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**
   ```bash
   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**
   ```bash
   FLASK_ENV=production python deploy.py check-prod
   ```

4. **Deploy**
   ```bash
   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:
   ```bash
   export FLASK_ENV=production
   python app.py
   ```

### Docker Deployment

Create `Dockerfile`:

```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:
```bash
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`):
```ini
[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

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