renato97/math2-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
math2-platform/docs/DEPLOYMENT_ENV_VARS.md
Renato bc43c9e772
Some checks failed
Test Suite / test-backend (push) Has been cancelled
Details
Test Suite / test-frontend (push) Has been cancelled
Details
Test Suite / e2e-tests (push) Has been cancelled
Details
Test Suite / coverage-check (push) Has been cancelled
Details
🎓 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 ✅
2026-03-31 11:27:11 -03:00

426 lines
13 KiB
Markdown
Raw Permalink Blame History

# Variables de Entorno para Deployment en Producción
## Math2 Platform - Production Environment Variables
Este documento lista **TODAS** las variables de entorno necesarias para ejecutar Math2 Platform en modo producción local.
---
## 🔴 CRÍTICAS - Obligatorias
Estas variables **DEBEN** estar configuradas antes de iniciar el deployment.
### Base de Datos
| Variable | Descripción | Ejemplo | Requerida |
|----------|-------------|---------|-----------|
| `DATABASE_URL` | URL de conexión a PostgreSQL | `postgresql://mathuser:securepass@localhost:5432/mathdb` | ✅ Si |
| `DB_USER` | Usuario de PostgreSQL | `mathuser` | ✅ No (default: mathuser) |
| `DB_PASSWORD` | Contraseña de PostgreSQL | `SecureP@ssw0rd123!` | ✅ Si |
| `DB_NAME` | Nombre de la base de datos | `mathdb` | ✅ No (default: mathdb) |
> **Nota**: Si `DATABASE_URL` está definida, `DB_USER`, `DB_PASSWORD` y `DB_NAME` son opcionales para Docker Compose.
### Seguridad
| Variable | Descripción | Ejemplo | Requerida |
|----------|-------------|---------|-----------|
| `JWT_SECRET` | Clave secreta para tokens JWT (mín. 32 chars) | `your-super-secret-jwt-key-min-32-chars!` | ✅ Si |
| `REDIS_PASSWORD` | Contraseña para Redis | `redis_secure_pass_2024` | ✅ Si |
| `SESSION_SECRET` | Clave para sesiones | `session-secret-min-32-chars-long` | ✅ No (default: generado) |
---
## 🟡 IMPORTANTES - Recomendadas
Estas variables deberían configurarse para un funcionamiento óptimo.
### Inteligencia Artificial (AI/LLM)
| Variable | Descripción | Ejemplo | Default |
|----------|-------------|---------|---------|
| `AI_API_BASE_URL` | URL base de la API de AI | `https://coding-intl.dashscope.aliyuncs.com/v1` | - |
| `AI_API_KEY` | API Key para servicio de AI | `sk-xxxxxxxxxxxxxxxx` | - |
| `AI_MODEL` | Modelo de AI a utilizar | `MiniMax-M2.5` | `MiniMax-M2.5` |
| `AI_MAX_TOKENS` | Máximo de tokens por request | `2000` | `2000` |
| `AI_TEMPERATURE` | Temperatura para generación | `0.7` | `0.7` |
> **Nota**: Sin estas variables, el sistema funcionará pero sin capacidad de generar ejercicios con AI.
### Telegram (Notificaciones)
| Variable | Descripción | Ejemplo | Default |
|----------|-------------|---------|---------|
| `TELEGRAM_BOT_TOKEN` | Token del bot de Telegram | `123456789:ABCdefGHIjklMNOpqrSTU` | - |
| `TELEGRAM_ADMIN_CHAT_ID` | Chat ID del administrador | `123456789` | - |
| `TELEGRAM_NOTIFICATIONS_ENABLED` | Habilitar notificaciones | `true` | `true` |
> **Nota**: Sin estas variables, las notificaciones por Telegram no funcionarán.
### CORS y URLs
| Variable | Descripción | Ejemplo Producción | Default |
|----------|-------------|-------------------|---------|
| `CORS_ORIGIN` | Origen permitido para CORS | `https://tudominio.com` | `http://localhost:3000` |
| `FRONTEND_URL` | URL del frontend | `https://tudominio.com` | `http://localhost:3000` |
| `BACKEND_URL` | URL del backend | `https://api.tudominio.com` | `http://localhost:3001` |
| `NEXT_PUBLIC_API_URL` | URL pública de API para frontend | `/api` | `/api` |
---
## 🟢 OPCIONALES - Configuración Avanzada
### Rate Limiting
| Variable | Descripción | Default |
|----------|-------------|---------|
| `RATE_LIMIT_WINDOW_MS` | Ventana de tiempo para rate limiting | `900000` (15 min) |
| `RATE_LIMIT_MAX_REQUESTS` | Máximo de requests por ventana | `100` |
| `STRICT_RATE_LIMIT_MAX` | Límite estricto para endpoints sensibles | `5` |
| `AUTH_RATE_LIMIT_WINDOW_MS` | Ventana para auth endpoints | `900000` |
| `AUTH_RATE_LIMIT_MAX` | Máximo para auth endpoints | `20` |
### Configuración de JWT
| Variable | Descripción | Default |
|----------|-------------|---------|
| `JWT_EXPIRES_IN` | Tiempo de expiración del JWT | `15m` |
| `JWT_REFRESH_EXPIRES_IN` | Tiempo de expiración del refresh token | `30d` |
### Redis
| Variable | Descripción | Default |
|----------|-------------|---------|
| `REDIS_HOST` | Host de Redis | `localhost` (dev) / `redis` (docker) |
| `REDIS_PORT` | Puerto de Redis | `6379` |
| `REDIS_DB` | Base de datos Redis | `0` |
### Archivos y Uploads
| Variable | Descripción | Default |
|----------|-------------|---------|
| `MAX_FILE_SIZE_MB` | Tamaño máximo de archivo (MB) | `10` |
| `UPLOAD_DIR` | Directorio de uploads | `./uploads` |
| `PDF_PROCESSING_DIR` | Directorio para PDFs | `./uploads/pdfs` |
### Procesamiento de PDFs
| Variable | Descripción | Default |
|----------|-------------|---------|
| `PDF_CONCURRENCY` | Concurrencia de procesamiento | `3` |
| `PDF_TIMEOUT_MS` | Timeout para procesamiento | `300000` (5 min) |
| `PDF_QUALITY` | Calidad de procesamiento | `medium` |
### Workers
| Variable | Descripción | Default |
|----------|-------------|---------|
| `WORKER_CONCURRENCY` | Concurrencia de workers | `3` |
| `WORKER_MAX_JOBS_PER_WORKER` | Máximo de jobs por worker | `10` |
| `WORKER_STUCK_TOKENS_THRESHOLD` | Umbral para detectar stuck | `10000` |
| `WORKER_STUCK_INTERVAL` | Intervalo de revisión stuck | `5000` |
### Logging
| Variable | Descripción | Default |
|----------|-------------|---------|
| `LOG_LEVEL` | Nivel de logging | `info` (prod) / `debug` (dev) |
| `LOG_DIR` | Directorio de logs | `./logs` |
| `ENABLE_QUERY_LOGGING` | Log de queries SQL | `false` (prod) |
### Cache
| Variable | Descripción | Default |
|----------|-------------|---------|
| `CACHE_TTL_SECONDS` | TTL del caché (segundos) | `3600` (1 hora) |
| `ENABLE_CACHE` | Habilitar caché | `true` |
### Sesiones
| Variable | Descripción | Default |
|----------|-------------|---------|
| `SESSION_MAX_AGE_MS` | Duración de sesión (ms) | `86400000` (24 horas) |
### Notificaciones
| Variable | Descripción | Default |
|----------|-------------|---------|
| `NOTIFICATION_RETRY_ATTEMPTS` | Intentos de reintento | `3` |
| `NOTIFICATION_RETRY_DELAY_MS` | Delay entre reintentos | `1000` |
| `DAILY_SUMMARY_ENABLED` | Resumen diario habilitado | `true` |
| `DAILY_SUMMARY_TIME` | Hora del resumen | `00:00` |
### Ranking y Logros
| Variable | Descripción | Default |
|----------|-------------|---------|
| `RANKING_UPDATE_INTERVAL_MS` | Intervalo de actualización ranking | `60000` (1 min) |
| `RANKING_CACHE_TTL_SECONDS` | TTL del caché de ranking | `300` (5 min) |
| `LEADERBOARD_SIZE` | Tamaño del leaderboard | `100` |
| `ACHIEVEMENT_CHECK_INTERVAL_MS` | Intervalo de check de logros | `30000` (30 seg) |
| `BADGE_AUTO_AWARD` | Auto-asignar badges | `true` |
### Monitoreo
| Variable | Descripción | Default |
|----------|-------------|---------|
| `HEALTH_CHECK_INTERVAL_MS` | Intervalo de health checks | `30000` (30 seg) |
| `ENABLE_METRICS` | Habilitar métricas Prometheus | `true` |
| `METRICS_PORT` | Puerto para métricas | `9090` |
### Feature Flags
| Variable | Descripción | Default |
|----------|-------------|---------|
| `ENABLE_REGISTRATION` | Habilitar registro de usuarios | `true` |
| `ENABLE_AI_GENERATION` | Habilitar generación con AI | `true` |
| `ENABLE_PDF_PROCESSING` | Habilitar procesamiento de PDFs | `true` |
| `ENABLE_TELEGRAM_NOTIFICATIONS` | Habilitar notificaciones Telegram | `true` |
| `ENABLE_RANKING_SYSTEM` | Habilitar sistema de ranking | `true` |
| `ENABLE_ACHIEVEMENTS` | Habilitar sistema de logros | `true` |
| `MAINTENANCE_MODE` | Modo mantenimiento | `false` |
### Configuración de Docker
| Variable | Descripción | Default |
|----------|-------------|---------|
| `VERSION` | Versión de las imágenes Docker | `1.0.0` |
| `COMPOSE_PROJECT_NAME` | Nombre del proyecto Docker | `math2` |
---
## 📋 Plantilla .env para Producción
```bash
# ============================================
# MATH2 PLATFORM - PRODUCTION ENVIRONMENT
# ============================================
# Copiar a .env y configurar valores reales
# NUNCA commitear este archivo con valores reales
# ============================================
# ============================================
# CRÍTICAS - Obligatorias
# ============================================
DB_PASSWORD=CHANGE_THIS_TO_STRONG_PASSWORD
REDIS_PASSWORD=CHANGE_THIS_TO_STRONG_PASSWORD
JWT_SECRET=CHANGE_THIS_TO_MIN_32_CHARS_SECRET_KEY
# ============================================
# BASE DE DATOS
# ============================================
DATABASE_URL=postgresql://mathuser:${DB_PASSWORD}@postgres:5432/mathdb
DB_USER=mathuser
DB_NAME=mathdb
# ============================================
# REDIS
# ============================================
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_DB=0
# ============================================
# AI / LLM (MiniMax-M2.5 - DashScope)
# ============================================
AI_API_BASE_URL=https://coding-intl.dashscope.aliyuncs.com/v1
AI_API_KEY=your-dashscope-api-key-here
AI_MODEL=MiniMax-M2.5
AI_MAX_TOKENS=2000
AI_TEMPERATURE=0.7
# ============================================
# TELEGRAM
# ============================================
TELEGRAM_BOT_TOKEN=your-telegram-bot-token-here
TELEGRAM_ADMIN_CHAT_ID=your-admin-chat-id-here
TELEGRAM_NOTIFICATIONS_ENABLED=true
# ============================================
# SEGURIDAD
# ============================================
JWT_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=30d
SESSION_SECRET=CHANGE_THIS_SESSION_SECRET_MIN_32_CHARS
# ============================================
# CORS Y URLs
# ============================================
NODE_ENV=production
PORT=3001
BACKEND_URL=http://localhost:3001
FRONTEND_URL=http://localhost
CORS_ORIGIN=http://localhost
NEXT_PUBLIC_API_URL=/api
NEXT_PUBLIC_APP_NAME=Plataforma de Álgebra Lineal
# ============================================
# RATE LIMITING
# ============================================
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100
STRICT_RATE_LIMIT_MAX=5
AUTH_RATE_LIMIT_WINDOW_MS=900000
AUTH_RATE_LIMIT_MAX=20
# ============================================
# UPLOADS
# ============================================
MAX_FILE_SIZE_MB=10
UPLOAD_DIR=./uploads
PDF_PROCESSING_DIR=./uploads/pdfs
# ============================================
# PDF
# ============================================
PDF_CONCURRENCY=3
PDF_TIMEOUT_MS=300000
PDF_QUALITY=medium
# ============================================
# WORKERS
# ============================================
WORKER_CONCURRENCY=3
WORKER_MAX_JOBS_PER_WORKER=10
WORKER_STUCK_TOKENS_THRESHOLD=10000
WORKER_STUCK_INTERVAL=5000
# ============================================
# LOGGING
# ============================================
LOG_LEVEL=info
LOG_DIR=./logs
ENABLE_QUERY_LOGGING=false
# ============================================
# CACHE
# ============================================
CACHE_TTL_SECONDS=3600
ENABLE_CACHE=true
# ============================================
# SESSION
# ============================================
SESSION_MAX_AGE_MS=86400000
# ============================================
# NOTIFICACIONES
# ============================================
NOTIFICATION_RETRY_ATTEMPTS=3
NOTIFICATION_RETRY_DELAY_MS=1000
DAILY_SUMMARY_ENABLED=true
DAILY_SUMMARY_TIME=00:00
# ============================================
# RANKING
# ============================================
RANKING_UPDATE_INTERVAL_MS=60000
RANKING_CACHE_TTL_SECONDS=300
LEADERBOARD_SIZE=100
# ============================================
# LOGROS
# ============================================
ACHIEVEMENT_CHECK_INTERVAL_MS=30000
BADGE_AUTO_AWARD=true
# ============================================
# MONITOREO
# ============================================
HEALTH_CHECK_INTERVAL_MS=30000
ENABLE_METRICS=true
METRICS_PORT=9090
# ============================================
# FEATURE FLAGS
# ============================================
ENABLE_REGISTRATION=true
ENABLE_AI_GENERATION=true
ENABLE_PDF_PROCESSING=true
ENABLE_TELEGRAM_NOTIFICATIONS=true
ENABLE_RANKING_SYSTEM=true
ENABLE_ACHIEVEMENTS=true
MAINTENANCE_MODE=false
# ============================================
# DOCKER
# ============================================
VERSION=1.0.0
COMPOSE_PROJECT_NAME=math2
```
---
## 🔒 Seguridad
### Checklist de Seguridad para Producción
- [ ] `JWT_SECRET` tiene al menos 32 caracteres aleatorios
- [ ] `REDIS_PASSWORD` es fuerte y única
- [ ] `DB_PASSWORD` es fuerte y única
- [ ] No hay credenciales hardcodeadas en el código
- [ ] El archivo `.env` está en `.gitignore`
- [ ] Variables sensibles no aparecen en logs
- [ ] SSL/TLS está configurado para tráfico HTTPS
### Generar Secretos Fuertes
```bash
# JWT_SECRET (32+ chars)
openssl rand -base64 48
# Redis Password
openssl rand -base64 24
# DB Password
openssl rand -base64 24
# Session Secret
openssl rand -base64 48
```
---
## 🚀 Deployment
### Pasos para Deployment Local en Producción
1. **Copiar y configurar variables**:
```bash
cp .env.example .env
nano .env # Editar con valores reales
```
2. **Verificar variables**:
```bash
./scripts/verify-production.sh
```
3. **Iniciar en modo producción**:
```bash
./scripts/start-production.sh
```
### Troubleshooting
| Problema | Causa Probable | Solución |
|----------|----------------|----------|
| `DATABASE_URL not set` | Variables no cargadas | Ejecutar `source .env` antes |
| `Redis connection failed` | Contraseña incorrecta | Verificar `REDIS_PASSWORD` |
| `JWT verification failed` | Secreto incorrecto | Verificar `JWT_SECRET` |
| `AI generation failed` | API Key inválida | Verificar `AI_API_KEY` |
---
## 📚 Referencias
- [DEPLOYMENT.md](./DEPLOYMENT.md) - Guía completa de deployment
- [SECURITY.md](./SECURITY.md) - Guía de seguridad
- [ARCHITECTURE.md](./ARCHITECTURE.md) - Arquitectura del sistema
---
**Última actualización:** Marzo 2026
**Versión:** 1.0.0
**Mantenido por:** DevOps Team
Reference in New Issue View Git Blame Copy Permalink