math2-platform/docs/DEPLOYMENT.md

Deployment Guide

Overview

This guide covers deploying the Math2 Platform in various environments.

Deployment Environments

1. Development (Local)

Prerequisites:

• Node.js 20+
• PostgreSQL 15
• Redis 7
• Docker (optional)

Setup:

# Clone repository
git clone https://github.com/math2/platform.git
cd platform

# Backend setup
cd backend
npm install
cp .env.example .env
# Edit .env with your values

# Database setup
npx prisma generate
npx prisma migrate dev
npm run prisma:seed

# Start backend
npm run dev

# Frontend setup (new terminal)
cd ../frontend
npm install
cp .env.local.example .env.local
# Edit .env.local with your values

# Start frontend
npm run dev

Access:

• Frontend: http://localhost:3000
• Backend API: http://localhost:3001
• Prisma Studio: http://localhost:5555

2. Docker Compose (Single Server)

Prerequisites:

• Docker 24+
• Docker Compose 2.20+
• 4GB+ RAM
• 20GB+ Disk space

Setup:

# Clone and configure
git clone https://github.com/math2/platform.git
cd platform

# Configure environment
./scripts/setup-secrets.sh
# Or manually:
cp .env.example .env
nano .env

# Start services
docker-compose up -d

# Run migrations
docker-compose exec backend npx prisma migrate deploy

# Verify health
./scripts/health-check.sh

Environment Variables:

# Required
NODE_ENV=production
DATABASE_URL=postgresql://mathuser:password@postgres:5432/mathdb
REDIS_HOST=redis
REDIS_PASSWORD=secure_redis_password
JWT_SECRET=your-super-secret-jwt-key-min-32-chars

# AI Service (Optional)
AI_API_KEY=your-ai-api-key
AI_API_BASE_URL=https://api.example.com/v1

# Telegram (Optional)
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_ADMIN_CHAT_ID=admin-chat-id

Production Checklist:

• Change default passwords
• Set strong JWT_SECRET (min 32 chars)
• Enable SSL/TLS
• Configure firewall rules
• Set up monitoring
• Configure backups
• Test health checks
• Verify rate limiting

3. Production with SSL (Let's Encrypt)

Prerequisites:

• Domain name pointing to server
• Ports 80/443 open
• Docker Compose installed

Setup:

# Configure domain
export DOMAIN=mathplatform.com
export EMAIL=admin@mathplatform.com

# Run setup script
./scripts/setup-ssl.sh

# Or manually:
# 1. Copy SSL configuration
cp docker/nginx-ssl.conf docker/nginx.conf

# 2. Update .env
DOMAIN=mathplatform.com
ACME_EMAIL=admin@mathplatform.com

# 3. Start with SSL
docker-compose -f docker-compose.yml -f docker-compose.ssl.yml up -d

SSL Configuration:

# nginx-ssl.conf
server {
    listen 80;
    server_name mathplatform.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name mathplatform.com;

    ssl_certificate /etc/letsencrypt/live/mathplatform.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mathplatform.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256';
    ssl_prefer_server_ciphers off;

    # HSTS
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    location / {
        proxy_pass http://frontend:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /api {
        proxy_pass http://backend:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

4. Kubernetes

Prerequisites:

• Kubernetes 1.28+
• kubectl configured
• Helm 3.12+

Setup:

# Add secrets
kubectl create secret generic math-platform-secrets \
  --from-literal=DATABASE_URL="postgresql://..." \
  --from-literal=JWT_SECRET="..." \
  --from-literal=REDIS_PASSWORD="..."

# Deploy with Helm
helm install math-platform ./helm-chart \
  --namespace math-platform \
  --create-namespace \
  --set ingress.enabled=true \
  --set ingress.host=mathplatform.com

# Verify deployment
kubectl get pods -n math-platform
kubectl get svc -n math-platform

Helm Values:

# helm-chart/values.yaml
replicaCount: 3

image:
  repository: math-platform
  tag: latest
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 3001

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt
  hosts:
    - host: mathplatform.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: math-platform-tls
      hosts:
        - mathplatform.com

resources:
  limits:
    cpu: 1000m
    memory: 1Gi
  requests:
    cpu: 500m
    memory: 512Mi

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

5. AWS ECS

Prerequisites:

• AWS CLI configured
• ECS CLI installed
• VPC and Subnets configured

Setup:

# Create ECS cluster
ecs-cli up --cluster math-platform --region us-east-1

# Configure task definition
ecs-cli compose \
  --project-name math-platform \
  --file docker-compose.yml \
  --ecs-params ecs-params.yml \
  up

# Configure ALB
aws ecs create-service \
  --cluster math-platform \
  --service-name math-platform-service \
  --task-definition math-platform \
  --desired-count 3 \
  --load-balancers targetGroupArn=arn:aws:elasticloadbalancing:...

Database Migrations

Running Migrations

# Docker Compose
docker-compose exec backend npx prisma migrate deploy

# Kubernetes
kubectl exec -it deployment/backend -- npx prisma migrate deploy

# AWS ECS
aws ecs run-task \
  --cluster math-platform \
  --task-definition math-platform-migrate \
  --launch-type FARGATE

Rollback Strategy

# Check migration status
docker-compose exec backend npx prisma migrate status

# Rollback one migration
docker-compose exec backend npx prisma migrate resolve --rolled-back "20240330120000"

# Emergency rollback
docker-compose exec backend npx prisma db execute --file ./rollback.sql

Backup and Recovery

Automated Backups

# Daily backup cron job
0 2 * * * docker-compose exec postgres pg_dump -U mathuser mathdb > /backup/mathdb_$(date +\%Y\%m\%d).sql

# Backup with compression
0 2 * * * docker-compose exec postgres pg_dump -U mathuser mathdb | gzip > /backup/mathdb_$(date +\%Y\%m\%d).sql.gz

# S3 backup
0 2 * * * docker-compose exec postgres pg_dump -U mathuser mathdb | gzip | aws s3 cp - s3://math-platform-backups/db-$(date +\%Y\%m\%d).sql.gz

Recovery

# Restore from backup
# 1. Stop services
docker-compose stop backend

# 2. Restore database
docker-compose exec -T postgres psql -U mathuser mathdb < backup_20240330.sql

# 3. Restart services
docker-compose start backend

# Verify
docker-compose exec backend npx prisma migrate status

Monitoring and Logging

Health Checks

# Check service health
curl http://localhost/health

# Docker health
docker-compose ps

# Kubernetes health
kubectl get pods -n math-platform
kubectl describe pod <pod-name> -n math-platform

Logs

# Docker Compose
docker-compose logs -f backend
docker-compose logs -f --tail=100 frontend

# Kubernetes
kubectl logs -f deployment/backend -n math-platform
kubectl logs -f deployment/frontend -n math-platform --all-containers

# Centralized logging (if configured)
curl https://logs.mathplatform.com/api/search?query=error

Metrics

# Prometheus metrics (if enabled)
curl http://localhost:9090/metrics

# Custom application metrics
curl http://localhost:3001/metrics

Scaling

Horizontal Scaling

# Scale backend instances
docker-compose up -d --scale backend=5

# Scale workers
docker-compose up -d --scale exercise-worker=3

# Kubernetes
kubectl scale deployment backend --replicas=5 -n math-platform

Vertical Scaling

Update resource limits in docker-compose.yml:

services:
  backend:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G
        reservations:
          cpus: '1.0'
          memory: 1G

Blue-Green Deployment

# Deploy to blue environment
docker-compose -f docker-compose.yml -f docker-compose.blue.yml up -d

# Test blue environment
./scripts/test-blue.sh

# Switch traffic to blue
docker-compose exec nginx nginx -s reload

# Stop green environment
docker-compose -f docker-compose.green.yml stop

Troubleshooting

Common Issues

Services Won't Start

# Check logs
docker-compose logs service-name

# Check resource usage
docker stats

# Restart with cleanup
docker-compose down -v
docker-compose up -d

Database Connection Issues

# Check PostgreSQL
docker-compose exec postgres pg_isready

# Check network
docker network inspect math2_default

# Test connection
docker-compose exec backend ping postgres

Migration Failures

# Check status
docker-compose exec backend npx prisma migrate status

# Reset (WARNING: Data loss)
docker-compose exec backend npx prisma migrate reset

# Manual fix
docker-compose exec backend npx prisma migrate resolve --applied "migration_name"

Performance Issues

# Check slow queries
docker-compose exec postgres psql -U mathuser -d mathdb -c "SELECT * FROM pg_stat_statements ORDER BY total_time DESC LIMIT 10;"

# Check Redis memory
docker-compose exec redis redis-cli info memory

# Analyze response times
curl -w "@curl-format.txt" -o /dev/null -s http://localhost:3001/health

CI/CD Pipeline

GitHub Actions

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run test
      - run: npm run lint
      - run: npm run type-check

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build Docker images
        run: |
          docker build -t math-platform:${{ github.sha }} .
          docker tag math-platform:${{ github.sha }} math-platform:latest
      - name: Push to registry
        run: |
          echo ${{ secrets.DOCKER_PASSWORD }} | docker login -u ${{ secrets.DOCKER_USERNAME }} --password-stdin
          docker push math-platform:${{ github.sha }}

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to production
        run: |
          ssh ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }} '
            cd /opt/math-platform && \
            docker pull math-platform:${{ github.sha }} && \
            docker-compose up -d
          '

Security Checklist

Pre-Deployment

• Environment variables configured
• Secrets not in code
• SSL certificates installed
• Security headers configured
• Rate limiting enabled
• CORS properly configured
• Database encrypted at rest
• Backups configured
• Monitoring enabled
• Health checks passing

Post-Deployment

• Verify HTTPS
• Test authentication flow
• Check security headers
• Verify rate limiting
• Test backup restoration
• Monitor error rates
• Check resource usage
• Verify logging

Support

For deployment issues:

• Check logs: docker-compose logs
• Run health check: ./scripts/health-check.sh
• Review documentation: README.md
• Contact: devops@mathplatform.com