spotlightcam/docs/DEPLOYMENT.md

# Deployment Guide - spotlight.cam

## Development Setup

### Prerequisites
- Docker & Docker Compose
- Node.js 20+
- PostgreSQL 15 (via Docker)

### Quick Start (Development)

1. **Clone repository**
```bash
git clone <repository-url>
cd spotlightcam
```

2. **Create environment file**
```bash
cp backend/.env.example backend/.env
# Edit backend/.env with your values
```

3. **Start development environment**
```bash
docker compose --profile dev up -d
# Or simply: docker compose up (dev is default)
```

4. **Run database migrations**
```bash
docker compose exec backend npx prisma migrate deploy
```

5. **Seed the database**
```bash
# Development environment - includes test users, events, heats
make seed-dev

# Or use npm directly
docker compose exec backend npm run prisma:seed:dev
```

6. **Access the application**
- Frontend: http://localhost:8080
- Backend API: http://localhost:8080/api
- Database: localhost:5432

### Development Features
- Hot reload for frontend and backend
- Relaxed rate limiting
- Detailed error messages
- Debug logging
- Exposed database port for tools (pgAdmin, DBeaver)

---

## Production Deployment

### Prerequisites
- Docker & Docker Compose
- SSL certificates
- Production database (AWS RDS, managed PostgreSQL, or self-hosted)
- AWS SES configured and in production mode
- Domain name with DNS configured

### Production Setup

1. **Create production environment file**
```bash
cp backend/.env.production.example backend/.env.production
```

2. **Generate strong secrets**
```bash
# Generate JWT secret
openssl rand -base64 64

# Generate strong database password
openssl rand -base64 32
```

3. **Configure environment variables**
Edit `backend/.env.production`:
- Set `NODE_ENV=production`
- Set strong `JWT_SECRET`
- Configure production `DATABASE_URL`
- Add AWS SES credentials
- Set production `CORS_ORIGIN`

4. **Create production database volume**
```bash
# IMPORTANT: Create external volume before first production start
# This protects the database from accidental deletion with 'docker compose down -v'
docker volume create slc_postgres_prod_data
```

This external volume will NOT be deleted even with `docker compose down -v`.

5. **Build production images**
```bash
docker compose --profile prod build
```

5. **Start production services**
```bash
docker compose --profile prod up -d
```

6. **Run migrations**
```bash
docker compose exec backend-prod npx prisma migrate deploy
```

7. **Seed production database**
```bash
# Production environment - admin user + divisions + competition types only
make seed-prod

# Or use npm directly
docker compose exec backend-prod npm run prisma:seed:prod
```

**Important:** Production seed creates:
- Admin account: admin@spotlight.cam (COMFORT tier, isAdmin flag)
- Divisions: Newcomer, Novice, Intermediate, Advanced, All-Star, Champion
- Competition Types: Jack & Jill, Strictly

**No test users or events are created in production.**

---

## Server Resource Requirements

### Recommended Server Specs
- **CPU:** 4 cores minimum
- **RAM:** 8GB minimum
- **Disk:** 50GB SSD (includes OS, Docker images, database)

### Resource Allocation (Production)
Docker containers configured for 4 CPU / 8GB server:

| Service | CPU Limit | CPU Reserved | Memory Limit | Memory Reserved |
|---------|-----------|--------------|--------------|-----------------|
| nginx-prod | 0.5 | 0.25 | 512M | 256M |
| frontend-prod | 0.5 | 0.25 | 512M | 256M |
| backend-prod | 1.5 | 1.0 | 2G | 1G |
| db-prod | 1.0 | 0.75 | 3G | 2G |
| **Total** | **3.5** | **2.25** | **6GB** | **3.5GB** |

Leaves ~0.5 CPU and ~2GB RAM for host system operations.

**Notes:**
- Limits allow bursting during peak traffic
- Reservations guarantee minimum resources
- PostgreSQL gets most memory for query caching
- Backend gets most CPU for Socket.IO and matching algorithm

---

## Environment Configuration

### Development vs Production

| Feature | Development | Production |
|---------|-------------|------------|
| Rate Limiting | Disabled/Relaxed | Strict (5 login attempts) |
| CSRF Protection | Disabled | Enabled |
| Body Size Limit | 50MB | 10KB |
| Error Details | Full stack traces | Generic messages |
| Logging | Debug level | Warn/Error level |
| CORS | Localhost only | Specific domains |
| Password Policy | Relaxed (8 chars) | Strict (8 chars + complexity) |

### Environment Variables

**Critical Security Variables:**
```bash
# Must be changed in production!
JWT_SECRET=<64-char-random-string>
DATABASE_URL=postgresql://user:STRONG_PASSWORD@host:5432/dbname

# AWS credentials - use IAM roles in production
AWS_ACCESS_KEY_ID=<your-key>
AWS_SECRET_ACCESS_KEY=<your-secret>
```

**Security Settings:**
```bash
# Production values
RATE_LIMIT_ENABLED=true
RATE_LIMIT_AUTH_MAX=5
RATE_LIMIT_EMAIL_MAX=3
ENABLE_CSRF=true
BODY_SIZE_LIMIT=10kb

# Development values
RATE_LIMIT_ENABLED=false
RATE_LIMIT_AUTH_MAX=100
ENABLE_CSRF=false
BODY_SIZE_LIMIT=50mb
```

---

## SSL/HTTPS Configuration

### Development (HTTP)
No SSL required - runs on http://localhost:8080

### Production (HTTPS)

1. **Obtain SSL certificates**
```bash
# Using Let's Encrypt (certbot)
certbot certonly --standalone -d spotlight.cam -d www.spotlight.cam
```

2. **Configure nginx**
Update `nginx/conf.d/default.conf`:
```nginx
server {
    listen 443 ssl http2;
    server_name spotlight.cam www.spotlight.cam;

    ssl_certificate /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;

    # SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    server_name spotlight.cam www.spotlight.cam;
    return 301 https://$server_name$request_uri;
}
```

3. **Mount SSL certificates in docker-compose.prod.yml**
Already configured to mount `./ssl:/etc/nginx/ssl:ro`

---

## Database Management

### Backups

**Automated backup script:**
```bash
#!/bin/bash
# scripts/backup-db.sh

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="./backups"
DB_CONTAINER="spotlightcam-db"

docker exec $DB_CONTAINER pg_dump -U spotlightcam spotlightcam > "$BACKUP_DIR/backup_$DATE.sql"

# Keep only last 7 days
find $BACKUP_DIR -name "backup_*.sql" -mtime +7 -delete
```

**Setup cron job:**
```bash
# Daily backup at 2 AM
0 2 * * * /path/to/spotlightcam/scripts/backup-db.sh
```

### Restore from backup

```bash
cat backups/backup_YYYYMMDD_HHMMSS.sql | docker exec -i spotlightcam-db psql -U spotlightcam spotlightcam
```

---

## Volume Safety & Data Protection

### Production Database Volume Protection

The production database uses an **external volume** (`slc_postgres_prod_data`) that is protected from accidental deletion:

```yaml
volumes:
  postgres_data_prod:
    external: true
    name: slc_postgres_prod_data
```

**Key Safety Features:**
- ✅ **NOT deleted** by `docker compose down`
- ✅ **NOT deleted** by `docker compose down -v` (even with volumes flag!)
- ✅ **Survives** container recreation and rebuilds
- ⚠️ Must be manually created before first production deployment

**Volume Commands:**
```bash
# Create volume (before first deployment)
docker volume create slc_postgres_prod_data

# List volumes
docker volume ls

# Inspect volume
docker volume inspect slc_postgres_prod_data

# Manual deletion (if absolutely necessary)
docker volume rm slc_postgres_prod_data  # Requires manual confirmation
```

### Safe vs Dangerous Commands

**SAFE - Will NOT delete data:**
```bash
docker compose down                      # Removes containers only
docker compose --profile prod down       # Removes prod containers only
docker compose restart                   # Restart containers
docker compose up --build                # Rebuild and restart
```

**DANGEROUS - Could delete development data:**
```bash
docker compose down -v                   # Deletes dev volumes (postgres_data)
docker compose down --volumes            # Same as above
```

**PROTECTED - Production database is safe even with:**
```bash
docker compose --profile prod down -v    # prod volume is EXTERNAL, won't be deleted
```

### Additional Safety Measures

**1. Shell Aliases (add to ~/.bashrc or ~/.zshrc):**
```bash
# Safe shutdown
alias dcd='echo "✅ docker compose down - volumes SAFE"; docker compose down'

# Dangerous shutdown with confirmation
alias dcdv='echo "🚨 WARNING! docker compose down -v DELETES VOLUMES!"; \
  echo "Type YES to continue:"; read response; \
  [ "$response" = "YES" ] && docker compose down -v || echo "❌ Cancelled"'
```

**2. Regular Backups:**
Always maintain automated backups regardless of volume protection:
```bash
# Daily backup at 2 AM
0 2 * * * docker compose exec db-prod pg_dump -U spotlightcam spotlightcam | gzip > /backups/db-$(date +\%Y\%m\%d).sql.gz
```

**3. Pre-deployment Checklist:**
- [ ] Production volume created: `docker volume ls | grep slc_postgres_prod_data`
- [ ] Volume is marked as external in docker-compose.yml
- [ ] Backup script is configured and tested
- [ ] Team knows NOT to use `-v` flag on production

---

## Monitoring & Logging

### View logs

**Development:**
```bash
# All services
docker compose --profile dev logs -f

# Specific service
docker compose logs -f backend
docker compose logs -f nginx

# Last 100 lines
docker compose logs --tail 100 backend
```

**Production:**
```bash
# All services
docker compose --profile prod logs -f

# Specific service (note -prod suffix)
docker compose logs -f backend-prod
docker compose logs -f nginx-prod

# Last 100 lines
docker compose --profile prod logs --tail 100 backend-prod
```

### Production log management

Logs are configured with rotation:
- Max size: 10MB per file
- Max files: 3
- Located in Docker's logging directory

---

## Security Checklist

### Before Going to Production

- [ ] **Create external database volume:** `docker volume create slc_postgres_prod_data`
- [ ] Generate strong JWT secret (64+ characters)
- [ ] Use strong database password (20+ characters)
- [ ] Configure AWS SES in production mode (not sandbox)
- [ ] Enable rate limiting (`RATE_LIMIT_ENABLED=true`)
- [ ] Enable CSRF protection (`ENABLE_CSRF=true`)
- [ ] Set strict CORS origins (no wildcards)
- [ ] Configure HTTPS with valid SSL certificates
- [ ] Set `NODE_ENV=production`
- [ ] Review and rotate all secrets
- [ ] Enable account lockout (`ENABLE_ACCOUNT_LOCKOUT=true`)
- [ ] Set strict password policy
- [ ] Configure firewall (allow only 80, 443, 22)
- [ ] Set up automated backups
- [ ] Configure monitoring/alerting
- [ ] Review security audit report (`docs/archive/SECURITY_AUDIT.md`)

### After Deployment

- [ ] Test all authentication flows
- [ ] Verify email sending works
- [ ] Check rate limiting is active
- [ ] Verify HTTPS is working
- [ ] Test WSDC integration
- [ ] Monitor error logs
- [ ] Set up uptime monitoring
- [ ] Configure alerts for failures

---

## Troubleshooting

### Backend won't start

**Check logs:**
```bash
docker compose logs backend
```

**Common issues:**
- Missing environment variables
- Database connection failed
- Port already in use
- Missing npm packages

### Database connection failed

**Check database is running:**
```bash
docker compose ps db
```

**Test connection:**
```bash
docker compose exec backend npx prisma db push
```

### Emails not sending

**Check AWS SES configuration:**
- Verify AWS credentials are correct
- Check SES is in production mode (not sandbox)
- Verify sender email is verified in SES
- Check CloudWatch logs for SES errors

### Rate limiting too strict

**Temporary disable (development only):**
```bash
# In .env
RATE_LIMIT_ENABLED=false
```

**Adjust limits:**
```bash
# In .env
RATE_LIMIT_AUTH_MAX=10  # Allow 10 attempts instead of 5
```

---

## Scaling Considerations

### Horizontal Scaling

For high traffic, consider:
1. Load balancer (nginx, HAProxy)
2. Multiple backend containers
3. Redis for session/rate limit storage
4. Managed database (AWS RDS, DigitalOcean)
5. CDN for static assets

### Performance Optimization

- Enable gzip compression in nginx
- Add Redis for caching
- Use connection pooling for database
- Implement database read replicas
- Use CDN for avatar images

---

## Maintenance

### Update dependencies

```bash
# Backend
docker compose exec backend npm update
docker compose exec backend npm audit fix

# Frontend
docker compose exec frontend npm update
docker compose exec frontend npm audit fix
```

### Rotate secrets

```bash
# Generate new JWT secret
openssl rand -base64 64

# Update .env.production
# Restart services
docker compose -f docker-compose.yml -f docker-compose.prod.yml restart backend
```

### Database migrations

```bash
# Create migration
docker compose exec backend npx prisma migrate dev --name description

# Apply to production
docker compose -f docker-compose.yml -f docker-compose.prod.yml exec backend npx prisma migrate deploy
```

---

## Quick Commands

```bash
# Start development
docker compose --profile dev up -d
# Or simply: docker compose up -d

# Start production
docker compose --profile prod up -d

# Stop all (specific profile)
docker compose --profile dev down
docker compose --profile prod down

# View logs (development)
docker compose logs -f backend

# View logs (production)
docker compose logs -f backend-prod

# Shell into container (development)
docker compose exec backend sh

# Shell into container (production)
docker compose exec backend-prod sh

# Run migrations (development)
docker compose exec backend npx prisma migrate deploy

# Run migrations (production)
docker compose exec backend-prod npx prisma migrate deploy

# Backup database (development)
docker exec spotlightcam-db pg_dump -U spotlightcam spotlightcam > backup.sql

# Backup database (production)
docker exec spotlightcam-db-prod pg_dump -U spotlightcam spotlightcam > backup.sql
```

---

## Support

For issues:
1. Check logs: `docker compose logs`
2. Review security audit: `docs/archive/SECURITY_AUDIT.md`
3. Check session context: `docs/SESSION_CONTEXT.md`
4. Review phase documentation: `docs/PHASE_*.md`

**Last Updated:** 2025-11-13