🎓 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
575
docs/DEPLOYMENT.md
Normal file
575
docs/DEPLOYMENT.md
Normal file
@@ -0,0 +1,575 @@
|
||||
# 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:**
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
|
||||
```bash
|
||||
# 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
|
||||
# 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:**
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
|
||||
```yaml
|
||||
# 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:**
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Prometheus metrics (if enabled)
|
||||
curl http://localhost:9090/metrics
|
||||
|
||||
# Custom application metrics
|
||||
curl http://localhost:3001/metrics
|
||||
```
|
||||
|
||||
## Scaling
|
||||
|
||||
### Horizontal Scaling
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
backend:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '2.0'
|
||||
memory: 2G
|
||||
reservations:
|
||||
cpus: '1.0'
|
||||
memory: 1G
|
||||
```
|
||||
|
||||
## Blue-Green Deployment
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```yaml
|
||||
# .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](../README.md)
|
||||
- Contact: devops@mathplatform.com
|
||||
Reference in New Issue
Block a user