📖 EC2 Deployment Guide

🏗️ Infrastructure Requirements

Recommended EC2 Instance Types

*Costs are approximate and vary by region

Storage Requirements

• Root Volume: 50GB GP3 SSD (minimum)
• Data Volume: 100GB+ GP3 SSD (for models and cache)
• IOPS: 3000 baseline, burstable to 16000

Network Configuration

• Elastic IP: Required for stable endpoint
• Security Groups: See security section below
• Load Balancer: ALB recommended for production

🚀 Step-by-Step Deployment

1. Launch EC2 Instance

# Using AWS CLI
aws ec2 run-instances \
  --image-id ami-0c94855ba95c71c0a \  # Ubuntu 22.04 LTS
  --instance-type g4dn.xlarge \
  --key-name your-key-pair \
  --security-group-ids sg-xxxxxxxxx \
  --subnet-id subnet-xxxxxxxxx \
  --block-device-mappings '[
    {
      "DeviceName": "/dev/sda1",
      "Ebs": {
        "VolumeSize": 50,
        "VolumeType": "gp3",
        "DeleteOnTermination": true
      }
    }
  ]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=avatar-production}]'

2. Configure Security Groups

# Create security group
aws ec2 create-security-group \
  --group-name avatar-sg \
  --description "Security group for AvaTar system"

# Add inbound rules
aws ec2 authorize-security-group-ingress \
  --group-name avatar-sg \
  --protocol tcp \
  --port 22 \
  --cidr 0.0.0.0/0  # Restrict to your IP in production

aws ec2 authorize-security-group-ingress \
  --group-name avatar-sg \
  --protocol tcp \
  --port 80 \
  --cidr 0.0.0.0/0

aws ec2 authorize-security-group-ingress \
  --group-name avatar-sg \
  --protocol tcp \
  --port 443 \
  --cidr 0.0.0.0/0

aws ec2 authorize-security-group-ingress \
  --group-name avatar-sg \
  --protocol tcp \
  --port 8000-8002 \
  --cidr 0.0.0.0/0

3. Initial Server Setup

# Connect to instance
ssh -i your-key.pem ubuntu@your-instance-ip

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

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker ubuntu

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Install NVIDIA Docker support (for GPU instances)
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt-get update && sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker

# Verify GPU access
docker run --rm --gpus all nvidia/cuda:11.6.2-base-ubuntu20.04 nvidia-smi

4. Deploy AvaTar

# Clone repository
git clone https://github.com/yourusername/AvaTar.git
cd AvaTar

# Create environment file
cat > .env << EOF
# API Configuration
ELEVENLABS_API_KEY=your_elevenlabs_key
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key

# Redis Configuration
REDIS_URL=redis://redis:6379
REDIS_MAX_CONNECTIONS=100

# API Settings
API_HOST=0.0.0.0
API_PORT=8000
API_WORKERS=4

# WebSocket Settings
WS_HOST=0.0.0.0
WS_PORT=8001

# Performance Settings
FRAME_BUFFER_SIZE=200
MAX_CONCURRENT_SESSIONS=20
SESSION_TIMEOUT=3600

# Security
CORS_ORIGINS=["https://yourdomain.com"]
SECRET_KEY=$(openssl rand -hex 32)
EOF

# Start services
docker-compose -f docker-compose.yml up -d

# Check logs
docker-compose logs -f

5. Configure Nginx Reverse Proxy

# Install Nginx
sudo apt install nginx -y

# Configure Nginx
sudo tee /etc/nginx/sites-available/avatar << EOF
server {
    listen 80;
    server_name your-domain.com;

    # Redirect to HTTPS
    return 301 https://\$server_name\$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    # SSL Configuration
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    # API Backend
    location /v1/ {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade \$http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host \$host;
        proxy_cache_bypass \$http_upgrade;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto \$scheme;
    }

    # WebSocket
    location /ws/ {
        proxy_pass http://localhost:8001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade \$http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto \$scheme;
        
        # WebSocket specific
        proxy_read_timeout 86400;
        proxy_send_timeout 86400;
    }

    # Static files
    location / {
        root /home/ubuntu/AvaTar/test-client;
        try_files \$uri \$uri/ /index.html;
    }
}
EOF

# Enable site
sudo ln -s /etc/nginx/sites-available/avatar /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl restart nginx

6. SSL Certificate Setup

# Install Certbot
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot

# Get SSL certificate
sudo certbot --nginx -d your-domain.com

7. System Optimization

# Increase file descriptors
echo "* soft nofile 65536" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65536" | sudo tee -a /etc/security/limits.conf

# Optimize kernel parameters
sudo tee -a /etc/sysctl.conf << EOF
# Network optimizations
net.core.rmem_max = 134217728
net.core.wmem_max = 134217728
net.ipv4.tcp_rmem = 4096 87380 134217728
net.ipv4.tcp_wmem = 4096 65536 134217728
net.core.netdev_max_backlog = 5000
net.ipv4.tcp_congestion_control = bbr

# WebSocket connections
net.ipv4.tcp_keepalive_time = 600
net.ipv4.tcp_keepalive_intvl = 60
net.ipv4.tcp_keepalive_probes = 3
EOF

sudo sysctl -p

📊 Monitoring & Logging

CloudWatch Setup

# Install CloudWatch agent
wget https://s3.amazonaws.com/amazoncloudwatch-agent/amazon_linux/amd64/latest/amazon-cloudwatch-agent.rpm
sudo rpm -U ./amazon-cloudwatch-agent.rpm

# Configure CloudWatch
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-config-wizard

Application Monitoring

# Create monitoring script
cat > ~/monitor-avatar.sh << 'EOF'
#!/bin/bash

# Check services
docker-compose ps

# Check memory usage
docker stats --no-stream

# Check Redis
docker exec avatar-redis-1 redis-cli INFO stats

# Check API health
curl -s http://localhost:8000/health | jq

# Check active sessions
curl -s http://localhost:8000/v1/streaming.sessions | jq
EOF

chmod +x ~/monitor-avatar.sh

🔒 Security Best Practices

🚨 Backup & Recovery

Automated Backup Script

#!/bin/bash
# backup-avatar.sh

BACKUP_DIR="/backup/avatar"
S3_BUCKET="s3://your-backup-bucket"
DATE=$(date +%Y%m%d_%H%M%S)

# Create backup directory
mkdir -p $BACKUP_DIR

# Backup Docker volumes
docker run --rm -v avatar_redis_data:/data -v $BACKUP_DIR:/backup alpine tar czf /backup/redis_$DATE.tar.gz -C /data .

# Backup configuration
tar czf $BACKUP_DIR/config_$DATE.tar.gz ~/AvaTar/.env ~/AvaTar/docker-compose.yml

# Upload to S3
aws s3 sync $BACKUP_DIR $S3_BUCKET/avatar-backups/

# Clean old backups (keep 7 days)
find $BACKUP_DIR -type f -mtime +7 -delete

📈 Scaling Strategies

Horizontal Scaling with Load Balancer

# docker-compose-scale.yml
version: '3.8'

services:
  api:
    image: avatar-api:latest
    deploy:
      replicas: 3
      restart_policy:
        condition: on-failure
    environment:
      - INSTANCE_ID={{.Task.Slot}}
    networks:
      - avatar-network

  nginx:
    image: nginx:latest
    volumes:
      - ./nginx-load-balancer.conf:/etc/nginx/nginx.conf
    ports:
      - "80:80"
    depends_on:
      - api
    networks:
      - avatar-network

Auto Scaling Configuration

# Create launch template
aws ec2 create-launch-template \
  --launch-template-name avatar-template \
  --version-description "AvaTar production template" \
  --launch-template-data '{
    "ImageId": "ami-xxxxxxxxx",
    "InstanceType": "g4dn.xlarge",
    "KeyName": "your-key",
    "SecurityGroupIds": ["sg-xxxxxxxxx"],
    "UserData": "BASE64_ENCODED_STARTUP_SCRIPT"
  }'

# Create Auto Scaling group
aws autoscaling create-auto-scaling-group \
  --auto-scaling-group-name avatar-asg \
  --launch-template LaunchTemplateName=avatar-template \
  --min-size 1 \
  --max-size 10 \
  --desired-capacity 2 \
  --target-group-arns arn:aws:elasticloadbalancing:region:account-id:targetgroup/avatar-tg/xxxxxxxxx

🎯 Performance Tuning

Redis Optimization

# redis.conf additions
maxmemory 4gb
maxmemory-policy allkeys-lru
save ""
appendonly no
tcp-keepalive 60

Docker Performance

# docker-compose.yml optimizations
services:
  api:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G

📞 Support & Troubleshooting

Common Issues

# Verify NVIDIA drivers
nvidia-smi

# Check Docker GPU support
docker run --rm --gpus all nvidia/cuda:11.6.2-base-ubuntu20.04 nvidia-smi

# Check memory leaks
docker stats

# Restart services
docker-compose restart

Health Checks

# API health
curl http://localhost:8000/health

# WebSocket test
wscat -c ws://localhost:8001/ws/test-session

# Redis health
docker exec avatar-redis-1 redis-cli ping

📌 Quick Reference

Essential Commands

# Start system
docker-compose up -d

# View logs
docker-compose logs -f

# Restart service
docker-compose restart api

# Scale service
docker-compose up -d --scale api=3

# Backup data
./backup-avatar.sh

# Monitor system
./monitor-avatar.sh

Important URLs

• API Health: http://your-domain.com/health
• API Docs: http://your-domain.com/docs
• WebSocket: ws://your-domain.com/ws/{session_id}
• Demo: http://your-domain.com/conversational-avatar.html