Instal·lar Quire amb Docker Compose

Aquest és el producte complet en un sol host: l’LMS, les tasques en segon pla, els serveis de temps real i d’edició col·laborativa i tots els serveis opcionals darrere d’un perfil. El disseny es descriu a la secció 2 de docs/architecture/23-ops.md.

Altres opcions: Vercel i Cloudflare Workers executen només la capa web. Les actualitzacions es descriuen a upgrade.md, i les còpies de seguretat i el simulacre de restauració a backup-restore.md.

Requisits

• Docker Engine 27 o posterior, amb el connector Compose 2.30 o posterior.
• 4 nuclis de CPU i 8 GB de memòria per al stack predeterminat; 8 nuclis i 16 GB amb --profile full (ClamAV ocupa tot sol aproximadament 1,5 GB de signatures).
• Un nom DNS per a la capa web i un altre per al contingut no fiable. Han de ser hosts diferents: els paquets SCORM i l’HTML carregat s’executen des de l’origen de contingut i no poden llegir mai les galetes de l’LMS.
• Per a una prova local, lvh.me i *.localhost es resolen a 127.0.0.1, com preveu docker/.env.example. El servei proxy del stack serveix tots dos per HTTPS amb una autoritat de certificació local, així que no cal instal·lar res més (vegeu «TLS»).
• Allibereu els ports 80 i 443 de l’host (QUIRE_PROXY_HTTP_PORT i QUIRE_PROXY_HTTPS_PORT els canvien).

Primera execució

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 i genera tots els secrets (contrasenyes de la base de dades, claus de signatura i mestra, i parell de claus d’inici del contingut). També crea la clau de signatura dels checkpoints d’auditoria a docker/secrets/audit-signing-key.pem, que Compose munta als workers com a secret. Només necessita sh, awk i openssl i es nega a sobreescriure un docker/.env existent. Copieu tots dos fitxers fora de l’host: sense QUIRE_MASTER_KEY, una base de dades restaurada no pot desxifrar les credencials que conté. Si preferiu omplir el fitxer manualment, executeu cp docker/.env.example docker/.env; dins del fitxer s’explica com generar cada secret.

Tots dos orígens han de ser https: el servei de contingut rebutja l’http sense xifrar en producció i no poden compartir un mateix domini registrable. El servei proxy acaba TLS per a tots dos (vegeu «TLS»); init-env.sh rebutja els orígens que comencen per http://.

El stack s’inicia en un ordre fix i cada pas espera que acabi l’anterior:

1. postgres arriba a un estat saludable. A la primera arrencada, l’script d’inicialització (docker/postgres/init/90-passwords.sh) estableix les contrasenyes dels quatre rols.
2. migrate aplica totes les migracions i inicialitza la cua de tasques tant a la base de dades de control com a cada base de dades de tenant dedicada; comprova que totes coincideixin i, després, surt (docs/ops/upgrade.md). Les migracions s’executen cada vegada que s’inicia el stack i són idempotents, així que actualitzar-lo consisteix a fer servir una imatge nova i reiniciar.
3. init (apps/web/src/first-run.ts) registra la base de dades de l’aplicació sota QUIRE_DATABASE_ID i, si s’ha definit QUIRE_SETUP_ADMIN_EMAIL, crea la primera organització i el seu administrador. L’adreça d’inici de sessió i una contrasenya generada es mostren una sola vegada al registre de docker compose logs init.
4. S’inicien web, content, worker, scheduler, collab i centrifugo.
5. proxy s’inicia quan web i content estan saludables.

Obriu https://demo. seguit del domini de l’aplicació (el registre de init mostra l’adreça d’inici de sessió exacta) i inicieu sessió. En una instal·lació local, primer establiu com a fiable l’autoritat de certificació del proxy (vegeu «TLS»). Canvieu la contrasenya generada a /account/security.

Un procés que s’inicia sense un secret obligatori es nega a arrencar i n’indica el nom al registre. No s’inicia res amb una configuració incompleta.

Serveis i perfils

--profile full inicia tots els serveis opcionals excepte backup i h5p. Per iniciar-ne un, executeu docker compose -f docker/compose.yaml --profile scan up -d. Quire continua funcionant sense un servei opcional i indica què manca: sense scanner, les pujades es desen sense analitzar i s’avisa l’administrador; sense Gotenberg, els fitxers es poden descarregar però no previsualitzar; sense transcoder, el vídeo es reprodueix com el fitxer original.

Les imatges de tercers i les obligacions de llicència corresponents figuren a docker/third-party-containers.yaml.

Connectar un proveïdor H5P

Quire no incorpora ni distribueix un runtime o sidecar H5P (ADR 0019). Si utilitzeu H5P, contracteu una subscripció allotjada pròpia o gestioneu una instància H5P autoallotjada separada de Quire. Registreu aquest proveïdor com a eina externa LTI 1.3 i afegiu-ne el contingut als cursos com a activitats d’eina. Quire intercanvia qualificacions i progrés de l’activitat i l’avaluació mitjançant LTI Assignment and Grade Services (AGS). Si el proveïdor també envia declaracions xAPI, configureu-ho per separat amb el magatzem de declaracions xAPI de Quire; l’intercanvi de qualificacions i progrés per AGS no envia declaracions xAPI. Les importacions de Moodle indiquen que les activitats H5P necessiten una connexió a una eina LTI. El proveïdor continua sent responsable del seu runtime H5P, les eines de creació, el banc de continguts i l’historial d’intents.

Per executar una instància pròpia en aquest host, establiu QUIRE_H5P_IMAGE amb la imatge i inicieu el perfil h5p. Compose la publica al port QUIRE_H5P_PORT (8090) i en desa les dades al volum h5p-data; tant la imatge com les obligacions que comporta són responsabilitat vostra.

Configuració

Cada procés llegeix docker/.env. El fitxer de plantilla, docker/.env.example, enumera cada opció amb el seu valor predeterminat. Els grups són:

Adreces

Secrets

Guardeu una còpia de QUIRE_MASTER_KEY fora d’aquest host. Sense aquesta clau, una base de dades restaurada no pot desxifrar les credencials que conté.

Base de dades

Les contrasenyes dels rols només s’apliquen quan es crea per primera vegada el volum de la base de dades. Per canviar-ne una més endavant, executeu ALTER ROLE i, després, actualitzeu l’URL corresponent.

QUIRE_REPORT_DATABASE_URL s’utilitza per a la base de dades física configurada a DATABASE_URL. Per a qualsevol altra base de dades física registrada, establiu el seu propi URL de connexió quire_report als entorns web i worker; després, al camp Reporting environment variable de la base, indiqueu el nom de la variable amb el format env:NAME. La referència ha d’apuntar a la mateixa base de dades que la connexió de l’aplicació, idealment a la seva rèplica de lectura. Cada superfície d’informes segueix el tenant i utilitza la connexió d’informes de la seva base de dades: el creador i els informes desats, els lliuraments programats, les exportacions d’informes, l’analítica, el registre d’auditoria, els recursos d’auditoria REST i la cerca d’auditoria de l’assistent. Cap d’ells no utilitza la URL d’informes d’una altra base de dades. Si una base de dades no té connexió d’informes, els informes habituals utilitzen la connexió de l’aplicació de la mateixa base; en canvi, l’analítica i qualsevol lectura d’auditoria es rebutgen i n’indiquen el motiu, perquè el rol de l’aplicació no pot llegir el registre d’auditoria.

Drivers

Quan s’inicia la capa web, es rebutja un valor de driver que no inclogui aquesta versió i se n’indica el nom; no se substitueix silenciosament pel valor predeterminat.

Imatges

Les pàgines demanen imatges en quatre mides fixes mitjançant /api/files/{id}/image/{size}. Es comprova el mateix accés que al fitxer i, després, es redirigeix al servei d’imatges. Cada organització pot demanar fins a QUIRE_IMAGE_SPECS_PER_HOUR (2000 per defecte) parelles noves d’imatge i mida per hora; les mides ja generades durant aquella hora no compten. Si hi ha més d’un contenidor web, utilitzeu valkey o postgres per a QUIRE_CACHE_DRIVER, de manera que el límit s’apliqui a tots.

Cloudflare Images conserva una còpia de cada original que serveix. Quan se suprimeix un fitxer, el worker elimina primer aquella còpia i després l’original.

Cua

Les tasques en segon pla utilitzen pg-boss a la mateixa base de dades Postgres; per tant, no cal executar ni configurar un servei de cua. Les tasques s’encuen dins de la mateixa transacció que el canvi que les ha provocat: una fallada no en pot perdre cap ni enviar-la dues vegades. Aquí QUIRE_QUEUE_DRIVER és pgboss, el valor predeterminat; vercel i cloudflare només traslladen les notificacions lleugeres i els lliuraments de webhooks a la cua de la plataforma. Les guies de Vercel i Cloudflare n’expliquen el funcionament i com les seves capes web hi encuen tasques.

Correu electrònic

Establiu una d’aquestes opcions:

• QUIRE_EMAIL_PROVIDER_CONFIG: objecte JSON que indica un proveïdor HTTP i les seves credencials, com ara {"provider":"postmark","token":"..."}. S’admeten Postmark, Amazon SES, Mailgun, SendGrid i Resend.
• QUIRE_SMTP_URL: smtp://user:password@host:587. Només funciona en aquest entorn; els entorns serverless bloquegen SMTP.

QUIRE_MAIL_FROM és l’adreça del remitent. Per provar Quire, inicieu el perfil devmail, establiu QUIRE_SMTP_URL=smtp://mailpit:1025 i llegiu el correu a http://localhost:8025.

Serveis opcionals

Observabilitat

OTEL_EXPORTER_OTLP_ENDPOINT indica el recol·lector al qual cada procés envia traçes i mètriques. Amb el perfil observability, és http://otelcol:4318; a docker/otel-collector.yaml s’hi afegeix l’exportador per al vostre backend. Si s’estableix aquesta opció, els processos de la capa web, el worker, l’scheduler, content i collab envien spans per OTLP/HTTP (peticions web, transaccions de bases de dades tenant, tasques de workers i crides sortints) i mètriques al mateix endpoint cada minut (OTEL_METRICS_EXPORTER=none les desactiva). OTEL_TRACES_SAMPLER_ARG determina la proporció de traces conservades. Els registres s’envien a la sortida estàndard segons LOG_LEVEL i Compose els rota. Les traces no contenen mai dades personals.

Trànsit de sortida regional (residència de dades a la UE)

QUIRE_REGION=eu indica que el stack serveix organitzacions de la Unió Europea. En aquest cas, el worker limita a una llista de permesos les peticions sortints de les organitzacions assignades a la UE (21-compliance.md, secció 8.1). Aquesta llista inclou els hosts que declaren els serveis configurats per a la regió (endpoint d’emmagatzematge, proveïdor de correu, proveïdor de vídeo allotjat, destinacions d’emmagatzematge pròpies de l’organització, proveïdors d’IA i compte de correu), els hosts dels serveis amb una excepció vigent i els que indiqueu a QUIRE_EGRESS_ALLOW_HOSTS. Es rebutja qualsevol petició a un altre host públic abans d’enviar-la; el rebuig queda al registre d’auditoria de l’organització com a privacy/egress_refused i es mostra a Compliance, Data residency.

Les organitzacions del Regne Unit i dels Estats Units no estan subjectes a una llista de hosts, però es mantenen les comprovacions de regió dels serveis. Establiu la llista al worker; la pàgina d’administració la llegeix des de la capa web per mostrar la llista de permesos, així que poseu-la a docker/.env, que llegeixen tots els serveis.

La comprovació de l’aplicació dona un error clar i crea una entrada d’auditoria, però no és la garantia: el codi pot ser incorrecte. La garantia és la xarxa, i Compose no la imposa. En un stack regional, poseu worker i web en una xarxa internal: true l’única sortida de la qual sigui un proxy de trànsit de sortida (per exemple, un contenidor Squid o tinyproxy) que permeti els mateixos hosts que QUIRE_EGRESS_ALLOW_HOSTS, a més dels hosts dels serveis configurats; establiu HTTPS_PROXY per a aquests serveis. La pàgina de residència enumera exactament els hosts que permet l’aplicació, de manera que en podeu comparar les dues llistes.

Estat de salut

docker compose -f docker/compose.yaml ps mostra l’estat de salut de cada servei.

TLS

El servei proxy (Caddy, Apache-2.0, docker/caddy/Caddyfile) forma part del stack predeterminat. Escolta als ports 80 i 443 i encamina:

init-env.sh deriva QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL i IMGPROXY_URL dels dos orígens, de manera que no divergeixin. Si canvieu un origen manualment, modifiqueu-los tots alhora.

Els certificats segueixen l’opció QUIRE_PROXY_TLS:

• internal (predeterminat): l’autoritat de certificació pròpia de Caddy, per a localhost, *.localhost i lvh.me. Marqueu-ne l’arrel com a fiable una vegada i, després, navegueu-hi:

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

  Afegiu quire-local-ca.crt al magatzem de certificats fiables del sistema o del navegador. curl l’utilitza amb --cacert.

• Una adreça de correu electrònic: certificats ACME automàtics (Let’s Encrypt i, després, ZeroSSL) per a noms de host reals. El DNS dels dos orígens i de cada host tenant ha d’apuntar aquí, i els ports 80 i 443 han de ser accessibles des d’Internet.

Els certificats dels hosts tenant s’emeten quan cal, en la primera visita i només si web confirma que el nom pertany a aquesta instal·lació (/tls-allowed, consultat des de la xarxa de Compose). No cal cap certificat wildcard ni cap connector de proveïdor DNS, i un desconegut que apunti un nom a l’host no pot fer que se n’emetin certificats. Els certificats i l’autoritat local són al volum caddy-data; si utilitzeu internal, incloeu-lo a la resta de còpies de seguretat.

Web només confia en X-Forwarded-For si l’envia el proxy: el proxy té una adreça fixa (QUIRE_PROXY_ADDRESS, 172.29.64.10 per defecte) en una subnet fixa (QUIRE_COMPOSE_SUBNET), i QUIRE_TRUSTED_PROXY_CIDRS inclou aquesta adreça. Si la subnet entra en conflicte amb una xarxa de l’host, canvieu totes dues i executeu docker compose down abans de up.

Darrere del vostre propi proxy invers

Per utilitzar el balancejador de càrrega o el proxy que ja executeu, excloeu proxy (docker compose up -d --scale proxy=0) i acabeu TLS davant de web (8080), content (8081), collab (1234, websocket) i centrifugo (8000, websocket). Establiu les adreces públiques a QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN i QUIRE_COLLAB_URL (wss://), i el rang d’adreces del vostre proxy a QUIRE_TRUSTED_PROXY_CIDRS.

Resolució de problemes

• Si init surt amb «QUIRE_DATABASE_ID is not a UUID», establiu-ne un amb uuidgen.
• Si web es reinicia amb «did not start on compose», el registre enumera cada opció que no pot acceptar i què cal utilitzar en lloc seu.
• Canviar una contrasenya de rol a .env després de la primera arrencada no fa res: l’script d’inicialització només s’executa una vegada. Utilitzeu ALTER ROLE.
• Si fallen les pujades amb un error d’anàlisi quan CLAMAV_URL està establert, ClamAV està descarregant les signatures de la primera arrencada; això pot trigar uns minuts.