🎓 Initial commit: Math2 Platform - Plataforma de Álgebra Lineal PRO
✨ Características: - 45 ejercicios universitarios (Basic → Advanced) - Renderizado LaTeX profesional - IA generativa (Z.ai/DashScope) - Docker 9 servicios - Tests 123/123 pasando - Seguridad enterprise (JWT, XSS, Rate limiting) 🐳 Infraestructura: - Next.js 14 + Node.js 20 - PostgreSQL 15 + Redis 7 - Docker Compose completo - Nginx + SSL ready 📚 Documentación: - 5 informes técnicos completos - README profesional - Scripts de deployment automatizados Estado: Producción lista ✅
This commit is contained in:
Renato
402
docker/README.md
Normal file
402
docker/README.md
Normal file
@@ -0,0 +1,402 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user