mirror of
https://github.com/andwati/telecom-platform.git
synced 2026-10-27 23:22:15 +00:00
feat: Initialize telecom platform with core services and infrastructure
- Add Go-based API server and carrier connector services - Add Rust-based charging engine and packet gateway services - Add Docker Compose configuration for local development - Add comprehensive documentation (API, Architecture, Deployment) - Add development scripts for Redis, MongoDB, and environment setup - Add workspace configuration for Go modules and pnpm - Remove unnecessary documentation files from web-dashboard - Add project build configuration (Makefile, Cargo.toml) This commit establishes the foundational microservices architecture for the sovereign Telecom-as-a-Service platform.
This commit is contained in:
nutcas3
+237
@@ -0,0 +1,237 @@
|
||||
# TaaS Platform API Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
The TaaS Platform provides a RESTful API for managing cellular connectivity programmatically. All API endpoints are available at `https://api.taas-platform.com/v1` (production) or `http://localhost:8000/v1` (development).
|
||||
|
||||
## Authentication
|
||||
|
||||
All API requests require authentication using Bearer tokens:
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer YOUR_API_KEY" \
|
||||
https://api.taas-platform.com/v1/esims
|
||||
```
|
||||
|
||||
Get your API key from the [Developer Dashboard](http://localhost:3000).
|
||||
|
||||
## Endpoints
|
||||
|
||||
### Health Check
|
||||
|
||||
**GET** `/health`
|
||||
|
||||
Check API server status.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"service": "api-server",
|
||||
"timestamp": 1711929600
|
||||
}
|
||||
```
|
||||
|
||||
### Create eSIM
|
||||
|
||||
**POST** `/v1/esims`
|
||||
|
||||
Provision a new eSIM with cellular connectivity.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"data_plan": "1GB",
|
||||
"country_code": "US",
|
||||
"carrier": "optional-carrier-name"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"esim_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"imsi": "208930000000001",
|
||||
"iccid": "8933123456789012345",
|
||||
"activation_code": "LPA:1$smdp.example.com$MATCHING_ID",
|
||||
"status": "provisioned",
|
||||
"data_plan": "1GB",
|
||||
"country_code": "US",
|
||||
"created_at": "2026-04-01T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Get eSIM Details
|
||||
|
||||
**GET** `/v1/esims/:id`
|
||||
|
||||
Retrieve information about a specific eSIM.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"esim_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"imsi": "208930000000001",
|
||||
"iccid": "8933123456789012345",
|
||||
"status": "active",
|
||||
"data_plan": "1GB",
|
||||
"created_at": "2026-04-01T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Get eSIM Usage
|
||||
|
||||
**GET** `/v1/esims/:id/usage`
|
||||
|
||||
Get data usage statistics for an eSIM.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"esim_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"data_used": 262144000,
|
||||
"data_limit": 1073741824,
|
||||
"sessions": [
|
||||
{
|
||||
"started_at": "2026-04-01T10:00:00Z",
|
||||
"ended_at": "2026-04-01T11:00:00Z",
|
||||
"bytes_up": 10485760,
|
||||
"bytes_down": 52428800
|
||||
}
|
||||
],
|
||||
"updated_at": "2026-04-01T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Terminate eSIM
|
||||
|
||||
**DELETE** `/v1/esims/:id`
|
||||
|
||||
Permanently terminate an eSIM.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"message": "eSIM terminated successfully",
|
||||
"esim_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
## Status Codes
|
||||
|
||||
- `200 OK` - Request successful
|
||||
- `201 Created` - Resource created
|
||||
- `400 Bad Request` - Invalid request parameters
|
||||
- `401 Unauthorized` - Missing or invalid authentication
|
||||
- `404 Not Found` - Resource not found
|
||||
- `500 Internal Server Error` - Server error
|
||||
|
||||
## Rate Limits
|
||||
|
||||
- **Free Tier**: 100 requests/hour
|
||||
- **Pro Tier**: 10,000 requests/hour
|
||||
- **Enterprise**: Unlimited
|
||||
|
||||
Rate limit headers are included in all responses:
|
||||
```
|
||||
X-RateLimit-Limit: 100
|
||||
X-RateLimit-Remaining: 99
|
||||
X-RateLimit-Reset: 1711933200
|
||||
```
|
||||
|
||||
## SDKs
|
||||
|
||||
### TypeScript/JavaScript
|
||||
|
||||
```bash
|
||||
npm install @taas-platform/sdk
|
||||
```
|
||||
|
||||
```typescript
|
||||
import { TaasClient } from '@taas-platform/sdk';
|
||||
|
||||
const client = new TaasClient({ apiKey: 'YOUR_API_KEY' });
|
||||
|
||||
// Create eSIM
|
||||
const esim = await client.esims.create({
|
||||
dataPlan: '1GB',
|
||||
countryCode: 'US'
|
||||
});
|
||||
|
||||
// Get usage
|
||||
const usage = await client.esims.getUsage(esim.esimId);
|
||||
```
|
||||
|
||||
### Go
|
||||
|
||||
```bash
|
||||
go get github.com/taas-platform/sdk-go
|
||||
```
|
||||
|
||||
```go
|
||||
import "github.com/taas-platform/sdk-go"
|
||||
|
||||
client := taas.NewClient("YOUR_API_KEY")
|
||||
|
||||
// Create eSIM
|
||||
esim, err := client.ESims.Create(&taas.CreateESIMRequest{
|
||||
DataPlan: "1GB",
|
||||
CountryCode: "US",
|
||||
})
|
||||
```
|
||||
|
||||
## Webhooks
|
||||
|
||||
Configure webhooks to receive real-time notifications:
|
||||
|
||||
### Events
|
||||
|
||||
- `esim.created` - New eSIM provisioned
|
||||
- `esim.activated` - eSIM activated on device
|
||||
- `usage.threshold` - Data usage threshold reached (50%, 75%, 90%)
|
||||
- `usage.depleted` - Data plan exhausted
|
||||
- `esim.terminated` - eSIM terminated
|
||||
|
||||
### Webhook Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "usage.threshold",
|
||||
"timestamp": "2026-04-01T12:00:00Z",
|
||||
"data": {
|
||||
"esim_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"threshold": 75,
|
||||
"data_used": 805306368,
|
||||
"data_limit": 1073741824
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Create and Activate eSIM
|
||||
|
||||
```bash
|
||||
# 1. Create eSIM
|
||||
curl -X POST https://api.taas-platform.com/v1/esims \
|
||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"data_plan": "1GB",
|
||||
"country_code": "US"
|
||||
}'
|
||||
|
||||
# 2. Show QR code to user (activation_code)
|
||||
# User scans QR code on their device
|
||||
|
||||
# 3. Monitor usage
|
||||
curl https://api.taas-platform.com/v1/esims/ESIM_ID/usage \
|
||||
-H "Authorization: Bearer YOUR_API_KEY"
|
||||
```
|
||||
|
||||
## Support
|
||||
|
||||
- **Documentation**: https://docs.taas-platform.com
|
||||
- **API Status**: https://status.taas-platform.com
|
||||
- **Support Email**: support@taas-platform.com
|
||||
- **GitHub Issues**: https://github.com/nutcas3/telecom-platform/issues
|
||||
@@ -0,0 +1,408 @@
|
||||
# TaaS Platform Architecture
|
||||
|
||||
## System Overview
|
||||
|
||||
The TaaS Platform is a multi-layer telecom infrastructure that provides cellular connectivity as a service. It implements 3GPP standards while exposing a modern, developer-friendly API.
|
||||
|
||||
## Architecture Layers
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Developer Interface │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Web UI │ │ TypeScript │ │ REST API │ │
|
||||
│ │ Dashboard │ │ SDK │ │ Webhooks │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Business Support System (BSS) │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ API Server │ │ Carrier │ │ Subscriber │ │
|
||||
│ │ (Go 1.26) │ │ Connector │ │ Management │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Operations Support System (OSS) │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Charging │ │ Usage │ │ eSIM │ │
|
||||
│ │ Engine │ │ Tracking │ │ Provisioning│ │
|
||||
│ │ (Rust) │ │ (Redis) │ │ (ES2+) │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Telecom Core Network │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ 5G Core │ │ Packet │ │ Data Plane │ │
|
||||
│ │ (free5GC) │ │ Gateway │ │ (eBPF) │ │
|
||||
│ │ (Go) │ │ (Rust) │ │ │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Component Details
|
||||
|
||||
### 1. API Server (Go 1.26)
|
||||
|
||||
**Purpose**: Developer-facing RESTful API and business logic
|
||||
|
||||
**Technology**:
|
||||
- Language: Go 1.26 (Green Tea GC, new(expr) syntax)
|
||||
- Framework: Gin
|
||||
- Database: MongoDB (subscriber data)
|
||||
- Cache: Redis (session management)
|
||||
|
||||
**Responsibilities**:
|
||||
- eSIM creation and management
|
||||
- Authentication and authorization
|
||||
- Rate limiting and quotas
|
||||
- Webhook delivery
|
||||
- API documentation
|
||||
|
||||
**Endpoints**:
|
||||
- `POST /v1/esims` - Create eSIM
|
||||
- `GET /v1/esims/:id` - Get eSIM details
|
||||
- `GET /v1/esims/:id/usage` - Get usage stats
|
||||
- `DELETE /v1/esims/:id` - Terminate eSIM
|
||||
|
||||
### 2. Carrier Connector (Go 1.26)
|
||||
|
||||
**Purpose**: Integration with GSMA SM-DP+ servers for eSIM provisioning
|
||||
|
||||
**Technology**:
|
||||
- Language: Go 1.26
|
||||
- Protocol: HTTPS (ES2+ API)
|
||||
- Vendor: Thales, G+D, or Idemia
|
||||
|
||||
**Responsibilities**:
|
||||
- Profile ordering via ES2+ protocol
|
||||
- Activation code generation (LPA strings)
|
||||
- Profile status tracking
|
||||
- Vendor-specific adaptations
|
||||
|
||||
**Flow**:
|
||||
1. Receive eSIM order from API Server
|
||||
2. Call SM-DP+ vendor API with IMSI, K, OPc keys
|
||||
3. Receive activation code (LPA:1$...)
|
||||
4. Return to API Server for user display
|
||||
|
||||
### 3. Charging Engine (Rust 1.94)
|
||||
|
||||
**Purpose**: Real-time credit control and billing
|
||||
|
||||
**Technology**:
|
||||
- Language: Rust 1.94 (array_windows, async Tokio)
|
||||
- Framework: Axum
|
||||
- Database: Redis (in-memory credit balances)
|
||||
|
||||
**Responsibilities**:
|
||||
- Credit balance management
|
||||
- Real-time authorization checks
|
||||
- Usage deduction (atomic operations)
|
||||
- Credit top-up processing
|
||||
|
||||
**API**:
|
||||
- `POST /v1/credit/:ip/check` - Check if user has credit
|
||||
- `POST /v1/credit/:ip/deduct` - Deduct bytes used
|
||||
- `POST /v1/credit/:ip/add` - Add credit
|
||||
- `GET /v1/credit/:ip/balance` - Get balance
|
||||
|
||||
**Performance**:
|
||||
- Sub-millisecond response times
|
||||
- Atomic Redis operations (INCR, DECR)
|
||||
- Horizontal scaling via Redis Cluster
|
||||
|
||||
### 4. Packet Gateway (Rust 1.94 + eBPF)
|
||||
|
||||
**Purpose**: High-performance packet processing and traffic control
|
||||
|
||||
**Technology**:
|
||||
- Language: Rust 1.94
|
||||
- Framework: Aya (pure Rust eBPF)
|
||||
- Attach Point: XDP (eXpress Data Path)
|
||||
- Protocol: GTP-U decapsulation (UDP port 2152)
|
||||
|
||||
**Responsibilities**:
|
||||
- Parse GTP-U tunneled packets
|
||||
- Extract user IP addresses
|
||||
- Count bytes per subscriber
|
||||
- Block traffic for users without credit
|
||||
- Sync stats to Redis
|
||||
|
||||
**Architecture**:
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ Network Interface (eth0) │
|
||||
└─────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────▼─────────┐
|
||||
│ XDP Hook │ ← eBPF program runs here
|
||||
│ (Kernel) │
|
||||
└─────────┬─────────┘
|
||||
│
|
||||
┌─────────▼─────────┐
|
||||
│ eBPF Maps │
|
||||
│ - Packet Stats │
|
||||
│ - Credit Status │
|
||||
└─────────┬─────────┘
|
||||
│
|
||||
┌─────────▼─────────┐
|
||||
│ Userspace Daemon │ ← Rust application
|
||||
│ (Reads maps, │
|
||||
│ syncs to Redis) │
|
||||
└───────────────────┘
|
||||
```
|
||||
|
||||
**Packet Processing**:
|
||||
1. Packet arrives at NIC
|
||||
2. XDP hook inspects Ethernet → IP → UDP → GTP-U headers
|
||||
3. Extract inner IP packet (actual user data)
|
||||
4. Look up credit status in eBPF map
|
||||
5. If credit > 0: `XDP_PASS`, else: `XDP_DROP`
|
||||
6. Update packet statistics in eBPF map
|
||||
7. Userspace daemon reads stats, syncs to Redis
|
||||
|
||||
### 5. 5G Core Network (free5GC)
|
||||
|
||||
**Purpose**: 3GPP-compliant 5G standalone core
|
||||
|
||||
**Technology**:
|
||||
- Project: free5GC v4.2.1
|
||||
- Language: Go
|
||||
- Database: MongoDB
|
||||
- Deployment: Kubernetes or bare metal
|
||||
|
||||
**Network Functions**:
|
||||
- **AMF** (Access and Mobility Management)
|
||||
- **SMF** (Session Management)
|
||||
- **UPF** (User Plane Function)
|
||||
- **PCF** (Policy Control)
|
||||
- **UDM** (Unified Data Management)
|
||||
- **UDR** (Unified Data Repository)
|
||||
- **AUSF** (Authentication Server)
|
||||
- **NRF** (NF Repository)
|
||||
|
||||
**Integration Points**:
|
||||
- API Server writes subscriber data to MongoDB
|
||||
- UPF forwards GTP-U traffic to Packet Gateway
|
||||
- AMF handles UE authentication using stored keys (K, OPc)
|
||||
|
||||
### 6. Web Dashboard (Next.js 15)
|
||||
|
||||
**Purpose**: Developer portal and management interface
|
||||
|
||||
**Technology**:
|
||||
- Framework: Next.js 15 (App Router)
|
||||
- Language: TypeScript
|
||||
- Styling: Tailwind CSS
|
||||
- Data Fetching: TanStack Query
|
||||
|
||||
**Features**:
|
||||
- eSIM creation and management
|
||||
- Real-time usage charts (Recharts)
|
||||
- API key management
|
||||
- Webhook configuration
|
||||
- Billing and invoices
|
||||
|
||||
## Data Flow
|
||||
|
||||
### eSIM Creation Flow
|
||||
|
||||
```
|
||||
1. Developer → API Server
|
||||
POST /v1/esims { data_plan: "1GB" }
|
||||
|
||||
2. API Server → IMSI Allocator
|
||||
Generate unique 15-digit IMSI
|
||||
|
||||
3. API Server → Key Generator
|
||||
Generate K (subscriber key)
|
||||
Generate OPc (operator key)
|
||||
|
||||
4. API Server → MongoDB (free5GC)
|
||||
Insert subscriber data:
|
||||
- subscriptionData.authenticationData (K, OPc)
|
||||
- subscriptionData.provisionedData (IMSI, AMBR)
|
||||
|
||||
5. API Server → Carrier Connector
|
||||
Order eSIM profile via ES2+
|
||||
|
||||
6. Carrier Connector → SM-DP+ Vendor
|
||||
HTTPS POST with IMSI, K, OPc
|
||||
|
||||
7. SM-DP+ → Carrier Connector
|
||||
Return activation code (LPA string)
|
||||
|
||||
8. API Server → Developer
|
||||
Return eSIM details + activation code
|
||||
|
||||
9. Developer → End User
|
||||
Display QR code with LPA string
|
||||
|
||||
10. End User's Device → SM-DP+
|
||||
Scan QR, download eSIM profile
|
||||
|
||||
11. Device → free5GC AMF
|
||||
Registration procedure (5G AKA)
|
||||
|
||||
12. free5GC → Packet Gateway
|
||||
Establish GTP-U tunnel for data
|
||||
```
|
||||
|
||||
### Real-Time Usage Flow
|
||||
|
||||
```
|
||||
1. User Device sends data
|
||||
↓
|
||||
2. free5GC UPF encapsulates in GTP-U
|
||||
↓
|
||||
3. Packet Gateway (eBPF XDP)
|
||||
- Decapsulate GTP-U
|
||||
- Extract user IP
|
||||
- Check credit status in eBPF map
|
||||
↓
|
||||
4. If credit > 0:
|
||||
- Pass packet (XDP_PASS)
|
||||
- Increment byte counter in eBPF map
|
||||
↓
|
||||
5. Userspace daemon (Rust)
|
||||
- Reads eBPF maps every 1 second
|
||||
- Writes stats to Redis
|
||||
↓
|
||||
6. Charging Engine
|
||||
- Reads usage from Redis
|
||||
- Deducts from credit balance
|
||||
- Updates credit status
|
||||
↓
|
||||
7. Packet Gateway
|
||||
- Reads new credit status from Redis
|
||||
- Updates eBPF map
|
||||
↓
|
||||
8. If credit reaches 0:
|
||||
- eBPF drops packets (XDP_DROP)
|
||||
- User's internet stops
|
||||
```
|
||||
|
||||
## Scaling Architecture
|
||||
|
||||
### Horizontal Scaling
|
||||
|
||||
**Stateless Components** (can be replicated):
|
||||
- API Server: 3+ replicas behind load balancer
|
||||
- Carrier Connector: 2+ replicas
|
||||
- Charging Engine: 2+ replicas
|
||||
- Web Dashboard: CDN + multiple origins
|
||||
|
||||
**Stateful Components** (require special handling):
|
||||
- MongoDB: Replica set (1 primary, 2 secondaries)
|
||||
- Redis: Cluster mode or Sentinel
|
||||
- Packet Gateway: One instance per physical server (eBPF)
|
||||
- free5GC: Kubernetes deployment with dedicated UPF nodes
|
||||
|
||||
### Performance Metrics
|
||||
|
||||
**Throughput**:
|
||||
- API Server: 10,000 requests/second
|
||||
- Charging Engine: 50,000 credit checks/second
|
||||
- Packet Gateway: 10 Gbps+ per server (eBPF)
|
||||
- free5GC UPF: 5 Gbps per instance
|
||||
|
||||
**Latency**:
|
||||
- API Server: <50ms p99
|
||||
- Charging Engine: <1ms p99 (Redis)
|
||||
- Packet Gateway: <1µs (eBPF in kernel)
|
||||
- eSIM Provisioning: <2 seconds end-to-end
|
||||
|
||||
## Security
|
||||
|
||||
### Authentication & Authorization
|
||||
- API keys with HMAC signatures
|
||||
- JWT tokens for web dashboard
|
||||
- OAuth 2.0 for third-party integrations
|
||||
- Rate limiting per API key
|
||||
|
||||
### Data Encryption
|
||||
- TLS 1.3 for all API endpoints
|
||||
- MongoDB encryption at rest
|
||||
- Redis TLS connections
|
||||
- eBPF packet inspection (no decryption)
|
||||
|
||||
### Secrets Management
|
||||
- Kubernetes Secrets for production
|
||||
- HashiCorp Vault for sensitive keys
|
||||
- Environment variables for local dev
|
||||
- No hardcoded credentials
|
||||
|
||||
## Deployment
|
||||
|
||||
### Development
|
||||
```bash
|
||||
make all # Build all components
|
||||
make db-setup # Set up MongoDB + Redis
|
||||
make dev # Start all services
|
||||
```
|
||||
|
||||
### Docker Compose
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### Kubernetes
|
||||
```bash
|
||||
kubectl apply -f deployments/kubernetes/
|
||||
```
|
||||
|
||||
### Production Checklist
|
||||
- [ ] MongoDB replica set configured
|
||||
- [ ] Redis Cluster or Sentinel enabled
|
||||
- [ ] TLS certificates installed
|
||||
- [ ] Monitoring (Prometheus, Grafana)
|
||||
- [ ] Logging (ELK Stack or Loki)
|
||||
- [ ] Backup strategy implemented
|
||||
- [ ] Disaster recovery plan documented
|
||||
- [ ] Load testing completed (10x expected traffic)
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Metrics (Prometheus)
|
||||
- `api_requests_total` - Total API requests
|
||||
- `esim_creations_total` - eSIMs created
|
||||
- `data_usage_bytes_total` - Total data usage
|
||||
- `charging_checks_duration_seconds` - Credit check latency
|
||||
- `packet_gateway_packets_total` - Packets processed
|
||||
|
||||
### Alerts
|
||||
- High error rate (>1%)
|
||||
- Low credit balances (<10% of users)
|
||||
- MongoDB replica lag (>10 seconds)
|
||||
- Redis memory usage (>90%)
|
||||
- Packet gateway packet loss (>0.1%)
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
1. **Multi-Region Deployment**
|
||||
- Deploy in multiple AWS regions
|
||||
- Global load balancing with Route 53
|
||||
- Data residency compliance
|
||||
|
||||
2. **Advanced Analytics**
|
||||
- Real-time dashboards with WebSockets
|
||||
- Predictive usage forecasting
|
||||
- Anomaly detection (unusual data patterns)
|
||||
|
||||
3. **Additional Carriers**
|
||||
- Support for multiple SM-DP+ vendors
|
||||
- Dynamic carrier selection based on region
|
||||
- Fallback mechanisms
|
||||
|
||||
4. **IoT Optimization**
|
||||
- SGP.32 support (IoT eSIM standard)
|
||||
- LPWAN protocol support (NB-IoT, LTE-M)
|
||||
- Power-saving features
|
||||
|
||||
5. **Developer Tools**
|
||||
- CLI tool for API interaction
|
||||
- Terraform provider
|
||||
- GitHub Actions integration
|
||||
@@ -0,0 +1,454 @@
|
||||
# Deployment Guide
|
||||
|
||||
This guide covers deploying the TaaS Platform in different environments.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Local Development](#local-development)
|
||||
2. [Docker Deployment](#docker-deployment)
|
||||
3. [Kubernetes Deployment](#kubernetes-deployment)
|
||||
4. [Production Considerations](#production-considerations)
|
||||
|
||||
---
|
||||
|
||||
## Local Development
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Go 1.26+
|
||||
- Rust 1.94+
|
||||
- Node.js 22+
|
||||
- MongoDB 7.0+
|
||||
- Redis 7+
|
||||
- pnpm
|
||||
|
||||
### Quick Start
|
||||
|
||||
```bash
|
||||
# 1. Clone repository
|
||||
git clone https://github.com/nutcas3/telecom-platform.git
|
||||
cd telecom-platform
|
||||
|
||||
# 2. Run setup script
|
||||
chmod +x scripts/dev-setup.sh
|
||||
./scripts/dev-setup.sh
|
||||
|
||||
# 3. Set up databases
|
||||
make db-setup
|
||||
|
||||
# 4. Build all components
|
||||
make all
|
||||
|
||||
# 5. Start services (in separate terminals)
|
||||
# Terminal 1: API Server
|
||||
./dist/api-server
|
||||
|
||||
# Terminal 2: Carrier Connector
|
||||
./dist/carrier-connector
|
||||
|
||||
# Terminal 3: Charging Engine
|
||||
./target/release/charging-engine
|
||||
|
||||
# Terminal 4: Web Dashboard
|
||||
cd apps/web-dashboard && pnpm dev
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Create `.env` files in each service directory:
|
||||
|
||||
**apps/api-server/.env:**
|
||||
```env
|
||||
MONGODB_URI=mongodb://localhost:27017/free5gc
|
||||
REDIS_URI=redis://localhost:6379
|
||||
API_PORT=8000
|
||||
GIN_MODE=debug
|
||||
```
|
||||
|
||||
**apps/charging-engine/.env:**
|
||||
```env
|
||||
REDIS_URI=redis://127.0.0.1/
|
||||
SERVER_PORT=8080
|
||||
RUST_LOG=info
|
||||
```
|
||||
|
||||
**apps/web-dashboard/.env.local:**
|
||||
```env
|
||||
NEXT_PUBLIC_API_URL=http://localhost:8000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Docker Deployment
|
||||
|
||||
### Build Images
|
||||
|
||||
```bash
|
||||
# Build all Docker images
|
||||
make docker-build
|
||||
|
||||
# Or build individually
|
||||
docker build -f deployments/docker/api-server.Dockerfile -t taas-api-server .
|
||||
docker build -f deployments/docker/charging-engine.Dockerfile -t taas-charging-engine .
|
||||
docker build -f deployments/docker/web-dashboard.Dockerfile -t taas-web-dashboard .
|
||||
```
|
||||
|
||||
### Run with Docker Compose
|
||||
|
||||
```bash
|
||||
# Start all services
|
||||
docker-compose up -d
|
||||
|
||||
# View logs
|
||||
docker-compose logs -f
|
||||
|
||||
# Stop all services
|
||||
docker-compose down
|
||||
|
||||
# Stop and remove volumes
|
||||
docker-compose down -v
|
||||
```
|
||||
|
||||
### Service URLs
|
||||
|
||||
After starting with docker-compose:
|
||||
|
||||
- **API Server**: http://localhost:8000
|
||||
- **Charging Engine**: http://localhost:8080
|
||||
- **Web Dashboard**: http://localhost:3000
|
||||
- **MongoDB**: mongodb://localhost:27017
|
||||
- **Redis**: redis://localhost:6379
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
**MongoDB connection issues:**
|
||||
```bash
|
||||
# Check if MongoDB is running
|
||||
docker-compose ps mongodb
|
||||
|
||||
# View MongoDB logs
|
||||
docker-compose logs mongodb
|
||||
|
||||
# Connect to MongoDB shell
|
||||
docker exec -it taas-mongodb mongosh
|
||||
```
|
||||
|
||||
**Redis connection issues:**
|
||||
```bash
|
||||
# Test Redis connection
|
||||
docker exec -it taas-redis redis-cli ping
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Kubernetes Deployment
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Kubernetes cluster (v1.28+)
|
||||
- kubectl configured
|
||||
- Persistent storage provisioner
|
||||
- LoadBalancer service support (or Ingress controller)
|
||||
|
||||
### Deploy to Kubernetes
|
||||
|
||||
```bash
|
||||
# 1. Create namespace
|
||||
kubectl create namespace taas-platform
|
||||
|
||||
# 2. Deploy all manifests
|
||||
kubectl apply -f deployments/kubernetes/
|
||||
|
||||
# 3. Verify deployments
|
||||
kubectl get pods -n taas-platform
|
||||
|
||||
# Expected output:
|
||||
# NAME READY STATUS RESTARTS AGE
|
||||
# mongodb-xxx 1/1 Running 0 2m
|
||||
# redis-xxx 1/1 Running 0 2m
|
||||
# api-server-xxx 1/1 Running 0 1m
|
||||
# charging-engine-xxx 1/1 Running 0 1m
|
||||
```
|
||||
|
||||
### Access Services
|
||||
|
||||
```bash
|
||||
# Get API Server external IP
|
||||
kubectl get svc api-server -n taas-platform
|
||||
|
||||
# Port forward for local access
|
||||
kubectl port-forward -n taas-platform svc/api-server 8000:8000
|
||||
kubectl port-forward -n taas-platform svc/charging-engine 8080:8080
|
||||
```
|
||||
|
||||
### Scaling
|
||||
|
||||
```bash
|
||||
# Scale API Server
|
||||
kubectl scale deployment api-server -n taas-platform --replicas=5
|
||||
|
||||
# Scale Charging Engine
|
||||
kubectl scale deployment charging-engine -n taas-platform --replicas=3
|
||||
|
||||
# Enable autoscaling
|
||||
kubectl autoscale deployment api-server -n taas-platform \
|
||||
--min=3 --max=10 --cpu-percent=70
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
|
||||
```bash
|
||||
# View logs
|
||||
kubectl logs -f deployment/api-server -n taas-platform
|
||||
|
||||
# Describe pod for issues
|
||||
kubectl describe pod <pod-name> -n taas-platform
|
||||
|
||||
# Get events
|
||||
kubectl get events -n taas-platform --sort-by='.lastTimestamp'
|
||||
```
|
||||
|
||||
### Update Deployment
|
||||
|
||||
```bash
|
||||
# Update image
|
||||
kubectl set image deployment/api-server \
|
||||
api-server=taas-api-server:v2.0.0 \
|
||||
-n taas-platform
|
||||
|
||||
# Check rollout status
|
||||
kubectl rollout status deployment/api-server -n taas-platform
|
||||
|
||||
# Rollback if needed
|
||||
kubectl rollout undo deployment/api-server -n taas-platform
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Production Considerations
|
||||
|
||||
### High Availability
|
||||
|
||||
**MongoDB Replica Set:**
|
||||
```yaml
|
||||
# Use MongoDB Operator or StatefulSet
|
||||
apiVersion: apps/v1
|
||||
kind: StatefulSet
|
||||
metadata:
|
||||
name: mongodb
|
||||
spec:
|
||||
replicas: 3
|
||||
serviceName: mongodb
|
||||
# ... (see MongoDB Operator docs)
|
||||
```
|
||||
|
||||
**Redis Cluster:**
|
||||
```bash
|
||||
# Deploy Redis in cluster mode
|
||||
helm install redis bitnami/redis-cluster \
|
||||
--namespace taas-platform \
|
||||
--set cluster.nodes=6 \
|
||||
--set cluster.replicas=1
|
||||
```
|
||||
|
||||
### Security
|
||||
|
||||
**Secrets Management:**
|
||||
```bash
|
||||
# Create Kubernetes secrets
|
||||
kubectl create secret generic mongodb-secret \
|
||||
--from-literal=username=admin \
|
||||
--from-literal=password='STRONG_PASSWORD' \
|
||||
-n taas-platform
|
||||
|
||||
kubectl create secret generic api-keys \
|
||||
--from-literal=jwt-secret='JWT_SECRET' \
|
||||
-n taas-platform
|
||||
```
|
||||
|
||||
**Network Policies:**
|
||||
```yaml
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: NetworkPolicy
|
||||
metadata:
|
||||
name: api-server-policy
|
||||
namespace: taas-platform
|
||||
spec:
|
||||
podSelector:
|
||||
matchLabels:
|
||||
app: api-server
|
||||
policyTypes:
|
||||
- Ingress
|
||||
- Egress
|
||||
ingress:
|
||||
- from:
|
||||
- podSelector:
|
||||
matchLabels:
|
||||
app: web-dashboard
|
||||
ports:
|
||||
- protocol: TCP
|
||||
port: 8000
|
||||
egress:
|
||||
- to:
|
||||
- podSelector:
|
||||
matchLabels:
|
||||
app: mongodb
|
||||
ports:
|
||||
- protocol: TCP
|
||||
port: 27017
|
||||
```
|
||||
|
||||
### Monitoring Stack
|
||||
|
||||
**Prometheus & Grafana:**
|
||||
```bash
|
||||
# Install using Helm
|
||||
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
|
||||
helm install prometheus prometheus-community/kube-prometheus-stack \
|
||||
-n monitoring --create-namespace
|
||||
```
|
||||
|
||||
**Application Metrics:**
|
||||
- Add `/metrics` endpoint to each service
|
||||
- Use Prometheus client libraries
|
||||
- Create Grafana dashboards
|
||||
|
||||
### Backup Strategy
|
||||
|
||||
**MongoDB Backups:**
|
||||
```bash
|
||||
# Daily backups with mongodump
|
||||
kubectl create cronjob mongodb-backup \
|
||||
--image=mongo:7.0 \
|
||||
--schedule="0 2 * * *" \
|
||||
-- mongodump --uri=$MONGODB_URI --out=/backup
|
||||
```
|
||||
|
||||
**Redis Persistence:**
|
||||
```bash
|
||||
# Enable AOF in Redis config
|
||||
kubectl edit configmap redis-config -n taas-platform
|
||||
# Set: appendonly yes
|
||||
```
|
||||
|
||||
### Resource Limits
|
||||
|
||||
**Recommended limits per service:**
|
||||
|
||||
| Service | CPU Request | CPU Limit | Memory Request | Memory Limit |
|
||||
|---------|-------------|-----------|----------------|--------------|
|
||||
| API Server | 100m | 500m | 128Mi | 512Mi |
|
||||
| Charging Engine | 100m | 1000m | 128Mi | 512Mi |
|
||||
| Packet Gateway | 250m | 2000m | 256Mi | 1Gi |
|
||||
| MongoDB | 250m | 1000m | 512Mi | 2Gi |
|
||||
| Redis | 100m | 500m | 256Mi | 2Gi |
|
||||
|
||||
### Load Testing
|
||||
|
||||
```bash
|
||||
# Install k6
|
||||
brew install k6 # macOS
|
||||
# or: sudo apt-get install k6
|
||||
|
||||
# Run load test
|
||||
k6 run scripts/loadtest.js
|
||||
```
|
||||
|
||||
**Sample load test script:**
|
||||
```javascript
|
||||
import http from 'k6/http';
|
||||
import { check, sleep } from 'k6';
|
||||
|
||||
export const options = {
|
||||
stages: [
|
||||
{ duration: '2m', target: 100 }, // Ramp up
|
||||
{ duration: '5m', target: 100 }, // Stay at 100 users
|
||||
{ duration: '2m', target: 200 }, // Ramp to 200
|
||||
{ duration: '5m', target: 200 }, // Stay at 200
|
||||
{ duration: '2m', target: 0 }, // Ramp down
|
||||
],
|
||||
};
|
||||
|
||||
export default function () {
|
||||
const res = http.get('http://api-server:8000/health');
|
||||
check(res, { 'status is 200': (r) => r.status === 200 });
|
||||
sleep(1);
|
||||
}
|
||||
```
|
||||
|
||||
### Disaster Recovery
|
||||
|
||||
**Backup Locations:**
|
||||
- MongoDB backups: S3 bucket (cross-region replication)
|
||||
- Redis RDB snapshots: S3 bucket
|
||||
- Configuration: Git repository
|
||||
- Secrets: HashiCorp Vault or AWS Secrets Manager
|
||||
|
||||
**Recovery Time Objective (RTO):** <1 hour
|
||||
**Recovery Point Objective (RPO):** <15 minutes
|
||||
|
||||
**Recovery Procedure:**
|
||||
1. Spin up new Kubernetes cluster
|
||||
2. Restore MongoDB from latest backup
|
||||
3. Restore Redis from snapshot
|
||||
4. Deploy all services from Git
|
||||
5. Update DNS to point to new cluster
|
||||
6. Verify functionality
|
||||
|
||||
### CI/CD Pipeline
|
||||
|
||||
**GitHub Actions example:**
|
||||
```yaml
|
||||
name: Deploy
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
build-and-deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- name: Build Docker images
|
||||
run: make docker-build
|
||||
|
||||
- name: Push to registry
|
||||
run: |
|
||||
docker tag taas-api-server registry.example.com/taas-api-server:${{ github.sha }}
|
||||
docker push registry.example.com/taas-api-server:${{ github.sha }}
|
||||
|
||||
- name: Deploy to Kubernetes
|
||||
run: |
|
||||
kubectl set image deployment/api-server \
|
||||
api-server=registry.example.com/taas-api-server:${{ github.sha }} \
|
||||
-n taas-platform
|
||||
```
|
||||
|
||||
### Cost Optimization
|
||||
|
||||
**Cloud Provider Recommendations:**
|
||||
- Use spot/preemptible instances for non-critical services
|
||||
- Enable autoscaling to match load
|
||||
- Use reserved instances for predictable workloads
|
||||
- Store backups in cheaper storage classes (S3 Glacier)
|
||||
|
||||
**Estimated Monthly Costs (AWS):**
|
||||
- 3x t3.medium (API Server): $90
|
||||
- 2x t3.medium (Charging Engine): $60
|
||||
- 1x t3.large (MongoDB): $75
|
||||
- 1x t3.small (Redis): $19
|
||||
- Load Balancer: $25
|
||||
- Data transfer: Variable
|
||||
- **Total**: ~$270/month (base infrastructure)
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
For deployment issues:
|
||||
- Check logs: `kubectl logs -f <pod-name>`
|
||||
- Review events: `kubectl get events`
|
||||
- Join community: [Discussions](https://github.com/taas-platform/discussions)
|
||||
- Email: devops@taas-platform.com
|
||||
Reference in New Issue
Block a user