DEPLOYMENT_README.md

# Multi-Language Chat Agent - Deployment Setup

This document provides a comprehensive overview of the deployment configuration and setup for the Multi-Language Chat Agent application.

## 🚀 Quick Start

### Docker Deployment (Recommended)

```bash
# Clone repository
git clone <repository-url>
cd chat-agent

# Set up environment
cp config/production.env .env
# Edit .env with your actual values

# Start with Docker Compose
docker-compose up -d

# Check health
curl http://localhost:5000/health/
```

### Manual Deployment

```bash
# Set up environment
python scripts/setup_environment.py --environment production

# Start application
make run-prod
```

## 📁 Configuration Files Overview

### Docker Configuration

| File | Purpose | Environment |
|------|---------|-------------|
| `Dockerfile` | Production container build | Production |
| `Dockerfile.dev` | Development container with hot reload | Development |
| `docker-compose.yml` | Production services orchestration | Production |
| `docker-compose.dev.yml` | Development services with volumes | Development |
| `nginx.conf` | Reverse proxy configuration | Production |
| `.dockerignore` | Docker build optimization | All |

### Environment Configuration

| File | Purpose | Usage |
|------|---------|-------|
| `config/development.env` | Development environment variables | Development |
| `config/production.env` | Production environment template | Production |
| `config/testing.env` | Testing environment configuration | Testing |
| `.env.example` | Environment template with examples | Reference |

### Database Configuration

| File | Purpose | Usage |
|------|---------|-------|
| `migrations/001_initial_schema.sql` | Database schema definition | All environments |
| `migrations/migrate.py` | Migration management script | All environments |
| `scripts/init_db.py` | Database initialization utility | Setup |

### Deployment Scripts

| File | Purpose | Usage |
|------|---------|-------|
| `scripts/setup_environment.py` | Automated environment setup | Setup |
| `scripts/init_db.py` | Database management | Setup/Maintenance |
| `Makefile` | Common development tasks | Development |

## 🏗️ Architecture Overview

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│     Nginx       │    │   Chat Agent    │    │   PostgreSQL    │
│  (Reverse Proxy)│────│   Application   │────│   Database      │
│                 │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                                │
                       ┌─────────────────┐
                       │     Redis       │
                       │   (Cache/       │
                       │   Sessions)     │
                       └─────────────────┘
```

## 🔧 Configuration Management

### Environment-Specific Settings

The application supports three environments with different configurations:

#### Development
- Debug mode enabled
- Detailed logging
- Local database
- Hot reload
- Development tools

#### Production
- Optimized for performance
- Security hardened
- Production database
- Monitoring enabled
- Error handling

#### Testing
- In-memory database
- Isolated test data
- Minimal logging
- Fast execution

### Configuration Hierarchy

1. **Environment Variables** (highest priority)
2. **`.env` file**
3. **Config class defaults**
4. **Application defaults** (lowest priority)

## 🐳 Docker Deployment

### Production Deployment

```bash
# Build and start all services
docker-compose up -d

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

# Scale application instances
docker-compose up -d --scale chat-agent=3
```

### Development Deployment

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

# View logs
docker-compose -f docker-compose.dev.yml logs -f
```

### Docker Services

| Service | Purpose | Ports | Dependencies |
|---------|---------|-------|--------------|
| `chat-agent` | Main application | 5000 | postgres, redis |
| `postgres` | Database | 5432 | - |
| `redis` | Cache/Sessions | 6379 | - |
| `nginx` | Reverse proxy | 80, 443 | chat-agent |

## 🗄️ Database Management

### Initialization

```bash
# Initialize database with schema
python scripts/init_db.py init --config production

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

# Seed with sample data
python scripts/init_db.py seed --config production
```

### Migrations

```bash
# Run migrations manually
python migrations/migrate.py migrate --config production

# Check migration status
python migrations/migrate.py status --config production
```

### Backup and Restore

```bash
# Create backup
make backup-db

# Restore from backup
make restore-db
```

## 🔍 Health Monitoring

### Health Check Endpoints

| Endpoint | Purpose | Use Case |
|----------|---------|----------|
| `/health/` | Basic health check | Load balancer |
| `/health/detailed` | Component status | Monitoring |
| `/health/ready` | Readiness probe | Kubernetes |
| `/health/live` | Liveness probe | Kubernetes |
| `/health/metrics` | Application metrics | Monitoring |

### Example Health Check

```bash
# Basic health check
curl http://localhost:5000/health/

# Detailed status
curl http://localhost:5000/health/detailed | jq
```

### Monitoring Integration

The health endpoints are designed to work with:
- **Load Balancers**: Nginx, HAProxy, AWS ALB
- **Container Orchestration**: Kubernetes, Docker Swarm
- **Monitoring Systems**: Prometheus, Grafana, DataDog

## 🔒 Security Configuration

### Production Security Checklist

- [ ] **HTTPS**: SSL/TLS certificates configured
- [ ] **API Keys**: Stored securely, not in code
- [ ] **Database**: Connection encryption enabled
- [ ] **Firewall**: Proper rules configured
- [ ] **Headers**: Security headers set in Nginx
- [ ] **Rate Limiting**: Configured for API endpoints
- [ ] **Input Validation**: All inputs sanitized
- [ ] **Logging**: Security events logged

### Environment Variables Security

```bash
# Use secure secret generation
python -c "import secrets; print(secrets.token_urlsafe(32))"

# Store in secure location
export SECRET_KEY="your_secure_key"
export GROQ_API_KEY="your_api_key"
```

## 📊 Performance Optimization

### Application Performance

- **Connection Pooling**: Database and Redis connections
- **Caching**: Redis for sessions and frequent data
- **Async Processing**: WebSocket for real-time communication
- **Load Balancing**: Multiple application instances

### Database Performance

```sql
-- Recommended indexes
CREATE INDEX CONCURRENTLY idx_messages_session_timestamp 
ON messages(session_id, timestamp);

CREATE INDEX CONCURRENTLY idx_sessions_user_active 
ON chat_sessions(user_id, is_active);
```

### Redis Configuration

```bash
# Production Redis settings
maxmemory 512mb
maxmemory-policy allkeys-lru
save 900 1
save 300 10
```

## 🚨 Troubleshooting

### Common Issues

#### 1. Container Won't Start

```bash
# Check logs
docker-compose logs chat-agent

# Check health
docker-compose exec chat-agent curl localhost:5000/health/
```

#### 2. Database Connection Failed

```bash
# Test database connectivity
docker-compose exec postgres psql -U chatuser -d chat_agent_db -c "SELECT 1;"

# Check environment variables
docker-compose exec chat-agent env | grep DATABASE
```

#### 3. Redis Connection Issues

```bash
# Test Redis connectivity
docker-compose exec redis redis-cli ping

# Check Redis logs
docker-compose logs redis
```

### Log Analysis

```bash
# Application logs
docker-compose logs -f chat-agent

# Database logs
docker-compose logs -f postgres

# All services
docker-compose logs -f
```

## 📈 Scaling

### Horizontal Scaling

```bash
# Scale application instances
docker-compose up -d --scale chat-agent=3

# Update nginx upstream configuration
# Add multiple server entries in nginx.conf
```

### Load Balancing

```nginx
upstream chat_agent {
    server chat-agent_1:5000;
    server chat-agent_2:5000;
    server chat-agent_3:5000;
}
```

### Database Scaling

- **Read Replicas**: For read-heavy workloads
- **Connection Pooling**: PgBouncer for connection management
- **Partitioning**: For large message tables

## 🔄 CI/CD Integration

### GitHub Actions Example

```yaml
name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Build and Deploy
        run: |
          docker-compose build
          docker-compose up -d
          
      - name: Health Check
        run: |
          sleep 30
          curl -f http://localhost:5000/health/ || exit 1
```

## 📚 Additional Resources

- **[Deployment Guide](docs/DEPLOYMENT.md)**: Detailed deployment instructions
- **[Environment Setup](docs/ENVIRONMENT_SETUP.md)**: Manual setup guide
- **[API Documentation](chat_agent/api/README.md)**: API reference
- **[Feature Specifications](.kiro/specs/multi-language-chat-agent/)**: Requirements and design

## 🆘 Support

For deployment issues:

1. Check the [troubleshooting section](#-troubleshooting)
2. Review application logs
3. Verify configuration settings
4. Test health endpoints
5. Check system resources

## 📝 Changelog

### Version 1.0.0
- Initial deployment configuration
- Docker containerization
- Health monitoring
- Environment management
- Database migrations
- Security hardening