mirror of
https://github.com/andwati/telecom-platform.git
synced 2026-10-18 02:52:53 +00:00
docs: Restructure documentation with comprehensive architecture guide and new API reference
- Remove docs/API.md (237 lines) with TaaS-specific REST endpoints and SDK examples - Expand docs/ARCHITECTURE.md with detailed system overview, component architecture, data flow diagrams, scaling strategies, and RBAC security model - Add Table of Contents with 6 main sections: System Overview, Component Details, Data Flow, Scaling, Security & RBAC, Future Enhancements - Add detailed component descriptions
This commit is contained in:
nutcas3
-237
@@ -1,237 +0,0 @@
|
||||
# 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
|
||||
+199
-287
@@ -1,10 +1,21 @@
|
||||
# TaaS Platform Architecture
|
||||
# Architecture
|
||||
|
||||
Comprehensive overview of the TaaS Platform system design, components, data flow, security, and RBAC.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [System Overview](#system-overview)
|
||||
2. [Component Details](#component-details)
|
||||
3. [Data Flow](#data-flow)
|
||||
4. [Scaling](#scaling)
|
||||
5. [Security & RBAC](#security--rbac)
|
||||
6. [Future Enhancements](#future-enhancements)
|
||||
|
||||
## 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.
|
||||
The TaaS Platform is a multi-layer telecom infrastructure that provides cellular connectivity as a service, implementing 3GPP standards while exposing a modern, developer-friendly API.
|
||||
|
||||
## Architecture Layers
|
||||
### Architecture Layers
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
@@ -46,363 +57,264 @@ The TaaS Platform is a multi-layer telecom infrastructure that provides cellular
|
||||
|
||||
### 1. API Server (Go 1.26)
|
||||
|
||||
**Purpose**: Developer-facing RESTful API and business logic
|
||||
**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)
|
||||
**Stack**:
|
||||
- Gin framework
|
||||
- GORM with PostgreSQL (primary) / MongoDB (free5GC subscriber data)
|
||||
- Redis (session/cache)
|
||||
- Casbin for RBAC
|
||||
- WebSocket for real-time updates
|
||||
|
||||
**Responsibilities**:
|
||||
- eSIM creation and management
|
||||
- Authentication and authorization
|
||||
- Rate limiting and quotas
|
||||
- eSIM lifecycle management
|
||||
- Authentication (JWT) and authorization (Casbin)
|
||||
- Rate limiting, quotas, and performance monitoring
|
||||
- Webhook delivery
|
||||
- API documentation
|
||||
- Health checks and alerting
|
||||
|
||||
**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
|
||||
**Key Endpoints**:
|
||||
- `/v1/auth/*` — authentication
|
||||
- `/v1/esims/*` — eSIM management
|
||||
- `/v1/services/*` — service operations
|
||||
- `/v1/monitoring/*` — metrics & alerts
|
||||
- `/v1/billing/*` — invoicing
|
||||
- `/ws` — WebSocket stream
|
||||
- `/health`, `/ready`, `/live` — probes
|
||||
|
||||
### 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
|
||||
**Purpose**: Integration with GSMA SM-DP+ servers for eSIM provisioning.
|
||||
|
||||
**Flow**:
|
||||
1. Receive eSIM order from API Server
|
||||
2. Call SM-DP+ vendor API with IMSI, K, OPc keys
|
||||
2. Call SM-DP+ vendor API with IMSI, K, OPc keys (ES2+ over HTTPS)
|
||||
3. Receive activation code (LPA:1$...)
|
||||
4. Return to API Server for user display
|
||||
4. Return to API Server
|
||||
|
||||
Supports multiple vendors: Thales, G+D, Idemia.
|
||||
|
||||
### 3. Charging Engine (Rust 1.94)
|
||||
|
||||
**Purpose**: Real-time credit control and billing
|
||||
**Purpose**: Real-time credit control and billing.
|
||||
|
||||
**Technology**:
|
||||
- Language: Rust 1.94 (array_windows, async Tokio)
|
||||
- Framework: Axum
|
||||
- Database: Redis (in-memory credit balances)
|
||||
**Stack**:
|
||||
- Axum (async web framework)
|
||||
- Redis for in-memory credit balances
|
||||
- Atomic INCR/DECR operations
|
||||
|
||||
**Responsibilities**:
|
||||
- Credit balance management
|
||||
- Real-time authorization checks
|
||||
- Usage deduction (atomic operations)
|
||||
- Credit top-up processing
|
||||
**Endpoints**:
|
||||
- `POST /v1/credit/:ip/check` — authorization
|
||||
- `POST /v1/credit/:ip/deduct` — usage deduction
|
||||
- `POST /v1/credit/:ip/add` — top-up
|
||||
- `GET /v1/credit/:ip/balance` — balance query
|
||||
|
||||
**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
|
||||
**Performance**: Sub-millisecond p99, horizontally scalable via Redis Cluster.
|
||||
|
||||
### 4. Packet Gateway (Rust 1.94 + eBPF)
|
||||
|
||||
**Purpose**: High-performance packet processing and traffic control
|
||||
**Purpose**: High-performance packet processing at line rate.
|
||||
|
||||
**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
|
||||
**Stack**:
|
||||
- Aya (pure Rust eBPF)
|
||||
- XDP (eXpress Data Path) hook
|
||||
- GTP-U decapsulation (UDP 2152)
|
||||
|
||||
**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) │
|
||||
└───────────────────┘
|
||||
NIC → XDP Hook (kernel eBPF) → eBPF Maps → Userspace Daemon → Redis
|
||||
```
|
||||
|
||||
**Packet Processing**:
|
||||
**Packet flow**:
|
||||
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
|
||||
2. XDP inspects Ethernet → IP → UDP → GTP-U headers
|
||||
3. Extract inner IP (user data), look up credit in eBPF map
|
||||
4. If credit > 0: `XDP_PASS`; else: `XDP_DROP`
|
||||
5. Userspace daemon syncs byte counters to Redis every 1s
|
||||
|
||||
### 5. 5G Core Network (free5GC)
|
||||
### 5. 5G Core Network (free5GC v4.2.1)
|
||||
|
||||
**Purpose**: 3GPP-compliant 5G standalone core
|
||||
3GPP-compliant 5G standalone core with all network functions (AMF, SMF, UPF, PCF, UDM, UDR, AUSF, NRF).
|
||||
|
||||
**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**:
|
||||
**Integration**:
|
||||
- API Server writes subscriber data to MongoDB
|
||||
- UPF forwards GTP-U traffic to Packet Gateway
|
||||
- AMF handles UE authentication using stored keys (K, OPc)
|
||||
- UPF forwards GTP-U to Packet Gateway
|
||||
- AMF authenticates using stored K/OPc keys
|
||||
|
||||
### 6. Web Dashboard (Next.js 15)
|
||||
|
||||
**Purpose**: Developer portal and management interface
|
||||
- App Router, TypeScript, Tailwind CSS
|
||||
- TanStack Query for data fetching
|
||||
- Real-time updates via WebSocket
|
||||
- Error boundaries and loading states
|
||||
|
||||
**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
|
||||
**Pages**: eSIM management, services, monitoring, billing, config, chaos engineering, plugins, automation.
|
||||
|
||||
## Data Flow
|
||||
|
||||
### eSIM Creation Flow
|
||||
### eSIM Creation
|
||||
|
||||
```
|
||||
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
|
||||
1. Developer → API Server: POST /v1/esims { data_plan: "1GB" }
|
||||
2. API Server → IMSI Allocator: generate 15-digit IMSI
|
||||
3. API Server → Key Generator: K + OPc
|
||||
4. API Server → MongoDB: insert subscriptionData
|
||||
5. API Server → Carrier Connector: order via ES2+
|
||||
6. Carrier Connector → SM-DP+: HTTPS POST (IMSI, K, OPc)
|
||||
7. SM-DP+ → Carrier Connector: activation code (LPA:1$...)
|
||||
8. API Server → Developer: eSIM + activation code
|
||||
9. End User scans QR → SM-DP+: profile download
|
||||
10. Device → free5GC AMF: 5G AKA registration
|
||||
11. free5GC → Packet Gateway: GTP-U tunnel established
|
||||
```
|
||||
|
||||
### Real-Time Usage Flow
|
||||
### Real-Time Usage
|
||||
|
||||
```
|
||||
1. User Device sends data
|
||||
↓
|
||||
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
|
||||
3. Packet Gateway (eBPF XDP):
|
||||
- Decapsulate, extract user IP
|
||||
- Check credit in eBPF map
|
||||
4. If credit > 0: XDP_PASS + increment byte counter
|
||||
5. Userspace daemon: read eBPF maps → Redis (1s interval)
|
||||
6. Charging Engine: deduct from credit balance
|
||||
7. Packet Gateway: reload credit status from Redis → eBPF map
|
||||
8. If credit = 0: XDP_DROP (user traffic stops)
|
||||
```
|
||||
|
||||
## Scaling Architecture
|
||||
## Scaling
|
||||
|
||||
### Horizontal Scaling
|
||||
### Horizontal (Stateless)
|
||||
|
||||
**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
|
||||
### Stateful
|
||||
|
||||
### Performance Metrics
|
||||
- MongoDB: replica set (1 primary, 2 secondaries)
|
||||
- PostgreSQL: primary + streaming replicas
|
||||
- Redis: Cluster or Sentinel
|
||||
- Packet Gateway: one per physical server (eBPF kernel binding)
|
||||
- free5GC: K8s deployment with dedicated UPF nodes
|
||||
|
||||
**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
|
||||
### Performance Targets
|
||||
|
||||
**Latency**:
|
||||
- API Server: <50ms p99
|
||||
- Charging Engine: <1ms p99 (Redis)
|
||||
- Packet Gateway: <1µs (eBPF in kernel)
|
||||
- eSIM Provisioning: <2 seconds end-to-end
|
||||
| Component | Throughput | Latency (p99) |
|
||||
|-----------|-----------|----------------|
|
||||
| API Server | 10,000 req/s | <100ms |
|
||||
| Charging Engine | 50,000 checks/s | <1ms |
|
||||
| Packet Gateway | 10+ Gbps/server | <1µs (kernel) |
|
||||
| free5GC UPF | 5 Gbps/instance | — |
|
||||
| eSIM provisioning | — | <2s end-to-end |
|
||||
|
||||
## Security
|
||||
## Security & RBAC
|
||||
|
||||
### Authentication & Authorization
|
||||
- API keys with HMAC signatures
|
||||
- JWT tokens for web dashboard
|
||||
- OAuth 2.0 for third-party integrations
|
||||
- Rate limiting per API key
|
||||
### Authentication
|
||||
|
||||
- **JWT** tokens for web dashboard and API
|
||||
- **API keys** with HMAC signatures for programmatic access
|
||||
- **OAuth 2.0** for third-party integrations
|
||||
- **Refresh tokens** for long-lived sessions
|
||||
|
||||
JWT middleware (`@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/middleware/auth.go`) validates tokens on all protected routes.
|
||||
|
||||
### RBAC with Casbin
|
||||
|
||||
Sophisticated policy-based access control using Casbin with a GORM adapter for persistent policies.
|
||||
|
||||
**Request flow**:
|
||||
```
|
||||
Request → AuthMiddleware (JWT) → CasbinRBAC (policy check) → Handler
|
||||
```
|
||||
|
||||
**Model** (in `@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/rbac/casbin.go`):
|
||||
|
||||
```
|
||||
[request_definition]
|
||||
r = sub, obj, act
|
||||
|
||||
[policy_definition]
|
||||
p = sub, obj, act
|
||||
|
||||
[role_definition]
|
||||
g = _, _
|
||||
|
||||
[policy_effect]
|
||||
e = some(where (p.eft == allow))
|
||||
|
||||
[matchers]
|
||||
m = g(r.sub, p.sub) && keyMatch(r.obj, p.obj) && (r.act == p.act || p.act == "*")
|
||||
```
|
||||
|
||||
**Default policies**:
|
||||
|
||||
| Role | Permissions |
|
||||
|------|-------------|
|
||||
| `admin` | All resources, all actions |
|
||||
| `operator` | Services, monitoring, deployments (GET/POST) |
|
||||
| `viewer` | Read-only on all resources |
|
||||
|
||||
**Usage in routes**:
|
||||
```go
|
||||
users := protected.Group("/users")
|
||||
if casbinSvc != nil {
|
||||
users.Use(middleware.RequireCasbinPermission(casbinSvc, "/v1/users", "GET"))
|
||||
} else {
|
||||
users.Use(middleware.RequireRole("admin")) // fallback
|
||||
}
|
||||
```
|
||||
|
||||
**Policy management**:
|
||||
```go
|
||||
casbinSvc.AddPolicy("operator", "/v1/services/*", "GET")
|
||||
casbinSvc.AddRoleForUser("user123", "operator")
|
||||
allowed, err := casbinSvc.CheckPermission(userID, "/v1/services", "GET")
|
||||
```
|
||||
|
||||
### 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
|
||||
- TLS 1.3 for all API endpoints
|
||||
- MongoDB/PostgreSQL encryption at rest
|
||||
- Redis TLS connections
|
||||
- Secrets via Kubernetes Secrets or HashiCorp Vault
|
||||
- No hardcoded credentials
|
||||
|
||||
## Deployment
|
||||
### Security Headers
|
||||
|
||||
### Development
|
||||
```bash
|
||||
make all # Build all components
|
||||
make db-setup # Set up MongoDB + Redis
|
||||
make dev # Start all services
|
||||
Applied globally via middleware:
|
||||
|
||||
```
|
||||
X-Content-Type-Options: nosniff
|
||||
X-Frame-Options: DENY
|
||||
X-XSS-Protection: 1; mode=block
|
||||
Strict-Transport-Security: max-age=31536000; includeSubDomains
|
||||
```
|
||||
|
||||
### Docker Compose
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
Plus request size limit (10MB), request timeout (30s), and CORS configuration.
|
||||
|
||||
### Kubernetes
|
||||
```bash
|
||||
kubectl apply -f deployments/kubernetes/
|
||||
```
|
||||
### Rate Limiting
|
||||
|
||||
### 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)
|
||||
Tiered limits protect against abuse (see `@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/middleware/ratelimit.go`):
|
||||
|
||||
## 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%)
|
||||
| Tier | Limit/min | Burst |
|
||||
|------|-----------|-------|
|
||||
| Auth | 10 | 5 |
|
||||
| Read | 200 | 50 |
|
||||
| Admin | 50 | 10 |
|
||||
| Default | 100 | 20 |
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
1. **Multi-Region Deployment**
|
||||
- Deploy in multiple AWS regions
|
||||
- Global load balancing with Route 53
|
||||
- Data residency compliance
|
||||
1. **Multi-region deployment** — AWS multi-region with Route 53 global LB and data residency compliance.
|
||||
2. **Advanced analytics** — predictive usage forecasting, anomaly detection.
|
||||
3. **Additional carriers** — multi-vendor SM-DP+ with fallback.
|
||||
4. **IoT optimization** — SGP.32 (IoT eSIM), NB-IoT/LTE-M, power-saving features.
|
||||
5. **Developer tools** — expanded CLI, Terraform provider, GitHub Actions integration.
|
||||
|
||||
2. **Advanced Analytics**
|
||||
- Real-time dashboards with WebSockets
|
||||
- Predictive usage forecasting
|
||||
- Anomaly detection (unusual data patterns)
|
||||
## Related Docs
|
||||
|
||||
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
|
||||
- [`GETTING_STARTED.md`](./GETTING_STARTED.md) — Setup, API reference, SDKs
|
||||
- [`OPERATIONS.md`](./OPERATIONS.md) — Deployment, monitoring, performance tuning
|
||||
|
||||
@@ -1,454 +0,0 @@
|
||||
# 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
|
||||
@@ -0,0 +1,299 @@
|
||||
# Getting Started
|
||||
|
||||
This guide helps you get the Telecom-as-a-Service (TaaS) platform running locally and make your first API call.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker & Docker Compose
|
||||
- Go 1.26+
|
||||
- Rust 1.94+
|
||||
- Node.js 22+
|
||||
- MongoDB 7.0+ / PostgreSQL 15+
|
||||
- Redis 7+
|
||||
- pnpm
|
||||
- Make
|
||||
|
||||
## Quick Start (Docker Compose)
|
||||
|
||||
The fastest path to a running platform:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/nutcas3/telecom-platform.git
|
||||
cd telecom-platform
|
||||
|
||||
# Install deps and start core services
|
||||
make install-deps
|
||||
docker-compose up -d mongodb redis
|
||||
make free5gc-start
|
||||
docker-compose up -d api-server charging-engine carrier-connector
|
||||
|
||||
# Start the dashboard
|
||||
make dev-ui
|
||||
|
||||
# Verify everything is running
|
||||
make verify
|
||||
```
|
||||
|
||||
### Service URLs
|
||||
|
||||
| Service | URL |
|
||||
|---------|-----|
|
||||
| Web Dashboard | http://localhost:3000 |
|
||||
| API Server | http://localhost:8000 |
|
||||
| Charging Engine | http://localhost:8080 |
|
||||
| MongoDB | mongodb://localhost:27017 |
|
||||
| Redis | redis://localhost:6379 |
|
||||
|
||||
## Local Development (Without Docker)
|
||||
|
||||
```bash
|
||||
# 1. Setup
|
||||
chmod +x scripts/dev-setup.sh
|
||||
./scripts/dev-setup.sh
|
||||
make db-setup
|
||||
make all
|
||||
|
||||
# 2. Start services (separate terminals)
|
||||
./dist/api-server
|
||||
./dist/carrier-connector
|
||||
./target/release/charging-engine
|
||||
cd apps/web-dashboard && pnpm dev
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
**`apps/api-server/.env`:**
|
||||
```env
|
||||
MONGODB_URI=mongodb://localhost:27017/free5gc
|
||||
REDIS_URI=redis://localhost:6379
|
||||
API_PORT=8000
|
||||
GIN_MODE=debug
|
||||
JWT_SECRET=your-dev-secret
|
||||
```
|
||||
|
||||
**`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
|
||||
```
|
||||
|
||||
## Your First API Call
|
||||
|
||||
### 1. Authenticate
|
||||
|
||||
```bash
|
||||
# Register
|
||||
curl -X POST http://localhost:8000/v1/auth/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"username": "admin",
|
||||
"email": "[email protected]",
|
||||
"password": "password123",
|
||||
"first_name": "Admin",
|
||||
"last_name": "User"
|
||||
}'
|
||||
|
||||
# Login
|
||||
TOKEN=$(curl -s -X POST http://localhost:8000/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email":"[email protected]","password":"password123"}' \
|
||||
| jq -r .token)
|
||||
```
|
||||
|
||||
### 2. Create an eSIM
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/v1/esims \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"data_plan": "1GB",
|
||||
"country_code": "US"
|
||||
}'
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"esim_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"imsi": "208930000000001",
|
||||
"iccid": "8933123456789012345",
|
||||
"activation_code": "LPA:1$smdp.example.com$MATCHING_ID",
|
||||
"status": "provisioned"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Check Usage
|
||||
|
||||
```bash
|
||||
curl http://localhost:8000/v1/esims/$ESIM_ID/usage \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### Base URL
|
||||
|
||||
- Production: `https://api.taas-platform.com/v1`
|
||||
- Development: `http://localhost:8000/v1`
|
||||
|
||||
### Authentication
|
||||
|
||||
All protected endpoints require a Bearer token:
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer $TOKEN" ...
|
||||
```
|
||||
|
||||
### Core Endpoints
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/health` | System health |
|
||||
| GET | `/ready` | Readiness probe |
|
||||
| GET | `/live` | Liveness probe |
|
||||
| POST | `/v1/auth/register` | Create user |
|
||||
| POST | `/v1/auth/login` | Obtain tokens |
|
||||
| POST | `/v1/auth/refresh` | Refresh access token |
|
||||
| POST | `/v1/esims` | Create eSIM |
|
||||
| GET | `/v1/esims/:id` | Get eSIM |
|
||||
| GET | `/v1/esims/:id/usage` | Get usage |
|
||||
| DELETE | `/v1/esims/:id` | Terminate eSIM |
|
||||
| GET | `/v1/services` | List services |
|
||||
| GET | `/v1/monitoring/metrics` | System metrics |
|
||||
| GET | `/v1/monitoring/alerts` | Active alerts |
|
||||
| GET | `/v1/billing/invoices` | List invoices |
|
||||
| GET | `/v1/config` | Get config |
|
||||
| GET | `/metrics/performance` | Performance stats |
|
||||
| GET | `/ws` | WebSocket real-time updates |
|
||||
|
||||
### Status Codes
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| 200 | Success |
|
||||
| 201 | Created |
|
||||
| 400 | Bad request |
|
||||
| 401 | Unauthorized |
|
||||
| 403 | Forbidden |
|
||||
| 404 | Not found |
|
||||
| 429 | Rate limited |
|
||||
| 500 | Server error |
|
||||
| 503 | Service unavailable |
|
||||
|
||||
### Rate Limits
|
||||
|
||||
| Tier | Limit | Burst |
|
||||
|------|-------|-------|
|
||||
| Auth endpoints | 10/min | 5 |
|
||||
| Read endpoints | 200/min | 50 |
|
||||
| Admin endpoints | 50/min | 10 |
|
||||
| Default | 100/min | 20 |
|
||||
|
||||
Response headers include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
|
||||
|
||||
## SDKs
|
||||
|
||||
### TypeScript
|
||||
|
||||
```bash
|
||||
npm install @taas-platform/sdk
|
||||
```
|
||||
|
||||
```typescript
|
||||
import { TaasClient } from '@taas-platform/sdk';
|
||||
|
||||
const client = new TaasClient({ apiKey: process.env.TAAS_API_KEY });
|
||||
const esim = await client.esims.create({ dataPlan: '1GB', countryCode: 'US' });
|
||||
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(os.Getenv("TAAS_API_KEY"))
|
||||
esim, err := client.ESims.Create(&taas.CreateESIMRequest{
|
||||
DataPlan: "1GB",
|
||||
CountryCode: "US",
|
||||
})
|
||||
```
|
||||
|
||||
## Webhooks
|
||||
|
||||
Configure webhooks to receive real-time events:
|
||||
|
||||
| Event | Trigger |
|
||||
|-------|---------|
|
||||
| `esim.created` | New eSIM provisioned |
|
||||
| `esim.activated` | eSIM activated on device |
|
||||
| `usage.threshold` | 50%/75%/90% of data used |
|
||||
| `usage.depleted` | Data plan exhausted |
|
||||
| `esim.terminated` | eSIM terminated |
|
||||
|
||||
**Payload example:**
|
||||
```json
|
||||
{
|
||||
"event": "usage.threshold",
|
||||
"timestamp": "2026-04-01T12:00:00Z",
|
||||
"data": {
|
||||
"esim_id": "550e8400-...",
|
||||
"threshold": 75,
|
||||
"data_used": 805306368,
|
||||
"data_limit": 1073741824
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Common Commands
|
||||
|
||||
```bash
|
||||
make help # List all targets
|
||||
make all # Build everything
|
||||
make verify # Check services
|
||||
make free5gc-logs # View free5GC logs
|
||||
make docker-build # Build Docker images
|
||||
make clean # Remove build artifacts
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Services won't start
|
||||
```bash
|
||||
docker-compose logs [service-name]
|
||||
docker-compose restart [service-name]
|
||||
```
|
||||
|
||||
### Port conflicts
|
||||
Ensure ports 3000, 8000, 8080, 27017, 6379 are free.
|
||||
|
||||
### Permission issues
|
||||
```bash
|
||||
chmod +x scripts/*.sh
|
||||
```
|
||||
|
||||
### Database connection errors
|
||||
- Verify MongoDB/PostgreSQL is running: `docker-compose ps`
|
||||
- Check connection strings in `.env`
|
||||
- For PostgreSQL: confirm `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME` are set
|
||||
|
||||
## Next Steps
|
||||
|
||||
- **Architecture**: See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for system design, RBAC, and security.
|
||||
- **Operations**: See [`OPERATIONS.md`](./OPERATIONS.md) for deployment, monitoring, and performance tuning.
|
||||
|
||||
## Support
|
||||
|
||||
- Issues: https://github.com/nutcas3/telecom-platform/issues
|
||||
- Discussions: https://github.com/nutcas3/telecom-platform/discussions
|
||||
@@ -0,0 +1,425 @@
|
||||
# Operations
|
||||
|
||||
Deployment, monitoring, performance tuning, and production operations for the TaaS Platform.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Docker Deployment](#docker-deployment)
|
||||
2. [Kubernetes Deployment](#kubernetes-deployment)
|
||||
3. [Production Considerations](#production-considerations)
|
||||
4. [Performance & Optimization](#performance--optimization)
|
||||
5. [Monitoring & Alerting](#monitoring--alerting)
|
||||
6. [CI/CD](#cicd)
|
||||
7. [Backup & Disaster Recovery](#backup--disaster-recovery)
|
||||
|
||||
## Docker Deployment
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
make docker-build
|
||||
# Or 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
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
docker-compose logs -f
|
||||
docker-compose down # Stop
|
||||
docker-compose down -v # Stop + remove volumes
|
||||
```
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
```bash
|
||||
# MongoDB
|
||||
docker-compose ps mongodb
|
||||
docker-compose logs mongodb
|
||||
docker exec -it taas-mongodb mongosh
|
||||
|
||||
# Redis
|
||||
docker exec -it taas-redis redis-cli ping
|
||||
```
|
||||
|
||||
## Kubernetes Deployment
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Kubernetes v1.28+
|
||||
- `kubectl` configured
|
||||
- Persistent storage provisioner
|
||||
- LoadBalancer or Ingress controller
|
||||
|
||||
### Deploy
|
||||
|
||||
```bash
|
||||
kubectl create namespace taas-platform
|
||||
kubectl apply -f deployments/kubernetes/
|
||||
kubectl get pods -n taas-platform
|
||||
```
|
||||
|
||||
### Access
|
||||
|
||||
```bash
|
||||
kubectl get svc api-server -n taas-platform
|
||||
kubectl port-forward -n taas-platform svc/api-server 8000:8000
|
||||
```
|
||||
|
||||
### Scale
|
||||
|
||||
```bash
|
||||
kubectl scale deployment api-server -n taas-platform --replicas=5
|
||||
kubectl autoscale deployment api-server -n taas-platform \
|
||||
--min=3 --max=10 --cpu-percent=70
|
||||
```
|
||||
|
||||
### Rolling Updates
|
||||
|
||||
```bash
|
||||
kubectl set image deployment/api-server \
|
||||
api-server=ghcr.io/nutcas3/telecom-platform/api-server:v2.0.0 \
|
||||
-n taas-platform
|
||||
kubectl rollout status deployment/api-server -n taas-platform
|
||||
kubectl rollout undo deployment/api-server -n taas-platform # rollback
|
||||
```
|
||||
|
||||
### Logs & Events
|
||||
|
||||
```bash
|
||||
kubectl logs -f deployment/api-server -n taas-platform
|
||||
kubectl describe pod <pod-name> -n taas-platform
|
||||
kubectl get events -n taas-platform --sort-by='.lastTimestamp'
|
||||
```
|
||||
|
||||
## Production Considerations
|
||||
|
||||
### High Availability
|
||||
|
||||
**PostgreSQL / MongoDB replica sets**:
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: StatefulSet
|
||||
metadata:
|
||||
name: mongodb
|
||||
spec:
|
||||
replicas: 3
|
||||
serviceName: mongodb
|
||||
# See MongoDB Operator docs for full config
|
||||
```
|
||||
|
||||
**Redis Cluster**:
|
||||
```bash
|
||||
helm install redis bitnami/redis-cluster \
|
||||
--namespace taas-platform \
|
||||
--set cluster.nodes=6 \
|
||||
--set cluster.replicas=1
|
||||
```
|
||||
|
||||
### Secrets Management
|
||||
|
||||
```bash
|
||||
kubectl create secret generic db-secret \
|
||||
--from-literal=username=admin \
|
||||
--from-literal=password='STRONG_PASSWORD' \
|
||||
-n taas-platform
|
||||
|
||||
kubectl create secret generic api-keys \
|
||||
--from-literal=jwt-secret="$(openssl rand -base64 32)" \
|
||||
-n taas-platform
|
||||
```
|
||||
|
||||
For production, prefer HashiCorp Vault or AWS Secrets Manager over raw K8s secrets.
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
### Resource Limits
|
||||
|
||||
| Service | CPU Request | CPU Limit | Mem Request | Mem Limit |
|
||||
|---------|------------:|----------:|------------:|----------:|
|
||||
| API Server | 100m | 500m | 128Mi | 512Mi |
|
||||
| Charging Engine | 100m | 1000m | 128Mi | 512Mi |
|
||||
| Packet Gateway | 250m | 2000m | 256Mi | 1Gi |
|
||||
| MongoDB | 250m | 1000m | 512Mi | 2Gi |
|
||||
| PostgreSQL | 250m | 1000m | 512Mi | 2Gi |
|
||||
| Redis | 100m | 500m | 256Mi | 2Gi |
|
||||
|
||||
## Performance & Optimization
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
In-memory sliding window with per-IP tracking. Configured via `middleware.RateLimitByEndpoint()` in `@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/middleware/ratelimit.go`.
|
||||
|
||||
| Tier | Limit/min | Burst | Applies To |
|
||||
|------|-----------|-------|------------|
|
||||
| Auth | 10 | 5 | `/v1/auth/login`, `/v1/auth/register` |
|
||||
| Read | 200 | 50 | `/v1/services`, `/v1/monitoring/metrics` |
|
||||
| Admin | 50 | 10 | `/v1/users`, `/v1/config` |
|
||||
| Default | 100 | 20 | Everything else |
|
||||
|
||||
### Caching
|
||||
|
||||
Layered in-memory LRU cache with TTL (`@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/cache/cache.go`):
|
||||
|
||||
| Namespace | TTL | Max Items | Use |
|
||||
|-----------|-----|-----------|-----|
|
||||
| `default` | 5 min | 1000 | General purpose |
|
||||
| `users` | 10 min | 500 | User data |
|
||||
| `services` | 2 min | 200 | Service info |
|
||||
| `metrics` | 1 min | 1000 | Monitoring data |
|
||||
|
||||
```go
|
||||
cache := cache.GetDefaultCache()
|
||||
cache.Set("key", value, 5*time.Minute)
|
||||
value, found := cache.Get("key")
|
||||
```
|
||||
|
||||
The cached database wrapper (`@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/database/cached.go`) provides `CachedFind`, `CachedFirst`, `InvalidateCache`.
|
||||
|
||||
### Connection Pooling
|
||||
|
||||
Tuned in `@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/database/database.go:50-54`:
|
||||
|
||||
```go
|
||||
sqlDB.SetMaxIdleConns(25) // minimum idle
|
||||
sqlDB.SetMaxOpenConns(100) // maximum open
|
||||
sqlDB.SetConnMaxLifetime(time.Hour)
|
||||
sqlDB.SetConnMaxIdleTime(30 * time.Minute)
|
||||
```
|
||||
|
||||
`db.PoolStats()` exposes live pool metrics for dashboards and alerts.
|
||||
|
||||
### Performance Middleware
|
||||
|
||||
Tracks response times, error rates, and slow requests (>100ms threshold). Adds:
|
||||
|
||||
- `X-Response-Time` header
|
||||
- `X-Request-ID` correlation ID
|
||||
- Security headers (CSP, HSTS, X-Frame-Options)
|
||||
- Request size limit (10MB) and timeout (30s)
|
||||
|
||||
**Metrics endpoint**: `GET /metrics/performance`
|
||||
|
||||
### Performance Targets
|
||||
|
||||
| Metric | Target |
|
||||
|--------|--------|
|
||||
| API response time (p50) | <50ms |
|
||||
| API response time (p99) | <100ms |
|
||||
| Uptime | 99.9% |
|
||||
| Error rate | <1% |
|
||||
| Test coverage | >80% |
|
||||
|
||||
### Load Testing
|
||||
|
||||
```bash
|
||||
brew install k6
|
||||
k6 run scripts/loadtest.js
|
||||
```
|
||||
|
||||
Sample script:
|
||||
```javascript
|
||||
import http from 'k6/http';
|
||||
import { check, sleep } from 'k6';
|
||||
|
||||
export const options = {
|
||||
stages: [
|
||||
{ duration: '2m', target: 100 },
|
||||
{ duration: '5m', target: 100 },
|
||||
{ duration: '2m', target: 200 },
|
||||
{ duration: '5m', target: 200 },
|
||||
{ duration: '2m', target: 0 },
|
||||
],
|
||||
};
|
||||
|
||||
export default function () {
|
||||
const res = http.get('http://api-server:8000/health');
|
||||
check(res, { 'status is 200': (r) => r.status === 200 });
|
||||
sleep(1);
|
||||
}
|
||||
```
|
||||
|
||||
## Monitoring & Alerting
|
||||
|
||||
### Health Checks
|
||||
|
||||
Three probe endpoints (`@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/monitoring/health.go`):
|
||||
|
||||
| Endpoint | Purpose |
|
||||
|----------|---------|
|
||||
| `/health` | Aggregated component health |
|
||||
| `/ready` | Kubernetes readiness probe |
|
||||
| `/live` | Kubernetes liveness probe |
|
||||
|
||||
Monitored components: **database**, **Prometheus**, **Kubernetes**, **system** (memory, goroutines, GC).
|
||||
|
||||
### Alert Rules
|
||||
|
||||
Default rules in `@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/monitoring/alerting.go`:
|
||||
|
||||
| Rule | Threshold | Severity |
|
||||
|------|-----------|----------|
|
||||
| System Health | Degraded/Unhealthy | Warning |
|
||||
| High Memory | >80% | Warning |
|
||||
| High Goroutines | >1000 | Warning |
|
||||
| DB Connection Utilization | >80% | Warning |
|
||||
|
||||
### Alert Notifiers
|
||||
|
||||
- **WebSocket** — real-time dashboard
|
||||
- **Log** — structured logs
|
||||
- **Composite** — multiple channels simultaneously
|
||||
|
||||
### Prometheus Metrics
|
||||
|
||||
Key exported metrics:
|
||||
- `api_requests_total` — total request count
|
||||
- `esim_creations_total` — eSIMs created
|
||||
- `data_usage_bytes_total` — cumulative data usage
|
||||
- `charging_checks_duration_seconds` — credit check latency histogram
|
||||
- `packet_gateway_packets_total` — packets processed
|
||||
|
||||
### Prometheus + Grafana Install
|
||||
|
||||
```bash
|
||||
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
|
||||
helm install prometheus prometheus-community/kube-prometheus-stack \
|
||||
-n monitoring --create-namespace
|
||||
```
|
||||
|
||||
### WebSocket Real-Time Events
|
||||
|
||||
`GET /ws` streams:
|
||||
- Service status updates
|
||||
- System metrics
|
||||
- Alert notifications
|
||||
|
||||
## CI/CD
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
Two workflows in `.github/workflows/`:
|
||||
|
||||
**`ci.yml`** — runs on every push/PR:
|
||||
- Go tests with PostgreSQL service container
|
||||
- `go vet` and `golangci-lint`
|
||||
- Web dashboard lint + typecheck + build
|
||||
- Docker image builds (on main)
|
||||
- Trivy security scan
|
||||
|
||||
**`deploy.yml`** — runs on main pushes and version tags:
|
||||
- Build + push images to GHCR
|
||||
- Deploy to staging (main branch)
|
||||
- Deploy to production (version tags)
|
||||
|
||||
Manual trigger via `workflow_dispatch` with environment input.
|
||||
|
||||
### Local Testing
|
||||
|
||||
```bash
|
||||
# Go tests with coverage
|
||||
cd apps/api-server
|
||||
go test ./... -v -race -coverprofile=coverage.out
|
||||
go tool cover -html=coverage.out
|
||||
|
||||
# Benchmarks
|
||||
go test -bench=. ./internal/middleware/
|
||||
go test -bench=. ./internal/monitoring/
|
||||
|
||||
# Linting
|
||||
golangci-lint run --timeout 5m
|
||||
go vet ./...
|
||||
go fix ./...
|
||||
```
|
||||
|
||||
## Backup & Disaster Recovery
|
||||
|
||||
### MongoDB Backup (CronJob)
|
||||
|
||||
```bash
|
||||
kubectl create cronjob mongodb-backup \
|
||||
--image=mongo:7.0 \
|
||||
--schedule="0 2 * * *" \
|
||||
-- mongodump --uri=$MONGODB_URI --out=/backup
|
||||
```
|
||||
|
||||
### Redis Persistence
|
||||
|
||||
Enable AOF for durability:
|
||||
```bash
|
||||
kubectl edit configmap redis-config -n taas-platform
|
||||
# Set: appendonly yes
|
||||
```
|
||||
|
||||
### Recovery Objectives
|
||||
|
||||
- **RTO** (Recovery Time Objective): <1 hour
|
||||
- **RPO** (Recovery Point Objective): <15 minutes
|
||||
|
||||
### Recovery Procedure
|
||||
|
||||
1. Spin up new Kubernetes cluster
|
||||
2. Restore database from latest backup (cross-region replicated)
|
||||
3. Restore Redis from RDB snapshot or rebuild from DB
|
||||
4. Deploy all services from Git (`kubectl apply -f deployments/kubernetes/`)
|
||||
5. Update DNS to new cluster
|
||||
6. Run `make verify` to confirm functionality
|
||||
|
||||
### Backup Locations
|
||||
|
||||
- **MongoDB/PostgreSQL**: S3 bucket with cross-region replication
|
||||
- **Redis**: S3 RDB snapshots
|
||||
- **Configuration**: Git repository
|
||||
- **Secrets**: HashiCorp Vault / AWS Secrets Manager
|
||||
|
||||
## Cost Optimization
|
||||
|
||||
- Use spot/preemptible instances for non-critical services
|
||||
- Enable autoscaling to match load
|
||||
- Reserved instances for predictable workloads
|
||||
- Store old backups in S3 Glacier
|
||||
|
||||
**Sample monthly costs (AWS, base infrastructure)**:
|
||||
- 3× t3.medium (API Server): $90
|
||||
- 2× t3.medium (Charging Engine): $60
|
||||
- 1× t3.large (MongoDB): $75
|
||||
- 1× t3.small (Redis): $19
|
||||
- Load Balancer: $25
|
||||
- **Total**: ~$270/month + data transfer
|
||||
|
||||
## Related Docs
|
||||
|
||||
- [`GETTING_STARTED.md`](./GETTING_STARTED.md) — Setup and API reference
|
||||
- [`ARCHITECTURE.md`](./ARCHITECTURE.md) — System design, RBAC, security
|
||||
@@ -1,121 +0,0 @@
|
||||
# Quick Start Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This guide will help you get the Telecom-as-a-Service platform running in minutes.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker & Docker Compose
|
||||
- Make command
|
||||
- Terminal access
|
||||
|
||||
## 1. Initial Setup
|
||||
|
||||
```bash
|
||||
# Clone the repository (if not already done)
|
||||
git clone https://github.com/nutcas3/telecom-platform.git
|
||||
cd telecom-platform
|
||||
|
||||
# Install dependencies
|
||||
make install-deps
|
||||
```
|
||||
|
||||
## 2. Start Core Services
|
||||
|
||||
```bash
|
||||
# Start databases and core services
|
||||
docker-compose up -d mongodb redis
|
||||
|
||||
# Start free5GC core network
|
||||
make free5gc-start
|
||||
|
||||
# Start application services
|
||||
docker-compose up -d api-server charging-engine carrier-connector
|
||||
```
|
||||
|
||||
## 3. Start Development Server
|
||||
|
||||
```bash
|
||||
# Start web dashboard
|
||||
make dev-ui
|
||||
```
|
||||
|
||||
## 4. Verify Deployment
|
||||
|
||||
```bash
|
||||
# Check all services status
|
||||
make verify
|
||||
|
||||
# Test free5GC configuration
|
||||
make free5gc-test
|
||||
```
|
||||
|
||||
## 5. Access Services
|
||||
|
||||
- **Web Dashboard**: http://localhost:3000
|
||||
- **API Server**: http://localhost:8000
|
||||
- **Charging Engine**: http://localhost:8080
|
||||
|
||||
## 6. Common Commands
|
||||
|
||||
```bash
|
||||
# View free5GC logs
|
||||
make free5gc-logs
|
||||
|
||||
# Stop all services
|
||||
docker-compose down
|
||||
|
||||
# Rebuild services
|
||||
make docker-build
|
||||
|
||||
# Clean everything
|
||||
make clean
|
||||
```
|
||||
|
||||
## Service Architecture
|
||||
|
||||
```
|
||||
Internet
|
||||
|
|
||||
[Web Dashboard] - [API Server] - [Carrier Connector]
|
||||
| | |
|
||||
| [Charging Engine] |
|
||||
| | |
|
||||
+-----------[free5GC Core]-----+
|
||||
|
|
||||
[MongoDB] [Redis]
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Services Not Starting
|
||||
```bash
|
||||
# Check logs
|
||||
docker-compose logs [service-name]
|
||||
|
||||
# Restart specific service
|
||||
docker-compose restart [service-name]
|
||||
```
|
||||
|
||||
### Port Conflicts
|
||||
Ensure ports 3000, 8000, 8080, 27017, 6379 are available.
|
||||
|
||||
### Permission Issues
|
||||
```bash
|
||||
# Fix script permissions
|
||||
chmod +x scripts/*.sh
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Explore the API documentation at `/docs/API.md`
|
||||
2. Configure your first subscriber in the web dashboard
|
||||
3. Test the charging engine with sample data
|
||||
4. Deploy to Kubernetes using the provided manifests
|
||||
|
||||
## Support
|
||||
|
||||
- Check `make help` for all available commands
|
||||
- Review `docs/DEPLOYMENT.md` for production deployment
|
||||
- Check `todos.md` for development roadmap
|
||||
Reference in New Issue
Block a user