gcp-hockey-results/motm_app/PRODUCTION_DEPLOYMENT.md

Production Deployment Guide

WSGI Server Setup

Your Flask application now uses Gunicorn as the production WSGI server instead of the Flask development server.

Files Added:

• gunicorn.conf.py - Gunicorn configuration file
• run_production.py - WSGI entry point
• start_production.sh - Production startup script
• motm-app.service - Systemd service file (optional)

Quick Start (Recommended)

1. Install Dependencies

pip install -r requirements.txt

2. Start Production Server

# Option A: Use the startup script (easiest)
./start_production.sh

# Option B: Start manually
gunicorn -c gunicorn.conf.py run_production:app

# Option C: Quick start with default settings
gunicorn --bind 0.0.0.0:5000 --workers 4 run_production:app

Configuration Details

Gunicorn Configuration (gunicorn.conf.py)

• Workers: CPU_COUNT * 2 + 1 (automatically calculated)
• Worker Class: sync (good for Flask applications)
• Timeout: 30 seconds
• Max Requests: 1000 per worker (prevents memory leaks)
• Logging: Standard output (can be redirected)
• Preload: Enabled for better performance

Environment Variables

• FLASK_ENV=production (automatically set)

Alternative WSGI Servers

If you prefer different WSGI servers:

1. uWSGI

pip install uwsgi
uwsgi --http 0.0.0.0:5000 --module run_production:app --processes 4 --threads 2

2. Waitress (Windows-friendly)

pip install waitress
waitress-serve --host=0.0.0.0 --port=5000 run_production:app

3. Gevent (for async workloads)

pip install gunicorn[gevent]
gunicorn -c gunicorn.conf.py --worker-class gevent run_production:app

Production Recommendations

1. Use a Reverse Proxy

Place Nginx or Apache in front of Gunicorn:

Nginx Example:

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

2. SSL/HTTPS

For production, always use HTTPS:

• Use Let's Encrypt for free SSL certificates
• Configure SSL in your reverse proxy
• Update Gunicorn config with SSL settings if needed

3. Process Management

Use systemd or supervisor to manage the Gunicorn process:

Systemd (Linux):

sudo cp motm-app.service /etc/systemd/system/
sudo systemctl enable motm-app
sudo systemctl start motm-app
sudo systemctl status motm-app

4. Monitoring

• Monitor worker processes and memory usage
• Set up log rotation
• Use tools like Prometheus + Grafana for metrics

Performance Tuning

Worker Count

• CPU-bound: workers = CPU_COUNT * 2
• I/O-bound: workers = CPU_COUNT * 2 + 1 (current setting)
• High concurrency: Consider async workers (gevent/eventlet)

Memory Management

• Current: max_requests = 1000 (restarts workers periodically)
• Adjust based on your memory constraints

Timeout Settings

• Current: timeout = 30 seconds
• Increase if you have long-running requests

Troubleshooting

Common Issues:

1. Permission denied: Check file permissions and user/group settings
2. Port already in use: Change port in gunicorn.conf.py or kill existing process
3. Memory issues: Reduce worker count or increase max_requests
4. Slow responses: Increase timeout or worker count

Logs:

• Gunicorn logs to stdout/stderr by default
• Check systemd logs: journalctl -u motm-app
• Redirect logs to files if needed

Security Notes

1. Never run as root in production
2. Use HTTPS for all production traffic
3. Set proper file permissions on your application files
4. Keep dependencies updated regularly
5. Use environment variables for sensitive configuration

Migration from Development

Your application is now ready for production! The key changes:

• ✅ Gunicorn WSGI server instead of Flask dev server
• ✅ Production-optimized configuration
• ✅ Proper worker management
• ✅ Security improvements
• ✅ Performance optimizations

Next Steps:

1. Test the production setup locally
2. Deploy to your production server
3. Set up reverse proxy (Nginx/Apache)
4. Configure SSL certificates
5. Set up monitoring and logging