telecom-platform/docs/DEPLOYMENT.md

Deployment Guide

This guide covers deploying the TaaS Platform in different environments.

Table of Contents

1. Local Development
2. Docker Deployment
3. Kubernetes Deployment
4. Production Considerations

---

Local Development

Prerequisites

• Go 1.26+
• Rust 1.94+
• Node.js 22+
• MongoDB 7.0+
• Redis 7+
• pnpm

Quick Start

# 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:

MONGODB_URI=mongodb://localhost:27017/free5gc
REDIS_URI=redis://localhost:6379
API_PORT=8000
GIN_MODE=debug

apps/charging-engine/.env:

REDIS_URI=redis://127.0.0.1/
SERVER_PORT=8080
RUST_LOG=info

apps/web-dashboard/.env.local:

NEXT_PUBLIC_API_URL=http://localhost:8000

---

Docker Deployment

Build Images

# 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

# 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:

# 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:

# 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

# 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

# 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

# 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

# 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

# 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:

# Use MongoDB Operator or StatefulSet
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: mongodb
spec:
  replicas: 3
  serviceName: mongodb
  # ... (see MongoDB Operator docs)

Redis Cluster:

# 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:

# 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:

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:

# 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:

# Daily backups with mongodump
kubectl create cronjob mongodb-backup \
  --image=mongo:7.0 \
  --schedule="0 2 * * *" \
  -- mongodump --uri=$MONGODB_URI --out=/backup

Redis Persistence:

# 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

# Install k6
brew install k6  # macOS
# or: sudo apt-get install k6

# Run load test
k6 run scripts/loadtest.js

Sample load test script:

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:

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
• Email: [email protected]