Entorno local
Cómo levantar la Academia Deltamontero en un equipo de desarrollo o de pruebas con Docker.
El repositorio es, en sí mismo, el entorno local de desarrollo: con Docker se levanta la misma plataforma que corre en producción (Moodle, cron y base de datos), con la dirección http://localhost:8080.
Requisitos
| Requisito | Detalle |
|---|---|
Docker con docker compose (plugin v2) | Los scripts de recuperación lo exigen (docker compose version) |
| Copia del repositorio | Es privado: se necesita acceso en GitHub |
| Acceso a internet durante la construcción | La imagen descarga Moodle y los plugins de GitHub, y los paquetes de Debian y Python |
| Bash | Para los scripts de respaldo. En Windows sirve Git Bash: los scripts ya exportan MSYS_NO_PATHCONV=1 |
| Memoria | El docker-compose.yml limita los contenedores a 3 GB (moodle), 1 GB (moodle-cron) y 2 GB (mariadb) |
Archivos que intervienen
| Archivo | Para qué |
|---|---|
docker-compose.yml | La composición completa (la misma de producción) |
docker-compose.override.yml | Se carga solo en local: publica el puerto 8080, fija MOODLE_WWWROOT=http://localhost:8080 en moodle y moodle-cron y quita las etiquetas de Traefik |
.env.example | Plantilla de variables. Se copia a .env |
.env | Variables reales del equipo. Nunca se sube al repositorio (está en .gitignore) |
.dockerignore | Lista blanca de lo que entra en la imagen. Un archivo que no esté en esa lista no llega al contenedor |
Primer arranque
Crear el archivo de variables
cp .env.example .envEdite .env y reemplace todos los valores CHANGE-ME. Son obligatorios:
MYSQL_ROOT_PASSWORDyMYSQL_PASSWORD: sin ellas el contenedor no arranca.MOODLE_ADMIN_PASSWORD: sin ella no se instala Moodle en el primer arranque. Según.env.example: mínimo 10 caracteres, con mayúsculas y números.
No hace falta tocar MOODLE_WWWROOT: en local la reemplaza docker-compose.override.yml. El detalle de cada variable está en Variables de entorno.
En local deje vacías las variables MOODLE_SMTP_*, o use un buzón de prueba (por ejemplo Mailpit) o MOODLE_MAIL_DIVERT_TO con su propio correo, para que ningún correo salga de verdad a personas reales.
Construir la imagen y levantar todo
docker compose up -d --buildLa construcción descarga Moodle y los plugins en versiones fijas, aplica los parches y comprueba que los parches importantes quedaron aplicados (si falta uno, la construcción falla). En la prueba registrada tardó unos 11 minutos.
Seguir el primer arranque
docker compose logs -f moodleEl primer arranque instala Moodle y aplica toda la configuración de la Academia: tarda varios minutos (el README del repositorio estima 3 a 5). Los arranques siguientes duran alrededor de 30 segundos. Mientras tanto Docker puede marcar el servicio como no sano: el control de salud de moodle y de moodle-cron tiene un margen de arranque de 15 minutos.
Entrar
Abra http://localhost:8080 con el usuario admin (o el definido en MOODLE_ADMIN_USER) y la contraseña de MOODLE_ADMIN_PASSWORD.
Qué hace el primer arranque
El contenedor moodle ejecuta entrypoint.sh en este orden (el detalle está en Arranque y actualizaciones):
- Espera la base de datos y genera
config.phpdesde las variables de entorno. - Si la base no tiene tablas
mdl_*, instala Moodle en español con el nombre del sitio y la cuenta de administrador. - Ejecuta
upgrade.php(siempre) y purga las cachés. - Aplica la configuración de la Academia con
moodle-config.sh: idioma, zona horaria, tema y colores, logos, seguridad, correo, plantilla de certificado, reglas de la Academia, perfiles y permisos, y más. - Arranca Apache.
El contenedor moodle-cron genera el mismo config.php, espera a que Moodle esté instalado y ejecuta el cron cada 60 segundos.
La instalación solo ocurre si la base de datos está vacía. Borrar el volumen moodledata no reinstala Moodle: solo se pierden los archivos.
Trabajar con datos reales en local
Para probar con una copia de producción, se restaura un respaldo con la opción --local, que incluye docker-compose.override.yml (puerto 8080 y dirección local):
infrastructure/scripts/restore.sh --dry-run backups/delta-lms_backup_X.tar
infrastructure/scripts/restore.sh --local backups/delta-lms_backup_X.tarUn respaldo de producción contiene datos personales (nombres, cédulas, correos, notas) y la cola de correos pendientes. Antes de restaurarlo en otro equipo, asegúrese de que esa instalación no tenga las variables MOODLE_SMTP_* o tenga MOODLE_MAIL_DIVERT_TO con un buzón propio. Si no, los correos en cola salen dos veces a personas reales. Ver Recuperación.
Comandos útiles
# Arranque normal (imagen ya construida)
docker compose up -d
# Reconstruir solo la imagen de Moodle (por ejemplo, tras cambiar el Dockerfile)
docker compose build moodle
# Registros
docker compose logs -f moodle
docker compose logs -f moodle-cron
# Parar sin destruir datos
docker compose down
# Reinicio total: DESTRUYE la base de datos y moodledata
docker compose down -v
# Consola dentro del contenedor
docker exec -it delta-lms_app bash
# Purgar cachés y forzar la actualización de Moodle
docker exec -it delta-lms_app php /var/www/html/admin/cli/purge_caches.php
docker exec -it delta-lms_app php /var/www/html/admin/cli/upgrade.php --non-interactive
# Respaldo manual del entorno local
./infrastructure/scripts/backup.sh ./backupsLos respaldos locales quedan en backups/, que está en .gitignore.
Scripts de una sola vez
La imagen incluye scripts PHP en la raíz del contenedor (/) que no se ejecutan en cada arranque y se lanzan a mano cuando hacen falta. Ejemplos documentados en el README del repositorio:
# Crear los cursos desde el inventario docs/modules-info/academia_dm_contenido.json (idempotente)
docker exec delta-lms_app php /create-courses.php
# Volver a crear la plantilla del certificado (también se ejecuta en cada arranque)
docker exec delta-lms_app php /create-certificate-template.phpEl orden completo para poblar una instalación vacía con todo el contenido de la Academia (personal, módulos, pruebas, IA) no está documentado como procedimiento en el repositorio: Por confirmar. Para tener los datos reales, lo recomendado es restaurar un respaldo. Los scripts de contenido se describen en Desarrollo.
Levantar la Academia desde cero
Procedimiento completo y en orden para montar la arquitectura, cargar las variables del sistema (base de datos, correo, seguridad, IA) y restaurar un respaldo en un servidor nuevo.
Despliegue en producción
Cómo se despliega la Academia con Coolify y Traefik (hoy en la red interna; publicación con Cloudflare planificada), qué variables cargar y cómo hacer un Redeploy sin riesgos.