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. **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. **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 --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:**
```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
```

---

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

- [ ] 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/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/SECURITY_AUDIT.md`
3. Check session context: `docs/SESSION_CONTEXT.md`
4. Review phase documentation: `docs/PHASE_*.md`

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