docs/DEPLOYMENT.md

Deployment Guide

This guide covers deployment options for the Multi-Language Chat Agent application.

Table of Contents

• Prerequisites
• Environment Setup
• Docker Deployment
• Manual Deployment
• Production Considerations
• Monitoring and Health Checks
• Troubleshooting

Prerequisites

System Requirements

• Python: 3.8 or higher
• PostgreSQL: 12 or higher
• Redis: 6 or higher (optional but recommended)
• Docker: 20.10+ and Docker Compose 2.0+ (for containerized deployment)

External Services

• Groq API Key: Required for LLM functionality
• Database: PostgreSQL instance (local or cloud)
• Cache: Redis instance (optional)

Environment Setup

1. Clone and Prepare

git clone <repository-url>
cd chat-agent

2. Environment Configuration

Choose your deployment environment and set up configuration:

# Development
python scripts/setup_environment.py --environment development

# Production
python scripts/setup_environment.py --environment production

# Testing
python scripts/setup_environment.py --environment testing

3. Configure Environment Variables

Edit your .env file with actual values:

# Required: Groq API Key
GROQ_API_KEY=your_actual_groq_api_key

# Required: Database Connection
DATABASE_URL=postgresql://user:password@host:port/database

# Optional: Redis Connection
REDIS_URL=redis://host:port/db

# Required: Security
SECRET_KEY=your_secure_secret_key

Docker Deployment

Development with Docker

# Start development environment
docker-compose -f docker-compose.dev.yml up -d

# View logs
docker-compose -f docker-compose.dev.yml logs -f chat-agent-dev

# Stop services
docker-compose -f docker-compose.dev.yml down

Production with Docker

# Build and start production services
docker-compose up -d

# With nginx reverse proxy
docker-compose --profile production up -d

# View logs
docker-compose logs -f chat-agent

# Stop services
docker-compose down

Docker Environment Variables

Create a .env file for Docker Compose:

# .env file for Docker Compose
GROQ_API_KEY=your_groq_api_key
SECRET_KEY=your_secret_key
POSTGRES_DB=chat_agent_db
POSTGRES_USER=chatuser
POSTGRES_PASSWORD=secure_password

Manual Deployment

1. Install Dependencies

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Database Setup

# Initialize database
python scripts/init_db.py init --config production

# Or run migrations manually
python migrations/migrate.py migrate --config production

3. Start Application

# Production server (using Gunicorn)
pip install gunicorn
gunicorn --bind 0.0.0.0:5000 --workers 4 --worker-class eventlet app:app

# Development server
python app.py

4. Process Management (Production)

Use a process manager like systemd, supervisor, or PM2:

Systemd Service Example

Create /etc/systemd/system/chat-agent.service:

[Unit]
Description=Chat Agent Application
After=network.target

[Service]
Type=simple
User=chatuser
WorkingDirectory=/opt/chat-agent
Environment=PATH=/opt/chat-agent/venv/bin
ExecStart=/opt/chat-agent/venv/bin/gunicorn --bind 0.0.0.0:5000 --workers 4 --worker-class eventlet app:app
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable chat-agent
sudo systemctl start chat-agent
sudo systemctl status chat-agent

Production Considerations

1. Security

• HTTPS: Use SSL/TLS certificates (Let's Encrypt recommended)
• Firewall: Configure firewall rules
• API Keys: Store securely, rotate regularly
• Database: Use connection pooling and SSL

2. Performance

• Reverse Proxy: Use Nginx or Apache
• Load Balancing: Multiple application instances
• Caching: Redis for session and response caching
• Database: Connection pooling, read replicas

3. Monitoring

• Health Checks: Built-in endpoints at /health/*
• Logging: Centralized logging (ELK stack, Fluentd)
• Metrics: Application and system metrics
• Alerts: Set up alerts for critical issues

4. Backup and Recovery

• Database Backups: Regular automated backups
• Configuration: Version control for configurations
• Disaster Recovery: Documented recovery procedures

Monitoring and Health Checks

Health Check Endpoints

The application provides several health check endpoints:

• GET /health/ - Basic health check
• GET /health/detailed - Detailed component status
• GET /health/ready - Readiness probe (Kubernetes)
• GET /health/live - Liveness probe (Kubernetes)
• GET /health/metrics - Basic metrics

Example Health Check Response

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "service": "chat-agent",
  "version": "1.0.0",
  "components": {
    "database": {
      "status": "healthy",
      "connection": "ok",
      "response_time_ms": 5.2
    },
    "redis": {
      "status": "healthy",
      "connection": "ok",
      "response_time_ms": 1.8
    },
    "groq_api": {
      "status": "configured",
      "api_key_present": true
    }
  }
}

Load Balancer Configuration

For load balancers, use the basic health check:

upstream chat_agent {
    server app1:5000;
    server app2:5000;
}

server {
    location / {
        proxy_pass http://chat_agent;
    }
    
    location /health {
        proxy_pass http://chat_agent;
        access_log off;
    }
}

Troubleshooting

Common Issues

1. Database Connection Failed

# Check database connectivity
python -c "import psycopg2; psycopg2.connect('your_database_url')"

# Check database status
python scripts/init_db.py status --config production

2. Redis Connection Failed

# Test Redis connection
redis-cli -u redis://your_redis_url ping

# Check Redis status in app
curl http://localhost:5000/health/detailed

3. Groq API Issues

# Test API key
curl -H "Authorization: Bearer your_api_key" https://api.groq.com/openai/v1/models

# Check configuration
python -c "from config import config; print(config['production'].GROQ_API_KEY)"

4. WebSocket Connection Issues

• Check firewall rules for WebSocket traffic
• Verify proxy configuration for WebSocket upgrades
• Check browser console for connection errors

Log Analysis

# View application logs
tail -f logs/chat_agent.log

# Docker logs
docker-compose logs -f chat-agent

# System logs (systemd)
journalctl -u chat-agent -f

Performance Issues

# Check system resources
htop
df -h
free -m

# Database performance
psql -c "SELECT * FROM pg_stat_activity;"

# Redis performance
redis-cli info stats

Scaling

Horizontal Scaling

1. Load Balancer: Distribute traffic across multiple instances
2. Session Storage: Use Redis for shared session storage
3. Database: Use connection pooling and read replicas
4. File Storage: Use shared storage for logs and uploads

Vertical Scaling

1. CPU: Increase worker processes
2. Memory: Optimize caching and database connections
3. Storage: Use SSD for database and logs

Container Orchestration

For Kubernetes deployment, see k8s/ directory for manifests:

kubectl apply -f k8s/
kubectl get pods -l app=chat-agent
kubectl logs -f deployment/chat-agent

Security Checklist

• HTTPS enabled with valid certificates
• API keys stored securely (not in code)
• Database connections encrypted
• Firewall configured
• Regular security updates
• Input validation and sanitization
• Rate limiting configured
• Monitoring and alerting set up
• Backup and recovery tested
• Access logs enabled