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

git clone <repository-url>
cd spotlightcam

2. Create environment file

cp backend/.env.example backend/.env
# Edit backend/.env with your values

3. Start development environment

docker compose --profile dev up -d
# Or simply: docker compose up (dev is default)

4. Run database migrations

docker compose exec backend npx prisma migrate deploy

5. Seed the database

# 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

cp backend/.env.production.example backend/.env.production

2. Generate strong secrets

# 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

# 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

docker compose --profile prod build

5. Start production services

docker compose --profile prod up -d

6. Run migrations

docker compose exec backend-prod npx prisma migrate deploy

7. Seed production database

# 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:

# 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:

# 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

# Using Let's Encrypt (certbot)
certbot certonly --standalone -d spotlight.cam -d www.spotlight.cam

2. Configure nginx Update nginx/conf.d/default.conf:

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:

#!/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:

# Daily backup at 2 AM
0 2 * * * /path/to/spotlightcam/scripts/backup-db.sh

Restore from backup

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:

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:

# 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:

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:

docker compose down -v                   # Deletes dev volumes (postgres_data)
docker compose down --volumes            # Same as above

PROTECTED - Production database is safe even with:

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):

# 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:

# 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:

# 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:

# 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:

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:

docker compose ps db

Test connection:

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):

# In .env
RATE_LIMIT_ENABLED=false

Adjust limits:

# 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

# 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

# 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

# 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

# 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