docs/PRODUCTION_DEPLOYMENT.md

Production Deployment Guide

This guide covers deploying the Chatty application in a production environment with proper security configurations.

Prerequisites

• Python 3.8+
• MongoDB Atlas account or MongoDB server
• HTTPS-enabled domain (required for secure cookies)
• Environment with proper SSL/TLS support

Quick Start

1. Generate Production Configuration

   python deploy.py gen-prod-env
   

   This creates .env.production with secure defaults.

2. Configure Environment Variables Edit .env.production and update:

   • MONGODB_URL: Your MongoDB connection string
   • Review all other settings

3. Validate Configuration

   FLASK_ENV=production python deploy.py check-prod
   

4. Deploy

   export FLASK_ENV=production
   ./start.sh
   

Environment Variables

Required Variables

Variable	Description	Example
SECRET_KEY	Flask secret key (32+ chars)	abc123...
MONGODB_URL	MongoDB connection string	mongodb+srv://...
FLASK_ENV	Environment mode	production

Security Variables

Variable	Default	Production	Description
SESSION_COOKIE_SECURE	false	true	Require HTTPS for cookies
WTF_CSRF_SSL_STRICT	false	true	Strict CSRF over HTTPS
MAX_LOGIN_ATTEMPTS	5	3	Failed login limit
RATE_LIMIT_WINDOW	900	1800	Rate limit window (seconds)

Optional Variables

Variable	Default	Description
SESSION_LIFETIME_HOURS	24	Session duration
API_TIMEOUT	30	External API timeout
LOG_LEVEL	INFO	Logging level
LOG_FILE	None	Log file path
PORT	7860	Server port

Security Checklist

Before Deployment

• Generate secure SECRET_KEY (32+ characters)
• Configure MongoDB with authentication
• Set up HTTPS/SSL certificates
• Review rate limiting settings
• Configure proper logging
• Test database connectivity

Production Configuration

• FLASK_ENV=production
• DEBUG=False (automatic in production)
• SESSION_COOKIE_SECURE=true
• WTF_CSRF_SSL_STRICT=true
• Strong MongoDB credentials
• Firewall rules configured

Monitoring

• Set up log monitoring
• Configure health checks
• Monitor database connections
• Track authentication failures

Deployment Methods

Hugging Face Spaces

1. Create .env file with production variables
2. Ensure PORT=7860 is set
3. Deploy with:

   export FLASK_ENV=production
   python app.py
   

Docker Deployment

Create Dockerfile:

FROM python:3.9-slim

WORKDIR /app
COPY ../requirements.txt .
RUN pip install -r requirements.txt

COPY .. .

ENV FLASK_ENV=production
EXPOSE 7860

CMD ["python", "app.py"]

Build and run:

docker build -t chatty .
docker run -p 7860:7860 --env-file .env.production chatty

Traditional Server

1. Set up reverse proxy (nginx/Apache)
2. Configure SSL certificates
3. Use process manager (systemd/supervisor)
4. Set environment variables
5. Start application

Example systemd service (/etc/systemd/system/chatty.service):

[Unit]
Description=Chatty Application
After=network.target

[Service]
Type=simple
User=chatty
WorkingDirectory=/opt/chatty
Environment=FLASK_ENV=production
EnvironmentFile=/opt/chatty/.env.production
ExecStart=/opt/chatty/atlas_env/bin/python app.py
Restart=always

[Install]
WantedBy=multi-user.target

Database Configuration

MongoDB Atlas

1. Create cluster in MongoDB Atlas
2. Configure network access (IP whitelist)
3. Create database user with appropriate permissions
4. Get connection string from Atlas dashboard
5. Update MONGODB_URL in environment

Self-Hosted MongoDB

1. Install and configure MongoDB
2. Enable authentication
3. Create application database and user
4. Configure SSL/TLS if needed
5. Set connection string in MONGODB_URL

Troubleshooting

Configuration Issues

# Check configuration
python deploy.py check-prod

# Generate new secret key
python deploy.py gen-secret

# Test database connection
python -c "from database import test_connection; test_connection()"

Common Issues

1. Secret Key Errors

   • Generate new key: python deploy.py gen-secret
   • Ensure key is 32+ characters

2. Database Connection Failures

   • Check MongoDB URI format
   • Verify network connectivity
   • Check authentication credentials

3. Session/Cookie Issues

   • Ensure HTTPS is configured
   • Check SESSION_COOKIE_SECURE setting
   • Verify domain configuration

4. CSRF Token Errors

   • Check WTF_CSRF_SSL_STRICT setting
   • Ensure forms include CSRF tokens
   • Verify HTTPS configuration

Logs and Monitoring

• Application logs: Check LOG_FILE or console output
• Database logs: MongoDB logs for connection issues
• Web server logs: nginx/Apache access and error logs
• System logs: systemd journal for service issues

Security Best Practices

1. Environment Variables

   • Never commit .env files to version control
   • Use secure secret management in production
   • Rotate secrets regularly

2. Database Security

   • Use strong passwords
   • Enable MongoDB authentication
   • Configure network restrictions
   • Regular backups

3. Application Security

   • Keep dependencies updated
   • Monitor for security vulnerabilities
   • Use HTTPS everywhere
   • Implement proper logging

4. Infrastructure Security

   • Keep OS updated
   • Configure firewall rules
   • Use fail2ban for brute force protection
   • Regular security audits

Performance Optimization

1. Database Optimization

   • Proper indexing (handled automatically)
   • Connection pooling (configured)
   • Query optimization

2. Application Optimization

   • Enable gzip compression
   • Use CDN for static assets
   • Implement caching where appropriate

3. Infrastructure Optimization

   • Use reverse proxy (nginx)
   • Load balancing for high traffic
   • Monitor resource usage

Backup and Recovery

1. Database Backups

   • Regular MongoDB backups
   • Test restore procedures
   • Store backups securely

2. Application Backups

   • Code repository backups
   • Configuration backups
   • Log file archival

3. Disaster Recovery

   • Document recovery procedures
   • Test disaster recovery
   • Maintain backup infrastructure