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. 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. Build production images

docker compose --profile prod build

5. Start production services

docker compose --profile prod up -d

6. Run migrations

docker compose --profile prod exec backend-prod npx prisma migrate deploy

---

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

---

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

• 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