Instalar Quire con Docker Compose

Este es el producto completo en un solo host: el LMS, sus trabajos en segundo plano, los servicios de edición colaborativa y en 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 las copias de seguridad 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 pila predeterminada; 8 núcleos y 16 GB con --profile full (solo ClamAV ocupa 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 en el origen de contenido, para que nunca puedan 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, por lo que no hay que instalar nada más (consulta «TLS»).
• Los puertos 80 y 443 deben estar libres 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 genera docker/.env a partir de docker/.env.example, crea todos los secretos (contraseñas de la base de datos, claves de firma y maestra, el par de claves para lanzar contenido) y 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 docker/.env existente. Copia ambos archivos fuera del host: sin QUIRE_MASTER_KEY, una base de datos restaurada no puede descifrar las credenciales almacenadas. Para rellenar el archivo manualmente, ejecuta cp docker/.env.example docker/.env; el archivo explica cómo generar cada secreto.

Ambos orígenes deben usar https: el servicio de contenido rechaza http sin cifrar en producción y no pueden compartir un mismo 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 a que termine el 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 trabajos en la base de datos de control y en cada base de datos de tenant dedicada, comprueba que todas coincidan y luego termina (consulta docs/ops/upgrade.md). Las migraciones se ejecutan en cada inicio y son idempotentes, así que para actualizar basta con una nueva imagen 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, cuando se establece 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 la 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.

Si un proceso no dispone de un secreto obligatorio, se niega a iniciarse e indica en el registro cuál falta. Nada se inicia con una configuración incompleta.

Servicios y perfiles

--profile full inicia todos los servicios opcionales, salvo backup y h5p. Para iniciar uno, ejecuta docker compose -f docker/compose.yaml --profile scan up -d. Quire sigue funcionando sin un servicio opcional y explica qué falta: sin analizador, los archivos se guardan sin analizar y se avisa al administrador; sin Gotenberg, los archivos se pueden descargar en lugar de previsualizarse; sin transcodificador, el vídeo 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 componente 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 añade su contenido a los cursos como actividades de herramienta. Quire intercambia calificaciones y el progreso de la actividad y la evaluación mediante LTI Assignment and Grade Services (AGS). Si el proveedor también envía declaraciones xAPI, configura por separado su envío al almacén de declaraciones xAPI de Quire; el intercambio de calificaciones y progreso de AGS no envía declaraciones xAPI. Las importaciones de Moodle indican que las actividades H5P necesitan una conexión con una herramienta LTI. El proveedor sigue siendo responsable de su entorno de ejecución H5P, la creación de contenido, el banco de contenido y el historial de intentos.

Para ejecutar tu propia instancia autoalojada en este host, establece QUIRE_H5P_IMAGE en 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 las obligaciones asociadas siguen siendo tuyas.

Configuración

Todos los procesos leen docker/.env. La plantilla docker/.env.example enumera cada parámetro y su valor predeterminado. Estos son los grupos:

Direcciones

Secretos

Guarda una copia de QUIRE_MASTER_KEY fuera de este host. Si restauras una base de datos sin ella, no podrás descifrar las credenciales almacenadas.

Base de datos

Las contraseñas de los roles solo se aplican cuando se crea el volumen de la base de datos por primera vez. Para cambiar una más adelante, usa ALTER ROLE y 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, en el campo Variable de entorno de informes de esa base de datos, introduce el nombre de la variable con el formato 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 superficies 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 de informes, las analíticas, el registro de auditoría, los recursos de auditoría REST y la búsqueda de auditoría del asistente. Ninguna toma prestada la URL de informes de otra base de datos. Si una base de datos no tiene conexión para informes, los informes normales 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 la aplicación no puede leer el registro de auditoría.

Controladores

Si esta versión no incluye el valor de un controlador, la capa web se niega a iniciarse e indica el parámetro, en lugar de sustituirlo 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 comprueba los mismos permisos de acceso que el archivo y después redirige al servicio de imágenes. Cada organización puede solicitar QUIRE_IMAGE_SPECS_PER_HOUR (2000 de forma predeterminada) pares nuevos de imagen y tamaño por hora; los tamaños que ya se hayan generado esa hora no cuentan. Si tienes más de un contenedor web, usa valkey o postgres para QUIRE_CACHE_DRIVER para que el límite se aplique en todos ellos.

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

Cola

Los trabajos en segundo plano usan pg-boss en la misma base de datos de Postgres, por lo que no hace falta ejecutar ni configurar un servicio de cola. Los trabajos se ponen en cola en la misma transacción que el cambio que los generó, así que un fallo no puede perder un trabajo ni enviarlo 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 la plataforma. Las guías de Vercel y Cloudflare describen esas colas y cómo las capas web añaden elementos.

Correo electrónico

Configura una de estas opciones:

• QUIRE_EMAIL_PROVIDER_CONFIG: un objeto JSON que indica un proveedor HTTP y sus credenciales, como {"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 destinos sin servidor bloquean SMTP.

QUIRE_MAIL_FROM es el remitente. Para probar Quire, inicia el perfil devmail, establece QUIRE_SMTP_URL=smtp://mailpit:1025 y consulta 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 docker/otel-collector.yaml es donde se añade el exportador de tu backend. Cuando está configurado, la capa web, el worker, el scheduler, content y collab exportan spans mediante OTLP/HTTP (solicitudes web, transacciones con bases de datos de tenants, trabajos del worker y llamadas salientes), así como 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 conserva. Los registros se envían a la salida estándar con el nivel LOG_LEVEL, y Compose los rota. Las trazas nunca contienen datos personales.

Salida regional (residencia de datos en la UE)

QUIRE_REGION=eu indica que la pila presta servicio a organizaciones de la Unión Europea. En ese caso, el worker limita las solicitudes salientes que se hacen en nombre de una organización fijada a la UE a una lista de permitidos (sección 8.1 de 21-compliance.md). La lista incluye los hosts que los servicios configurados declaran para la región (el endpoint de almacenamiento, el proveedor de correo, el proveedor de vídeo alojado, los destinos de almacenamiento propios de la organización, los proveedores de IA y la cuenta de correo electrónico), los hosts de cualquier servicio cubierto por una excepción vigente y los que incluyas 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 de Estados Unidos no están sujetas a una lista de hosts; solo se les aplican 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 la lista de permitidos, así que inclúyela en docker/.env, que leen todos los servicios.

La comprobación de la aplicación da un error claro y genera una entrada de auditoría, pero no es la garantía: el código puede contener errores. La garantía la proporciona la red. Compose no la impone por sí mismo. Para una pila regional, coloca los servicios worker y web en una red internal: true cuya única ruta de salida pase por un proxy de salida (por ejemplo, un contenedor Squid o tinyproxy) que permita los mismos hosts que QUIRE_EGRESS_ALLOW_HOSTS, además de los hosts de tus servicios configurados, y establece HTTPS_PROXY para esos servicios. La página de residencia enumera los hosts exactos que permite la aplicación, de modo 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 pila predeterminada. Responde en los puertos 80 y 443 y enruta:

init-env.sh deriva QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL e IMGPROXY_URL de los dos orígenes, para que no haya discrepancias entre ellos. Si cambias un origen manualmente, modifica también esos valores.

Los certificados dependen de QUIRE_PROXY_TLS:

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

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

  Añade quire-local-ca.crt al almacén de confianza del sistema o del navegador. En curl, pásalo con --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í, y los puertos 80 y 443 deben ser accesibles desde Internet.

Los hosts de tenants reciben certificados cuando se visitan por primera vez, y solo si web confirma que el nombre pertenece a esta instalación (/tls-allowed, mediante la red de Compose). No hace falta un certificado comodín ni un complemento del proveedor DNS; alguien ajeno que dirija un nombre a este host no puede provocar una solicitud de certificado. Los certificados y la autoridad local se guardan en el volumen caddy-data; si usas internal, inclúyelo en las demás copias de seguridad.

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 contiene 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 o proxy que ya tengas en lugar de este, deja fuera proxy (docker compose up -d --scale proxy=0) y termina TLS delante de web (8080), content (8081), collab (1234, WebSocket) y centrifugo (8000, WebSocket). Establece 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»: establece el valor 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 emplear.
• Cambiar una contraseña de rol en .env después del primer inicio no tiene efecto: el script de inicialización solo se ejecuta una vez. Usa ALTER ROLE.
• Las cargas fallan con un error de análisis mientras está configurado CLAMAV_URL: ClamAV descarga sus firmas en el primer inicio, lo que tarda unos minutos.