docs/deployment.md

# Deployment Guide

## Overview

This guide covers deploying the Voice-to-Voice Translator in various environments, from local development to production cloud deployments.

## Prerequisites

### System Requirements

**Minimum**:
- CPU: 4 cores
- RAM: 4GB
- Storage: 10GB
- Network: 10 Mbps

**Recommended**:
- CPU: 8 cores or GPU (CUDA-capable)
- RAM: 8GB+
- Storage: 20GB SSD
- Network: 100 Mbps

### Software Requirements
- Python 3.9+
- pip or conda
- Docker (optional)
- Redis (optional, for scaling)

## Local Development Setup

### 1. Clone Repository
```bash
git clone <repository-url>
cd voice-to-voice-translator
```

### 2. Create Virtual Environment
```bash
# Using venv
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate  # Windows

# Using conda
conda create -n voice-translator python=3.9
conda activate voice-translator
```

### 3. Install Dependencies
```bash
pip install -r requirements.txt
```

### 4. Download Models
```bash
python scripts/download_models.py
```

This will download:
- Vosk models for English and Hindi (~500MB each)
- Argos Translate packages (~200MB per language pair)
- Coqui TTS models (~100MB per language)

### 5. Configure Environment
```bash
cp .env.example .env
```

Edit `.env`:
```ini
HOST=127.0.0.1
PORT=8000
DEBUG=True
LOG_LEVEL=DEBUG
```

### 6. Run Server
```bash
python app/main.py
```

Server will start at `ws://localhost:8000/ws`

### 7. Health Check
```bash
curl http://localhost:8000/health
```

## Docker Deployment

### Single Container

#### Build Image
```bash
docker build -f docker/Dockerfile -t voice-translator:latest .
```

#### Run Container
```bash
docker run -d \
  --name voice-translator \
  -p 8000:8000 \
  -v $(pwd)/models:/app/models \
  -e HOST=0.0.0.0 \
  -e PORT=8000 \
  voice-translator:latest
```

### Docker Compose

#### Configuration
```yaml
# docker-compose.yml
version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: docker/Dockerfile
    ports:
      - "8000:8000"
    volumes:
      - ./models:/app/models
      - ./logs:/app/logs
    environment:
      - HOST=0.0.0.0
      - PORT=8000
      - LOG_LEVEL=INFO
    restart: unless-stopped
```

#### Deploy
```bash
docker-compose up -d
```

#### View Logs
```bash
docker-compose logs -f app
```

#### Stop
```bash
docker-compose down
```

## Production Deployment

### Architecture Options

#### Option 1: Single Server
Best for: < 50 concurrent users

```
Internet → Load Balancer → Application Server
```

#### Option 2: Multi-Server with Load Balancer
Best for: 50-500 concurrent users

```
Internet → Load Balancer → [App Server 1, App Server 2, App Server N]
                              ↓
                         Shared Redis (for session state)
```

#### Option 3: Microservices
Best for: 500+ concurrent users

```
Internet → API Gateway → [WebSocket Servers]
                          ↓
                        Message Queue
                          ↓
          [STT Workers] [Translation Workers] [TTS Workers]
                          ↓
                      Shared Storage
```

### Cloud Deployment

#### AWS Deployment

**Using EC2**:

1. **Launch Instance**
```bash
# Ubuntu 22.04 LTS
# Instance type: t3.xlarge (4 vCPU, 16GB RAM)
# Storage: 30GB gp3
```

2. **Setup Script**
```bash
#!/bin/bash
# setup-aws.sh

# Update system
sudo apt-get update
sudo apt-get upgrade -y

# Install Python
sudo apt-get install -y python3.9 python3-pip python3-venv

# Install dependencies
sudo apt-get install -y build-essential libssl-dev libffi-dev
sudo apt-get install -y portaudio19-dev

# Clone and setup application
git clone <repository-url>
cd voice-to-voice-translator
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Download models
python scripts/download_models.py

# Setup systemd service
sudo cp deployment/voice-translator.service /etc/systemd/system/
sudo systemctl enable voice-translator
sudo systemctl start voice-translator
```

3. **Systemd Service**
```ini
# /etc/systemd/system/voice-translator.service
[Unit]
Description=Voice-to-Voice Translator
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/voice-to-voice-translator
Environment="PATH=/home/ubuntu/voice-to-voice-translator/venv/bin"
ExecStart=/home/ubuntu/voice-to-voice-translator/venv/bin/python app/main.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

4. **Application Load Balancer**
- Create ALB with WebSocket support
- Configure health check: `/health`
- Enable sticky sessions
- SSL/TLS termination

**Using ECS (Fargate)**:

1. **Create Task Definition**
```json
{
  "family": "voice-translator",
  "taskRoleArn": "arn:aws:iam::ACCOUNT:role/ecsTaskRole",
  "networkMode": "awsvpc",
  "containerDefinitions": [
    {
      "name": "app",
      "image": "ACCOUNT.dkr.ecr.REGION.amazonaws.com/voice-translator:latest",
      "cpu": 2048,
      "memory": 4096,
      "portMappings": [
        {
          "containerPort": 8000,
          "protocol": "tcp"
        }
      ],
      "environment": [
        {"name": "HOST", "value": "0.0.0.0"},
        {"name": "PORT", "value": "8000"}
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/voice-translator",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ],
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "2048",
  "memory": "4096"
}
```

#### Google Cloud Platform

**Using Compute Engine**:

```bash
# Create instance
gcloud compute instances create voice-translator \
  --image-family=ubuntu-2204-lts \
  --image-project=ubuntu-os-cloud \
  --machine-type=n1-standard-4 \
  --boot-disk-size=30GB \
  --tags=http-server,https-server

# SSH and setup
gcloud compute ssh voice-translator
# Run setup script (similar to AWS)
```

**Using Cloud Run**:

```bash
# Build and push
gcloud builds submit --tag gcr.io/PROJECT_ID/voice-translator

# Deploy
gcloud run deploy voice-translator \
  --image gcr.io/PROJECT_ID/voice-translator \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --memory 4Gi \
  --cpu 2 \
  --timeout 3600 \
  --use-http2
```

#### Azure Deployment

**Using Container Instances**:

```bash
# Create resource group
az group create --name voice-translator-rg --location eastus

# Create container
az container create \
  --resource-group voice-translator-rg \
  --name voice-translator \
  --image REGISTRY.azurecr.io/voice-translator:latest \
  --cpu 4 \
  --memory 8 \
  --ports 8000 \
  --environment-variables \
    HOST=0.0.0.0 \
    PORT=8000
```

### Kubernetes Deployment

#### Deployment YAML

```yaml
# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: voice-translator
spec:
  replicas: 3
  selector:
    matchLabels:
      app: voice-translator
  template:
    metadata:
      labels:
        app: voice-translator
    spec:
      containers:
      - name: app
        image: voice-translator:latest
        ports:
        - containerPort: 8000
        env:
        - name: HOST
          value: "0.0.0.0"
        - name: PORT
          value: "8000"
        - name: REDIS_URL
          value: "redis://redis-service:6379"
        resources:
          requests:
            memory: "4Gi"
            cpu: "2"
          limits:
            memory: "8Gi"
            cpu: "4"
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 10
          periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: voice-translator-service
spec:
  type: LoadBalancer
  selector:
    app: voice-translator
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8000
```

#### Deploy

```bash
kubectl apply -f k8s/deployment.yaml
kubectl get services
```

### Scaling Strategies

#### Horizontal Scaling

**Nginx Load Balancer**:

```nginx
# /etc/nginx/nginx.conf
upstream voice_translator {
    least_conn;  # Use least connections algorithm
    
    server 10.0.1.10:8000 max_fails=3 fail_timeout=30s;
    server 10.0.1.11:8000 max_fails=3 fail_timeout=30s;
    server 10.0.1.12:8000 max_fails=3 fail_timeout=30s;
}

map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

server {
    listen 80;
    server_name api.example.com;

    location /ws {
        proxy_pass http://voice_translator;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }

    location /health {
        proxy_pass http://voice_translator;
    }
}
```

#### Vertical Scaling

Increase resources per instance:
- More CPU cores
- More RAM
- GPU acceleration
- Faster storage (NVMe SSD)

### Monitoring and Logging

#### Prometheus Metrics

```python
# Add to main.py
from prometheus_client import Counter, Histogram, Gauge

requests_total = Counter('requests_total', 'Total requests')
latency = Histogram('request_latency_seconds', 'Request latency')
active_connections = Gauge('active_connections', 'Active WS connections')
```

#### Grafana Dashboard

Import dashboard from `monitoring/grafana-dashboard.json`

#### Log Aggregation

**ELK Stack**:
```yaml
# docker-compose.elk.yml
version: '3.8'
services:
  elasticsearch:
    image: elasticsearch:8.5.0
    environment:
      - discovery.type=single-node
    ports:
      - "9200:9200"
  
  logstash:
    image: logstash:8.5.0
    volumes:
      - ./logstash.conf:/usr/share/logstash/pipeline/logstash.conf
  
  kibana:
    image: kibana:8.5.0
    ports:
      - "5601:5601"
```

### Security Hardening

#### SSL/TLS Configuration

**Nginx with Let's Encrypt**:
```bash
# Install certbot
sudo apt-get install certbot python3-certbot-nginx

# Obtain certificate
sudo certbot --nginx -d api.example.com

# Auto-renewal
sudo systemctl enable certbot.timer
```

#### Firewall Rules

```bash
# UFW (Ubuntu)
sudo ufw allow 22/tcp   # SSH
sudo ufw allow 80/tcp   # HTTP
sudo ufw allow 443/tcp  # HTTPS
sudo ufw enable
```

#### Environment Variables Security

```bash
# Use secrets management
# AWS Secrets Manager
aws secretsmanager get-secret-value --secret-id voice-translator-secrets

# Kubernetes Secrets
kubectl create secret generic voice-translator-secrets \
  --from-literal=jwt-secret=your-secret-key
```

### Backup and Disaster Recovery

#### Database Backups
```bash
# Backup script
#!/bin/bash
BACKUP_DIR="/backups"
DATE=$(date +%Y%m%d_%H%M%S)

# Backup models
tar -czf $BACKUP_DIR/models_$DATE.tar.gz models/

# Backup configuration
tar -czf $BACKUP_DIR/config_$DATE.tar.gz .env

# Upload to S3
aws s3 cp $BACKUP_DIR/*.tar.gz s3://voice-translator-backups/
```

### Performance Tuning

#### OS-Level Optimizations

```bash
# Increase file descriptors
echo "* soft nofile 65536" >> /etc/security/limits.conf
echo "* hard nofile 65536" >> /etc/security/limits.conf

# TCP tuning
cat >> /etc/sysctl.conf <<EOF
net.core.somaxconn = 4096
net.ipv4.tcp_max_syn_backlog = 4096
net.ipv4.ip_local_port_range = 1024 65535
EOF

sysctl -p
```

### Troubleshooting

#### Common Issues

**High Memory Usage**:
```bash
# Check memory
free -h

# Limit model memory
export OMP_NUM_THREADS=4
```

**Connection Timeouts**:
```bash
# Check WebSocket settings
grep -i timeout .env
```

**Model Loading Failures**:
```bash
# Verify models
ls -lh models/stt/
python scripts/health_check.py
```

### Health Checks

```python
# Endpoint: /health
{
  "status": "healthy",
  "timestamp": "2025-12-17T10:30:00Z",
  "version": "1.0.0",
  "components": {
    "stt": "ok",
    "translation": "ok",
    "tts": "ok",
    "redis": "ok"
  },
  "metrics": {
    "active_connections": 42,
    "total_requests": 15234,
    "uptime_seconds": 86400
  }
}
```

## Deployment Checklist

- [ ] Environment variables configured
- [ ] Models downloaded and verified
- [ ] SSL/TLS certificates installed
- [ ] Firewall rules configured
- [ ] Monitoring and logging setup
- [ ] Backup strategy implemented
- [ ] Load testing completed
- [ ] Health checks passing
- [ ] Documentation updated
- [ ] Rollback plan prepared