team-tryouts/docs/deployment.md

# Team Tryouts - Production Deployment Guide (Windows)

This document outlines the secure production deployment for the Team Tryouts
Flask application on Windows with Nginx reverse proxy.

## Architecture Overview

```
Internet → Nginx (HTTPS:443) → Waitress (127.0.0.1:5000) → Flask App
```

- **Nginx**: TLS termination, static file serving, rate limiting, security headers
- **Waitress**: Production WSGI server with multiple worker threads
- **Flask**: Application logic (never exposed directly to the internet)

## Prerequisites

1. **Python 3.12+** installed
2. **Nginx for Windows** downloaded from [nginx.org](https://nginx.org/en/download.html)
3. **SSL Certificate** (Let's Encrypt via certbot or commercial provider)
4. **Windows Firewall** configured properly

## Step 1: Install Dependencies

```powershell
# Install Python packages
pip install -r requirements.txt

# Create required directories
mkdir logs
mkdir backups
```

## Step 2: Configure Environment Variables

Create a `.env` file in the project root:

```env
# Security (REQUIRED - generate with: python -c "import secrets; print(secrets.token_hex(32))")
SECRET_KEY=<your-generated-64-char-hex-key>

# Database — PostgreSQL. create_app() refuses to start without this.
# Either form works; the driver is named for you if you leave it out.
DATABASE_URL=postgresql://user:password@host:5432/dbname

# Security settings
SESSION_COOKIE_SECURE=true
FORCE_HTTPS=true
FLASK_DEBUG=false

# CORS (set to your actual domain in production)
CORS_ALLOWED_ORIGINS=https://yourdomain.com

# Discord bot (optional)
DISCORD_BOT_TOKEN=
DISCORD_WEBHOOK_URL=

# Backup settings
BACKUP_DIR=./backups
BACKUP_RETENTION_DAYS=30
```

**Important**: Never commit `.env` to version control.

## Step 3: Configure Nginx

1. Copy `app/nginx.conf` to your Nginx installation directory (e.g., `C:\nginx\conf\`)
2. **Edit the `alias` in the `location /static/` block** to point at this
   checkout's `app/static/` directory — absolute path, forward slashes, keep
   the trailing slash. It ships as `C:/team-tryouts/app/static/`, which is a
   guess about your machine. Nginx resolves a relative path against its own
   install prefix, not against `nginx.conf`.
3. Place SSL certificate files:
   - `C:\nginx\certs\fullchain.pem`
   - `C:\nginx\certs\privkey.pem`
4. Check the configuration parses before restarting: `C:\nginx\nginx.exe -t`
5. Start Nginx: `C:\nginx\nginx.exe`

Nginx serves `/static/` from disk with a 30-day `immutable` cache. That is
only safe because `url_for('static', …)` appends `?v=<mtime>` to every static
URL (`version_static_urls` in `app/app.py`), so a redeployed file is requested
under a new URL. If that stamp is ever removed, remove the cache headers with
it or visitors keep a month-old stylesheet.

After a deploy, confirm the stamp changed rather than trusting it:

```powershell
# The v= value must differ from the one served before the deploy.
(Invoke-WebRequest https://your-domain/auth/login).Content -match 'style\.css\?v=(\d+)'
```

### Obtaining SSL Certificates

Using Let's Encrypt with certbot (recommended):

```powershell
# Using certbot on Windows
certbot certonly --standalone -d yourdomain.com
```

Or use your hosting provider's SSL certificate.

## Step 4: Start the Application

```powershell
# Production start
python wsgi.py

# Or with custom port/threads
$env:PORT=5000
$env:WAITRESS_THREADS=5
python wsgi.py
```

## Step 5: Configure Windows Firewall

```powershell
# Allow only necessary ports
New-NetFirewallRule -DisplayName "Nginx HTTPS" -Direction Inbound -Protocol TCP -LocalPort 443 -Action Allow
New-NetFirewallRule -DisplayName "Nginx HTTP Redirect" -Direction Inbound -Protocol TCP -LocalPort 80 -Action Allow

# Block direct access to Waitress port (5000) from outside
New-NetFirewallRule -DisplayName "Block Waitress External" -Direction Inbound -Protocol TCP -LocalPort 5000 -Action Block
```

## Step 6: Set Up Automated Backups

Create a scheduled task for daily backups:

```powershell
# Run backup script daily at 2:00 AM
$Action = New-ScheduledTaskAction -Execute "python" -Argument "backup.py" -WorkingDirectory "C:\path\to\team-tryouts"
$Trigger = New-ScheduledTaskTrigger -Daily -At 2:00AM
Register-ScheduledTask -TaskName "TeamTryoutsBackup" -Action $Action -Trigger $Trigger
```

## Step 7: Run Security Validation

Before going live:

```powershell
# Run the security scanner
python security_scan.py --url https://yourdomain.com
```

All checks must pass before deployment.

## Security Checklist

- [ ] `.env` is not committed to repository
- [ ] `SECRET_KEY` is strong (64+ hex characters, randomly generated)
- [ ] `FLASK_DEBUG` is set to `false`
- [ ] Nginx is running with HTTPS (port 443)
- [ ] HTTP (port 80) redirects to HTTPS
- [ ] TLS 1.2+ configured (TLS 1.0/1.1 disabled)
- [ ] HSTS header is present (`max-age=31536000; includeSubDomains; preload`)
- [ ] CSP header is configured with no `unsafe-eval`
- [ ] `server_tokens` is `off` in Nginx
- [ ] File uploads restricted to PDF only
- [ ] File uploads limited to 16MB
- [ ] Database backups scheduled daily
- [ ] Firewall rules applied (only 80/443 open)
- [ ] Application is not running as administrator
- [ ] Logs directory exists and is writable
- [ ] Health check endpoint returns 200

## Monitoring

- **Application logs**: `./logs/app.log`
- **Error logs**: `./logs/errors.log`
- **Auth logs**: `./logs/auth.log`
- **Nginx access logs**: `C:\nginx\logs\access.log`
- **Nginx error logs**: `C:\nginx\logs\error.log`

Monitor these logs regularly for suspicious activity.

## Maintenance

- Run `pip-audit` weekly to check for vulnerabilities
- Run `python security_scan.py` after any configuration changes
- Test backup restoration quarterly
- Review and rotate `SECRET_KEY` if compromised
- Keep Python and system packages updated