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