math2-platform/docker/README.md

Docker Infrastructure - Math Platform

Complete Docker infrastructure for the Mathematics Study Platform.

Overview

This infrastructure includes 8 services:

1. postgres - PostgreSQL 15 database
2. redis - Redis 7 cache and message queue
3. backend - Node.js API (Express + TypeScript)
4. frontend - Next.js 14 application
5. pdf-worker - PDF processing worker
6. exercise-worker - AI-powered exercise generation
7. notification-worker - Telegram notification worker
8. nginx - Reverse proxy with rate limiting

Quick Start

1. Environment Setup

# Copy environment file
cp .env.example .env

# Edit with your values
nano .env

2. Start Services

# Start all services
docker-compose up -d

# Or use the detailed version
docker-compose -f docker/docker-compose.yml up -d

3. Check Status

# Check all services
docker-compose ps

# View logs
docker-compose logs -f

# Check specific service logs
docker-compose logs -f backend

Services Details

PostgreSQL (postgres)

• Port: 5432
• User: mathuser
• Database: mathdb
• Data Volume: postgres_data
• Health Check: pg_isready

Redis (redis)

• Port: 6379
• Password: Set in .env
• Data Volume: redis_data
• Persistence: AOF enabled

Backend API (backend)

• Port: 3001
• Node.js: 20 LTS
• TypeScript: 5+
• Health: http://localhost:3001/health
• Depends on: postgres, redis

Frontend (frontend)

• Port: 3000
• Next.js: 14 (App Router)
• UI: shadcn/ui + TailwindCSS
• Health: http://localhost:3000
• Depends on: backend

PDF Worker (pdf-worker)

• Processes PDFs from /app/pdfs
• Extracts text and exercises
• Stores results in database
• Replicas: Scale with --scale pdf-worker=N

Exercise Worker (exercise-worker)

• Generates exercises using AI (MiniMax-M2.5)
• Connects to Aliyun DashScope API
• Validates mathematical notations
• Replicas: Scale with --scale exercise-worker=N

Notification Worker (notification-worker)

• Sends Telegram notifications (admin only)
• Processes notification queue
• Replicas: Scale with --scale notification-worker=N

Nginx (nginx)

• HTTP Port: 80
• HTTPS Port: 443
• Rate Limiting:
  • /api/auth: 5 req/s
  • /api/*: 10 req/s
  • /*: 20 req/s
• Health: http://localhost/health

Docker Compose Commands

Start Services

# Start all services in background
docker-compose up -d

# Start with detailed logs
docker-compose up

# Start specific service
docker-compose up -d backend

Stop Services

# Stop all services
docker-compose down

# Stop and remove volumes
docker-compose down -v

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f backend

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

Rebuild Services

# Rebuild all images
docker-compose build --no-cache

# Rebuild specific service
docker-compose build backend

# Rebuild and start
docker-compose up -d --build backend

Scale Workers

# Scale PDF workers
docker-compose up -d --scale pdf-worker=2

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

Database Operations

# Access PostgreSQL
docker-compose exec postgres psql -U mathuser -d mathdb

# Backup database
docker-compose exec postgres pg_dump -U mathuser mathdb > backup.sql

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

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

# Generate Prisma client
docker-compose exec backend npx prisma generate

Redis Operations

# Access Redis CLI
docker-compose exec redis redis-cli -a YOUR_PASSWORD

# Monitor Redis commands
docker-compose exec redis redis-cli -a YOUR_PASSWORD monitor

# Check memory usage
docker-compose exec redis redis-cli -a YOUR_PASSWORD info memory

File Structure

/home/ren/Documents/math2/
├── docker/
│   ├── docker-compose.yml          # Detailed configuration
│   ├── Dockerfile.backend          # Backend image
│   ├── Dockerfile.frontend         # Frontend image
│   ├── Dockerfile.worker           # Workers image
│   ├── nginx.conf                  # Nginx configuration
│   ├── init-scripts/               # Database initialization
│   ├── logs/                       # Service logs
│   │   ├── backend/
│   │   ├── frontend/
│   │   ├── pdf-worker/
│   │   ├── exercise-worker/
│   │   ├── notification-worker/
│   │   └── nginx/
│   ├── data/                       # Persistent data
│   │   ├── postgres/
│   │   └── redis/
│   └── ssl/                        # SSL certificates (optional)
├── backend/                        # Backend application
├── frontend/                       # Frontend application
├── pdfs/                           # PDF files (18 files)
├── .env                            # Environment variables
├── docker-compose.yml              # Main compose file
└── README.md                       # This file

Environment Variables

See .env file for all environment variables. Key variables:

Database

• DATABASE_URL - PostgreSQL connection string
• DB_PASSWORD - Database password

Redis

• REDIS_HOST - Redis host
• REDIS_PORT - Redis port
• REDIS_PASSWORD - Redis password

AI (MiniMax-M2.5)

• AI_API_BASE_URL - API base URL
• AI_API_KEY - API key
• AI_MODEL - Model name

Telegram

• TELEGRAM_BOT_TOKEN - Bot token
• TELEGRAM_ADMIN_CHAT_ID - Admin chat ID

JWT

• JWT_SECRET - Secret key for JWT
• JWT_EXPIRES_IN - Token expiration

Health Checks

All services include health checks:

• PostgreSQL: pg_isready
• Redis: redis-cli ping
• Backend: GET /health
• Frontend: GET /
• Nginx: GET /health

Check health status:

docker-compose ps

Monitoring

Nginx Status

curl http://localhost/nginx_status

Service Logs

# Backend logs
docker-compose logs -f backend

# Frontend logs
docker-compose logs -f frontend

# Worker logs
docker-compose logs -f pdf-worker
docker-compose logs -f exercise-worker
docker-compose logs -f notification-worker

Database Monitoring

# Active connections
docker-compose exec postgres psql -U mathuser -d mathdb \
  -c "SELECT count(*) FROM pg_stat_activity;"

# Table sizes
docker-compose exec postgres psql -U mathuser -d mathdb \
  -c "SELECT schemaname,tablename,pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) FROM pg_tables WHERE schemaname = 'public' ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;"

Troubleshooting

Service Won't Start

# Check logs
docker-compose logs SERVICE_NAME

# Check resource usage
docker stats

# Restart service
docker-compose restart SERVICE_NAME

Database Connection Issues

# Check PostgreSQL is running
docker-compose ps postgres

# Check PostgreSQL logs
docker-compose logs postgres

# Test connection
docker-compose exec backend ping postgres

Redis Connection Issues

# Check Redis is running
docker-compose ps redis

# Test connection
docker-compose exec backend redis-cli -h redis -a YOUR_PASSWORD ping

Clear Everything

# Stop and remove all containers, networks, volumes
docker-compose down -v

# Remove images
docker-compose rm -f
docker rmi $(docker images -q 'math-*')

# Start fresh
docker-compose up -d

Production Deployment

1. Update Environment

# Set production values
NODE_ENV=production

2. Configure SSL (Optional)

# Place certificates in docker/ssl/
# Uncomment HTTPS server block in nginx.conf

3. Set Resource Limits

Edit docker-compose.yml to adjust resource limits for your server.

4. Enable Automatic Backups

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

Security Notes

1. Change default passwords in .env before deploying
2. Use strong JWT_SECRET in production
3. Enable HTTPS with valid SSL certificates
4. Restrict network access to PostgreSQL and Redis
5. Keep images updated with security patches
6. Monitor logs for suspicious activity
7. Implement fail2ban for brute force protection

Support

For issues or questions:

• Check logs: docker-compose logs
• Check service status: docker-compose ps
• Review configuration: docker-compose config