12 KiB
OpenCCB - Instrucciones de Despliegue (AWS EC2)
Resumen
OpenCCB utiliza nginx-proxy + acme-companion para SSL automático con Let's Encrypt.
| Componente | Función |
|---|---|
| nginx-proxy | Reverse proxy que maneja el tráfico HTTP/HTTPS |
| acme-companion | Gestiona certificados SSL de Let's Encrypt automáticamente |
| Studio + CMS | Administración de cursos (puerto 3000/3001) |
| Experience + LMS | Experiencia del estudiante (puerto 3003/3002) |
| PostgreSQL + PGVector | Base de datos con búsqueda semántica |
Despliegue Rápido
Paso 1: Desde tu máquina local
# Ejecutar el script de despliegue
./deploy.sh
Este script hace TODO automáticamente:
- ✅ Copia todos los archivos al servidor
- ✅ Instala Docker y Docker Compose
- ✅ Genera credenciales seguras (DB_PASSWORD, JWT_SECRET)
- ✅ Configura las variables de entorno correctas
- ✅ Inicia nginx-proxy y acme-companion
- ✅ Crea las bases de datos
- ✅ Inicia todos los servicios
- ✅ Obtiene certificados SSL automáticamente
Paso 2: Verificar estado (opcional)
# Conectarse al servidor
ssh -i "ubuntu.pem" ubuntu@ec2-18-224-137-67.us-east-2.compute.amazonaws.com
cd /var/www/openccb
# Ver estado de contenedores
sudo docker compose ps
# Ver logs de SSL
docker logs acme-companion --tail 50
URLs de Acceso
Después del despliegue (esperar 2-5 minutos para SSL):
https://studio.norteamericano.com (CMS/Admin)
https://learning.norteamericano.com (LMS/Estudiantes)
Requisitos Previos
Seguridad de certificados (git)
Nunca versionar material de certificados o cuentas ACME del servidor.
Rutas sensibles (ejemplos):
nginx/certs-data/
*.key
*.csr
*.crt
Estas rutas deben permanecer ignoradas por git y gestionarse solo en el servidor/volumen de runtime.
1. Configurar DNS
Antes de ejecutar deploy.sh, configura los registros DNS en tu proveedor de dominio:
| Tipo | Nombre | Valor | TTL |
|---|---|---|---|
| A | @ | 18.224.137.67 | 300 |
| A | studio | 18.224.137.67 | 300 |
| A | learning | 18.224.137.67 | 300 |
Verificación:
dig studio.norteamericano.com
dig learning.norteamericano.com
2. Configurar Security Group de AWS
En la consola de AWS EC2, edita el Security Group de tu instancia:
| Tipo | Protocolo | Puerto | Fuente |
|---|---|---|---|
| SSH | TCP | 22 | Tu IP |
| HTTP | TCP | 80 | 0.0.0.0/0 |
| HTTPS | TCP | 443 | 0.0.0.0/0 |
3. Archivo de llave SSH
Asegúrate de tener ubuntu.pem en el directorio del proyecto:
chmod 400 ubuntu.pem
Comandos Útiles
Ver estado de servicios
sudo docker compose ps
Ver logs en tiempo real
sudo docker compose logs -f
Ver logs de un servicio específico
# Studio (CMS)
docker logs openccb-studio --tail 20
# Experience (LMS)
docker logs openccb-experience --tail 20
# Base de datos
docker logs openccb-db --tail 20
# nginx-proxy
docker logs nginx-proxy --tail 20
# SSL (acme-companion)
docker logs acme-companion --tail 50
Validacion rapida de LMS (post-deploy)
Despues de desplegar, valida que el backend LMS realmente levanto en 3002 y que no quedo con una URL de DB local invalida dentro de Docker.
# Health interno desde la red Docker
docker exec openccb-studio node -e "fetch('http://experience:3002/health').then(async r=>{console.log(r.status);console.log(await r.text())})"
# Ver variables activas en experience
docker exec openccb-experience sh -lc 'echo DATABASE_URL=$DATABASE_URL; echo LMS_DATABASE_URL=$LMS_DATABASE_URL'
Valores esperados en Docker:
DATABASE_URL=postgresql://user:<password>@db:5432/openccb_lms
LMS_DATABASE_URL=postgresql://user:<password>@db:5432/openccb_lms
CMS_API_URL=http://studio:3001
Si aparece localhost:5433 en el contenedor openccb-experience, recrea el servicio con la variable correcta:
LMS_DATABASE_URL='postgresql://user:password@db:5432/openccb_lms' docker compose up -d --force-recreate experience
LMS /auth/me devuelve 502 Bad Gateway
Síntoma común: login correcto en CMS, pero GET /auth/me desde LMS falla con No se pudo sincronizar el perfil de usuario desde CMS.
Causa común: CMS_API_URL faltante o incorrecta dentro del contenedor experience.
Solución:
docker exec openccb-experience sh -lc 'echo CMS_API_URL=$CMS_API_URL'
# Valor recomendado en Docker Compose
CMS_API_URL=http://studio:3001
# Recrear el servicio con la variable corregida
CMS_API_URL='http://studio:3001' docker compose up -d --force-recreate experience
Reiniciar servicios
# Reiniciar todo
sudo docker compose restart
# Reiniciar un servicio específico
sudo docker compose restart studio
Detener servicios
sudo docker compose down
Reconstruir desde cero
# ⚠️ Esto elimina todos los datos
sudo docker compose down -v
sudo docker compose up -d --build
Solución de Problemas
Error 502 Bad Gateway
Causa: nginx-proxy no puede conectar con los servicios backend.
Solución:
# 1. Verificar que los servicios están corriendo
sudo docker compose ps
# 2. Ver logs de Studio
docker logs openccb-studio --tail 20
# 3. Ver logs de nginx
docker logs nginx-proxy --tail 20
# 4. Reiniciar servicios
sudo docker compose restart
LMS inicia pero API no responde en 3002
Sintoma comun: el frontend en 3003 carga, pero /lms-api/* falla y en logs aparece PoolTimedOut.
Causa comun: openccb-experience arranco con DATABASE_URL o LMS_DATABASE_URL apuntando a localhost:5433 (invalido dentro del contenedor).
Solucion:
docker logs openccb-experience --tail 80
docker exec openccb-experience sh -lc 'echo DATABASE_URL=$DATABASE_URL; echo LMS_DATABASE_URL=$LMS_DATABASE_URL'
LMS_DATABASE_URL='postgresql://user:password@db:5432/openccb_lms' docker compose up -d --force-recreate experience
Smoke test de permisos de audio (admin/instructor/student)
Existe un script para validar reglas de acceso de evaluaciones de audio en LMS:
./scripts/smoke_audio_roles.sh
El script crea fixtures temporales, ejecuta validaciones y limpia automaticamente.
Para debug sin limpiar datos:
KEEP_FIXTURES=1 ./scripts/smoke_audio_roles.sh
Certificados SSL no se generan
Síntomas:
- Error de conexión SSL en el navegador
acme-companionmuestra errores de rate limit
Solución:
# 1. Verificar DNS
dig studio.norteamericano.com
dig learning.norteamericano.com
# 2. Verificar que nginx-proxy está corriendo
sudo docker compose ps nginx-proxy
# 3. Ver logs de acme-companion
docker logs acme-companion --tail 100
# 4. Verificar puertos
sudo netstat -tlnp | grep -E ':80|:443'
# 5. Esperar 1 hora (rate limit de Let's Encrypt)
Base de datos no está disponible
# 1. Verificar estado de la DB
sudo docker compose ps db
# 2. Ver logs de la DB
docker logs openccb-db --tail 20
# 3. Reiniciar DB
sudo docker compose restart db
# 4. Verificar bases de datos
sudo docker exec openccb-db psql -U user -d postgres -c "\l"
Error de conexión SSH
# Verificar permisos del archivo .pem
chmod 400 ubuntu.pem
# Probar conexión
ssh -i "ubuntu.pem" ubuntu@ec2-18-224-137-67.us-east-2.compute.amazonaws.com
Actualización de la Plataforma
Método recomendado
# Desde tu máquina local
./deploy.sh
El script sincronizará los cambios y reconstruirá los contenedores automáticamente.
Backup y Restauración
Backup de base de datos
# Conectarse al servidor
ssh -i "ubuntu.pem" ubuntu@ec2-18-224-137-67.us-east-2.compute.amazonaws.com
cd /var/www/openccb
# Crear backup
sudo docker exec openccb-db pg_dump -U user openccb_cms > backup_cms_$(date +%Y%m%d).sql
sudo docker exec openccb-db pg_dump -U user openccb_lms > backup_lms_$(date +%Y%m%d).sql
# Descargar backup a tu máquina local
scp -i "ubuntu.pem" ubuntu@ec2-18-224-137-67.us-east-2.compute.amazonaws.com:/var/www/openccb/backup_*.sql .
Restaurar base de datos
# Subir backup al servidor
scp -i "ubuntu.pem" backup_cms_20250101.sql ubuntu@ec2-18-224-137-67.us-east-2.compute.amazonaws.com:/var/www/openccb/
# Conectarse al servidor
ssh -i "ubuntu.pem" ubuntu@ec2-18-224-137-67.us-east-2.compute.amazonaws.com
cd /var/www/openccb
# Restaurar
sudo docker exec -i openccb-db psql -U user -d openccb_cms < backup_cms_20250101.sql
sudo docker exec -i openccb-db psql -U user -d openccb_lms < backup_lms_20250101.sql
Seguridad
Credenciales por Defecto
Después de ejecutar deploy.sh, las credenciales se generan automáticamente:
- DB_PASSWORD: Contraseña de base de datos (generada aleatoriamente)
- JWT_SECRET: Secreto JWT (generado aleatoriamente)
Estas credenciales se guardan en el archivo .env. Guárdalas en un lugar seguro.
Usuario Admin Inicial
El primer usuario admin se crea durante la instalación inicial con:
- Email: admin@norteamericano.com
- Contraseña: La que definas durante la instalación
Arquitectura del Sistema
┌─────────────────────────────────────────────────────┐
│ AWS EC2 │
│ │
│ ┌─────────────┐ ┌──────────────────────────┐ │
│ │ nginx │───▶│ Studio + CMS │ │
│ │ proxy │ │ (Next.js + Rust) │ │
│ │ :80, :443 │ │ :3000, :3001 │ │
│ └──────┬──────┘ └──────────┬───────────────┘ │
│ │ │ │
│ │ ┌─────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────┐ ┌──────────────────────────┐ │
│ │ acme │ │ Experience + LMS │ │
│ │ companion │ │ (Next.js + Rust) │ │
│ │ (Let's │ │ :3003, :3002 │ │
│ │ Encrypt) │ └──────────┬───────────────┘ │
│ └─────────────┘ │ │
│ │ │
│ ┌──────────▼───────────────┐ │
│ │ PostgreSQL + PGVector │ │
│ │ :5432 │ │
│ └──────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────┘
Notas Importantes
- Certificados automáticos: Se renuevan automáticamente con Let's Encrypt
- Puertos usados:
- 80: HTTP (redirección a HTTPS, validación Let's Encrypt)
- 443: HTTPS (tráfico web)
- 5432: PostgreSQL (interno de Docker)
- 3000-3003: Internos de los servicios
- Volúmenes persistentes:
postgres_data: Datos de la base de datosuploads_data: Archivos subidos por usuarioscerts: Certificados SSLvhost: Configuración virtual de nginx
Fecha: Marzo 2026
Versión: OpenCCB 0.3.0
Servidor: AWS EC2 us-east-2
Instancia: ec2-18-224-137-67.us-east-2.compute.amazonaws.com