Instalar Quire con Docker Compose

Este es el producto completo en un solo host: el LMS, sus tareas en segundo plano, los servicios de colaboración y tiempo real, y todos los servicios opcionales detrás de perfiles. El diseño se describe en la sección 2 de docs/architecture/23-ops.md.

Otros destinos: Vercel y Cloudflare Workers ejecutan solo la capa web. Consulta upgrade.md para las actualizaciones y backup-restore.md para respaldos y el simulacro de restauración.

Requisitos

• Docker Engine 27 o posterior, con el complemento Compose 2.30 o posterior.
• 4 núcleos de CPU y 8 GB de memoria para la configuración predeterminada; 8 núcleos y 16 GB con --profile full (solo ClamAV necesita aproximadamente 1.5 GB para las firmas).
• Un nombre DNS para la capa web y otro para el contenido no confiable. Deben ser hosts distintos: los paquetes SCORM y el HTML cargado se ejecutan desde el origen de contenido, así nunca pueden leer las cookies del LMS.
• Para una prueba local, lvh.me y *.localhost resuelven a 127.0.0.1, que es lo que configura docker/.env.example. El servicio proxy de la pila sirve ambos por https con una autoridad de certificación local, así que no necesitas instalar nada más (consulta «TLS»).
• Los puertos 80 y 443 deben estar disponibles en el host (QUIRE_PROXY_HTTP_PORT y QUIRE_PROXY_HTTPS_PORT permiten cambiarlos).

Primera ejecución

QUIRE_APP_ORIGIN=https://learn.example.org \
QUIRE_CONTENT_ORIGIN=https://content.example-content.org \
QUIRE_SETUP_ADMIN_EMAIL=you@example.org \
  docker/scripts/init-env.sh
docker compose -f docker/compose.yaml up -d --build
docker compose -f docker/compose.yaml logs init

docker/scripts/init-env.sh crea docker/.env a partir de docker/.env.example y genera todos los secretos (contraseñas de la base de datos, claves de firma y maestra, y el par de claves para el lanzamiento de contenido); guarda la clave de firma del punto de control de auditoría en docker/secrets/audit-signing-key.pem, que Compose monta en los workers como secreto. Solo requiere sh, awk y openssl, y se niega a sobrescribir un archivo docker/.env existente. Copia ambos archivos fuera del host: sin QUIRE_MASTER_KEY, una base de datos restaurada no puede descifrar las credenciales guardadas. Para completar el archivo manualmente, ejecuta cp docker/.env.example docker/.env; el mismo archivo explica cómo generar cada secreto.

Ambos orígenes deben usar https: el servicio de contenido rechaza conexiones http sin cifrar en producción y no pueden compartir un dominio registrable. El servicio proxy termina TLS para ambos (consulta «TLS»); init-env.sh rechaza un origen http://.

La pila se inicia en un orden fijo y cada paso espera al anterior:

1. postgres queda en estado saludable. En el primer inicio, su script de inicialización (docker/postgres/init/90-passwords.sh) establece las contraseñas de los cuatro roles.
2. migrate aplica todas las migraciones e inicializa la cola de tareas en la base de datos de control y en cada base de datos de tenant dedicada, confirma que coincidan y termina (consulta docs/ops/upgrade.md). Las migraciones se ejecutan cada vez que se inicia el servicio y son idempotentes; por eso, para actualizar basta con una imagen nueva y un reinicio.
3. init (apps/web/src/first-run.ts) registra la base de datos de la aplicación en QUIRE_DATABASE_ID y, si se configuró QUIRE_SETUP_ADMIN_EMAIL, crea la primera organización y su administrador. La dirección de inicio de sesión y una contraseña generada se muestran una sola vez en docker compose logs init.
4. Se inician web, content, worker, scheduler, collab y centrifugo.
5. proxy se inicia cuando web y content están saludables.

Abre https://demo. seguido del dominio de tu aplicación (el registro de init muestra la dirección exacta de inicio de sesión) e inicia sesión. En una instalación local, primero confía en la autoridad de certificación del proxy (consulta «TLS»). Cambia la contraseña generada en /account/security.

Un proceso sin un secreto obligatorio se niega a iniciarse e indica en sus registros cuál configuración falta. Nada se inicia con una configuración incompleta.

Servicios y perfiles

--profile full inicia todos los servicios opcionales excepto backup y h5p. Inicia uno con docker compose -f docker/compose.yaml --profile scan up -d. Quire sigue funcionando sin un servicio opcional e indica qué falta: sin analizador, los archivos se guardan sin revisar y se avisa al administrador; sin Gotenberg, los archivos se pueden descargar en lugar de previsualizarse; sin transcodificador, el video se reproduce como archivo original.

Todas las imágenes de terceros y sus obligaciones de licencia se enumeran en docker/third-party-containers.yaml.

Conectar un proveedor H5P

Quire no integra ni incluye un entorno de ejecución de H5P ni un servicio auxiliar (ADR 0019). Si usas H5P, proporciona tu propia suscripción alojada u opera una instancia autoalojada de H5P por separado de Quire. Registra ese proveedor como herramienta externa LTI 1.3 y agrega su contenido a cursos como actividad de herramienta. Quire intercambia calificaciones y avances de actividades y evaluaciones mediante LTI Assignment and Grade Services (AGS). Si el proveedor también envía declaraciones xAPI, configura por separado el envío al almacén de declaraciones xAPI de Quire; el intercambio de calificaciones y avances de AGS no envía declaraciones xAPI. Al importar cursos de Moodle, se indica que las actividades H5P necesitan una conexión con una herramienta LTI. El proveedor sigue siendo responsable de su entorno H5P, la creación y reproducción del contenido, el banco de contenido y el historial de intentos.

Para ejecutar tu propia instancia autoalojada en este host, configura QUIRE_H5P_IMAGE con su imagen e inicia el perfil h5p. Compose la publica en QUIRE_H5P_PORT (8090) y guarda sus datos en el volumen h5p-data; la imagen y sus obligaciones siguen siendo tuyas.

Configuración

Todos los procesos leen docker/.env. La plantilla docker/.env.example enumera cada configuración con su valor predeterminado. Estos son los grupos:

Direcciones

Secretos

Guarda una copia de QUIRE_MASTER_KEY fuera de este host. Sin ella, una base de datos restaurada no puede descifrar las credenciales que contiene.

Base de datos

Las contraseñas de roles solo se aplican cuando se crea por primera vez el volumen de la base de datos. Para cambiar una después, usa ALTER ROLE y luego actualiza la URL correspondiente.

QUIRE_REPORT_DATABASE_URL se usa para la base de datos física configurada en DATABASE_URL. Para cualquier otra base de datos física registrada, configura su propia URL de conexión quire_report en los entornos de web y del worker, y luego incluye el nombre de la variable en el campo Variable de entorno de informes de esa base como env:NAME. La referencia debe apuntar a la misma base de datos que la conexión de la aplicación, idealmente a su réplica de lectura. Todas las funciones de informes siguen la conexión de informes propia de la base de datos del tenant: el generador y los informes guardados, las entregas programadas, las exportaciones, las analíticas, el registro de auditoría, los recursos de auditoría REST y la búsqueda de auditoría del asistente. Ninguna usa la URL de informes de otra base de datos. Si una base de datos no tiene conexión para informes, los informes comunes se ejecutan con su propia conexión de aplicación, pero las analíticas y todas las consultas de auditoría se rechazan y lo indican, porque el rol de aplicación no puede leer el registro de auditoría.

Controladores

Si esta versión no incluye un valor de controlador, la capa web se niega a iniciar e indica qué configuración falta, en vez de cambiarlo silenciosamente por el valor predeterminado.

Imágenes

Las páginas solicitan imágenes en cuatro tamaños fijos mediante /api/files/{id}/image/{size}; la ruta verifica que la persona tenga el mismo acceso que al archivo y luego redirige al servicio de imágenes. Cada organización puede solicitar QUIRE_IMAGE_SPECS_PER_HOUR pares nuevos de imagen y tamaño por hora (2000 de forma predeterminada); no cuentan los tamaños generados durante esa hora. Si tienes varios contenedores web, usa valkey o postgres para QUIRE_CACHE_DRIVER, así el límite se aplica entre todos.

Cloudflare Images guarda su propia copia de cada original que sirve. Cuando se elimina un archivo, el worker borra esa copia antes que el original.

Cola

Las tareas en segundo plano usan pg-boss en la misma base de Postgres; no hace falta ejecutar ni configurar un servicio de cola. Las tareas se agregan a la cola en la misma transacción que el cambio que las originó, así que un fallo no puede perder una ni ejecutarla dos veces. QUIRE_QUEUE_DRIVER es pgboss aquí, su valor predeterminado; vercel y cloudflare trasladan solo las entregas ligeras de notificaciones y webhooks a la cola propia de cada plataforma. Las guías de Vercel y Cloudflare las describen y explican cómo sus capas web agregan tareas.

Correo electrónico

Configura una de estas opciones:

• QUIRE_EMAIL_PROVIDER_CONFIG: un objeto JSON que identifica un proveedor HTTP y sus credenciales, por ejemplo, {"provider":"postmark","token":"..."}. Se admiten Postmark, Amazon SES, Mailgun, SendGrid y Resend.
• QUIRE_SMTP_URL: smtp://user:password@host:587. Solo para este destino; los entornos sin servidor bloquean SMTP.

QUIRE_MAIL_FROM es la dirección del remitente. Para probar Quire, inicia el perfil devmail, configura QUIRE_SMTP_URL=smtp://mailpit:1025 y revisa el correo en http://localhost:8025.

Servicios opcionales

Observabilidad

OTEL_EXPORTER_OTLP_ENDPOINT indica el colector al que todos los procesos envían trazas y métricas; con el perfil observability es http://otelcol:4318, y en docker/otel-collector.yaml agregas el exportador de tu backend. Cuando se configura, los procesos de web, worker, scheduler, content y collab exportan spans por OTLP/HTTP (solicitudes web, transacciones de bases de datos de tenants, tareas del worker y llamadas salientes) y envían métricas al mismo endpoint cada minuto (OTEL_METRICS_EXPORTER=none las desactiva). OTEL_TRACES_SAMPLER_ARG establece la proporción de trazas que se conservan. Los registros se envían a la salida estándar con el nivel LOG_LEVEL, y Compose los rota. Las trazas nunca incluyen datos personales.

Salida de red regional (residencia de datos en la UE)

QUIRE_REGION=eu indica que la pila da servicio a organizaciones de la Unión Europea. En ese caso, el worker limita las solicitudes salientes que se hacen para una organización fijada a la UE a una lista de hosts permitidos (sección 8.1 de 21-compliance.md). La lista incluye los hosts que los servicios configurados declaran para esa región (el endpoint de almacenamiento, el proveedor de correo, uno de video alojado, los destinos de almacenamiento propios de la organización, los proveedores de IA y la cuenta de correo), los hosts de servicios cubiertos por una excepción vigente y los que especifiques en QUIRE_EGRESS_ALLOW_HOSTS. Las solicitudes a cualquier otro host público se rechazan antes de enviarse; el rechazo se registra en el historial de auditoría de la organización como privacy/egress_refused y aparece en Cumplimiento, Residencia de datos.

Las organizaciones del Reino Unido y Estados Unidos no están sujetas a una lista de hosts; mantienen las comprobaciones de región del servicio. Configura la lista en el worker; la página de administración la lee en la capa web para mostrar los hosts permitidos, así que inclúyela en docker/.env, que leen todos los servicios.

La comprobación de la aplicación muestra un error claro y agrega un registro de auditoría, pero no es la garantía: el código puede tener errores. La garantía la da la red. Compose no la impone por su cuenta. Para una pila regional, coloca los servicios worker y web en una red internal: true cuya única salida sea un proxy de egreso (por ejemplo, un contenedor Squid o tinyproxy) que permita los mismos hosts que QUIRE_EGRESS_ALLOW_HOSTS, además de los hosts de los servicios configurados, y establece HTTPS_PROXY para esos servicios. La página de residencia muestra los hosts exactos que permite la aplicación, así que puedes comparar ambas listas.

Estado de salud

docker compose -f docker/compose.yaml ps muestra el estado de cada servicio.

TLS

El servicio proxy (Caddy, Apache-2.0, docker/caddy/Caddyfile) forma parte de la configuración predeterminada. Responde en los puertos 80 y 443 y enruta:

init-env.sh obtiene QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL e IMGPROXY_URL a partir de los dos orígenes, para que no haya diferencias entre ellos. Si cambias un origen manualmente, edítalos también.

Los certificados dependen de QUIRE_PROXY_TLS:

• internal (opción predeterminada): autoridad de certificación propia de Caddy, para localhost, *.localhost y lvh.me. Confía una vez en su certificado raíz y luego abre:

  docker compose -f docker/compose.yaml cp \
    proxy:/data/caddy/pki/authorities/local/root.crt ./quire-local-ca.crt

  Agrega quire-local-ca.crt al almacén de confianza del sistema o del navegador. curl lo recibe mediante --cacert.

• Una dirección de correo electrónico: certificados ACME automáticos (Let’s Encrypt y luego ZeroSSL) para nombres de host reales. El DNS de ambos orígenes y de cada host de tenant debe apuntar aquí; además, los puertos 80 y 443 deben ser accesibles desde Internet.

Los hosts de tenants reciben certificados al visitarse por primera vez y solo si web confirma que el nombre pertenece a esta instalación (/tls-allowed, mediante la red de Compose). No necesitas un certificado comodín ni un complemento del proveedor DNS, y una persona ajena que apunte un nombre a este host no puede hacer que solicite certificados. Los certificados y la autoridad local están en el volumen caddy-data; si usas internal, inclúyelo en los demás respaldos.

Web solo confía en X-Forwarded-For cuando lo envía el proxy: este tiene una dirección fija (QUIRE_PROXY_ADDRESS, 172.29.64.10 de forma predeterminada) en una subred fija (QUIRE_COMPOSE_SUBNET), y QUIRE_TRUSTED_PROXY_CIDRS identifica esa dirección. Si la subred coincide con una red del host, cambia ambas y ejecuta docker compose down antes de up.

Detrás de tu propio proxy inverso

Para usar el balanceador de carga o proxy que ya tienes en lugar de proxy, déjalo fuera (docker compose up -d --scale proxy=0) y termina TLS frente a web (8080), content (8081), collab (1234, WebSocket) y centrifugo (8000, WebSocket). Configura las direcciones públicas en QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN y QUIRE_COLLAB_URL (wss://), y el rango de direcciones de tu proxy en QUIRE_TRUSTED_PROXY_CIDRS.

Solución de problemas

• init termina con «QUIRE_DATABASE_ID is not a UUID»: configúralo con uuidgen.
• web se reinicia con «did not start on compose»: el registro enumera cada parámetro que no puede usar y qué valor debes configurar.
• Cambiar una contraseña de rol en .env después del primer inicio no tiene efecto: el script de inicialización se ejecuta una sola vez. Usa ALTER ROLE.
• Si las cargas fallan con un error de análisis y está configurado CLAMAV_URL: ClamAV descarga sus firmas durante el primer inicio, lo que puede tardar unos minutos.