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

```bash
# Copy environment file
cp .env.example .env

# Edit with your values
nano .env
```

### 2. Start Services

```bash
# Start all services
docker-compose up -d

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

### 3. Check Status

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

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

```bash
# Stop all services
docker-compose down

# Stop and remove volumes
docker-compose down -v
```

### View Logs

```bash
# All services
docker-compose logs -f

# Specific service
docker-compose logs -f backend

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

### Rebuild Services

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

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

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

### Database Operations

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

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

```bash
docker-compose ps
```

## Monitoring

### Nginx Status

```bash
curl http://localhost/nginx_status
```

### Service Logs

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

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

```bash
# Check logs
docker-compose logs SERVICE_NAME

# Check resource usage
docker stats

# Restart service
docker-compose restart SERVICE_NAME
```

### Database Connection Issues

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

```bash
# Check Redis is running
docker-compose ps redis

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

### Clear Everything

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

```bash
# Set production values
NODE_ENV=production
```

### 2. Configure SSL (Optional)

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

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