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)

# 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

# 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

# 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

# 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

# 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

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

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

Backup and Restore

# 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

# 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

# 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

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

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

🚨 Troubleshooting

Common Issues

1. Container Won't Start

# Check logs
docker-compose logs chat-agent

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

2. Database Connection Failed

# 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

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

# Check Redis logs
docker-compose logs redis

Log Analysis

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

# Database logs
docker-compose logs -f postgres

# All services
docker-compose logs -f

📈 Scaling

Horizontal Scaling

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

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

Load Balancing

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

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: Detailed deployment instructions
• Environment Setup: Manual setup guide
• API Documentation: API reference
• Feature Specifications: Requirements and design

🆘 Support

For deployment issues:

1. Check the troubleshooting section
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