docs/DEPLOYMENT.md

# Deployment Guide

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

## Table of Contents

- [Prerequisites](#prerequisites)
- [Environment Setup](#environment-setup)
- [Docker Deployment](#docker-deployment)
- [Manual Deployment](#manual-deployment)
- [Production Considerations](#production-considerations)
- [Monitoring and Health Checks](#monitoring-and-health-checks)
- [Troubleshooting](#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

```bash

git clone <repository-url>

cd chat-agent

```

### 2. Environment Configuration

Choose your deployment environment and set up configuration:

```bash

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

```bash

# 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

```bash

# 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

```bash

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

```bash

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

```bash

# 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

```bash

# Initialize database

python scripts/init_db.py init --config production



# Or run migrations manually

python migrations/migrate.py migrate --config production

```

### 3. Start Application

```bash

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

```ini

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

```bash

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

```json

{

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

```nginx

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

```bash

# 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

```bash

# 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

```bash

# 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

```bash

# 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

```bash

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

```bash

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