Installare Quire con Docker Compose

Questo è il prodotto completo su un solo host: l’LMS, il suo lavoro in background, i servizi realtime e di modifica collaborativa, e ogni servizio facoltativo dietro un profilo. Il progetto è nella sezione 2 di docs/architecture/23-ops.md.

Altri target: Vercel e Cloudflare Workers eseguono solo il livello web. Gli aggiornamenti sono in upgrade.md, e backup e prova di ripristino in backup-restore.md.

Cosa serve

• Docker Engine 27 o successivo con plugin Compose 2.30 o successivo.
• 4 core CPU e 8 GB di memoria per lo stack predefinito; 8 core e 16 GB con --profile full (il solo ClamAV occupa circa 1,5 GB di firme).
• Un nome DNS per il livello web e un secondo per i contenuti non fidati. Devono essere host diversi: pacchetti SCORM e HTML caricati girano sull’origine dei contenuti così non possono mai leggere i cookie dell’LMS.
• Per una prova locale, lvh.me e *.localhost risolvono a 127.0.0.1, come usa docker/.env.example. Il servizio proxy proprio dello stack serve entrambi via https con un’autorità di certificazione locale, quindi non si installa nient’altro (vedi “TLS”).
• Porte 80 e 443 libere sull’host (QUIRE_PROXY_HTTP_PORT e QUIRE_PROXY_HTTPS_PORT le spostano).

Prima esecuzione

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 scrive docker/.env da docker/.env.example con ogni segreto generato (password dei database, chiavi di firma e master, coppia di chiavi di avvio dei contenuti) e la chiave di firma del checkpoint di audit in docker/secrets/audit-signing-key.pem, che Compose monta nei worker come segreto. Servono solo sh, awk e openssl, e rifiuta di sovrascrivere un docker/.env esistente. Copia entrambi i file fuori dall’host: senza QUIRE_MASTER_KEY un database ripristinato non può decifrare le sue credenziali archiviate. Per compilare il file a mano, cp docker/.env.example docker/.env; il file spiega come generare ciascun segreto.

Entrambe le origini devono essere https: il servizio dei contenuti rifiuta http in chiaro in produzione, e non devono condividere un dominio registrabile. Il servizio proxy termina TLS per entrambe (vedi “TLS”); init-env.sh rifiuta un’origine http://.

Lo stack parte in ordine fisso, e ciascun passaggio attende quello precedente:

1. postgres diventa sano. Al primissimo avvio il suo script di init (docker/postgres/init/90-passwords.sh) imposta le password dei quattro ruoli.
2. migrate applica ogni migrazione e avvia la coda dei job nel database di controllo e in ogni database tenant dedicato, verifica che siano tutti d’accordo, poi esce (docs/ops/upgrade.md). Le migrazioni girano a ogni avvio e sono idempotenti, quindi un aggiornamento è una nuova immagine e un riavvio.
3. init (apps/web/src/first-run.ts) registra il database applicativo sotto QUIRE_DATABASE_ID e, quando QUIRE_SETUP_ADMIN_EMAIL è impostato, crea la prima organizzazione e il suo amministratore. L’indirizzo di accesso e una password generata sono stampati una volta, in docker compose logs init.
4. web, content, worker, scheduler, collab e centrifugo partono.
5. proxy parte una volta che web e content sono sani.

Apri https://demo. seguito dal tuo dominio applicativo (il registro init stampa l’indirizzo di accesso esatto), e accedi. Su un’installazione locale, considera prima attendibile l’autorità di certificazione del proxy (vedi “TLS”). Cambia la password generata in /account/security.

Un processo avviato senza un segreto richiesto rifiuta di avviarsi e nomina l’impostazione mancante nel suo registro. Nulla parte mezzo configurato.

Servizi e profili

--profile full avvia ogni servizio facoltativo tranne backup e h5p. Avviane uno con docker compose -f docker/compose.yaml --profile scan up -d. Senza un servizio facoltativo Quire funziona comunque e dice cosa manca: senza scanner i caricamenti sono archiviati non scansionati e l’amministratore è avvisato; senza Gotenberg i file offrono il download invece dell’anteprima; senza transcoder i video vengono riprodotti come file originale.

Ogni immagine di terze parti e i suoi obblighi di licenza sono elencati in docker/third-party-containers.yaml.

Collegare un provider H5P

Quire non integra né fornisce un runtime o sidecar H5P (ADR 0019). Se usi H5P, procurati un abbonamento ospitato oppure gestisci separatamente da Quire una tua istanza H5P autonoma. Registra quel provider come strumento esterno LTI 1.3 e aggiungi i suoi contenuti ai corsi come attività strumento. Quire scambia voti e avanzamento di attività/valutazione tramite LTI Assignment and Grade Services (AGS). Se il provider invia anche istruzioni xAPI, configurale separatamente per l’archivio istruzioni xAPI di Quire; lo scambio voti/avanzamento AGS non invia istruzioni xAPI. Le importazioni Moodle segnalano le attività H5P come bisognose di una connessione a uno strumento LTI. Il provider resta responsabile del suo runtime H5P, della creazione, della banca dei contenuti e della cronologia dei tentativi.

Per eseguire una tua istanza autonoma su questo host, imposta QUIRE_H5P_IMAGE sulla sua immagine e avvia il profilo h5p. Compose la pubblica su QUIRE_H5P_PORT (8090) e ne conserva i dati nel volume h5p-data; l’immagine, e gli obblighi che comporta, restano tuoi.

Impostazioni

Ogni processo legge docker/.env. Il modello, docker/.env.example, elenca ciascuna impostazione col suo default. I gruppi:

Indirizzi

Segreti

Conserva una copia di QUIRE_MASTER_KEY altrove rispetto a questo host. Un database ripristinato senza di essa non può decifrare le credenziali che contiene.

Database

Le password dei ruoli sono applicate solo quando il volume del database viene creato per la prima volta. Per cambiarne una in seguito, usa ALTER ROLE e poi aggiorna l’URL corrispondente.

QUIRE_REPORT_DATABASE_URL è usato per il database fisico configurato da DATABASE_URL. Per ogni altro database fisico registrato, imposta il suo URL di connessione quire_report negli ambienti web e worker, poi inserisci il nome della variabile nel campo Variabile d’ambiente di reporting di quel database come env:NAME. Il riferimento deve puntare allo stesso database della sua connessione app, idealmente la sua replica di lettura. Ogni superficie di report segue il tenant alla connessione report del proprio database: il generatore di report e i report salvati, le consegne programmate, le esportazioni di report, le analisi, il registro di audit, le risorse audit REST e la ricerca audit dell’assistente. Nessuna di esse prende mai in prestito l’URL report di un altro database. Quando un database non ha una connessione report, i report ordinari girano sulla connessione applicativa del database stesso, mentre le analisi e ogni lettura audit rifiutano e lo dicono, perché il ruolo applicativo non può leggere la traccia di audit.

Driver

Un valore driver non incluso in questa release viene rifiutato all’avvio del livello web, col nome dell’impostazione, anziché sostituito in silenzio dal default.

Immagini

Le pagine chiedono immagini in quattro dimensioni fisse tramite /api/files/{id}/image/{size}, che verifica lo stesso accesso del file stesso e poi reindirizza al servizio immagini. Ciascuna organizzazione può chiedere QUIRE_IMAGE_SPECS_PER_HOUR (predefinito 2000) nuove coppie immagine e dimensione all’ora; le dimensioni già prodotte in quell’ora non contano. Usa valkey oppure postgres per QUIRE_CACHE_DRIVER con più di un contenitore web, così il limite vale tra essi.

Cloudflare Images conserva una propria copia di ciascun originale servito. Quando un file viene eliminato, il worker elimina quella copia prima dell’originale.

Coda

I job in background usano pg-boss nello stesso database Postgres, quindi non c’è un servizio di coda da eseguire e nulla da configurare. I job sono accodati nella stessa transazione della modifica che li ha causati, così un crash non può perderne uno né inviarne uno due volte. QUIRE_QUEUE_DRIVER qui è pgboss, il suo default; vercel e cloudflare spostano solo le consegne leggere di notifiche e webhook alla coda propria della piattaforma, e le guide Vercel e Cloudflare le descrivono e spiegano come i loro livelli web accodano.

Email

Impostane una tra:

• QUIRE_EMAIL_PROVIDER_CONFIG: un oggetto JSON che nomina un provider HTTP e le sue credenziali, ad esempio {"provider":"postmark","token":"..."}. Postmark, Amazon SES, Mailgun, SendGrid e Resend sono supportati.
• QUIRE_SMTP_URL: smtp://user:password@host:587. Solo questo target; i target serverless bloccano SMTP.

QUIRE_MAIL_FROM è il mittente. Per provare Quire, avvia il profilo devmail, imposta QUIRE_SMTP_URL=smtp://mailpit:1025, e leggi la posta in http://localhost:8025.

Servizi facoltativi

Osservabilità

OTEL_EXPORTER_OTLP_ENDPOINT nomina il collector a cui ogni processo invia tracce e metriche; con il profilo observability è http://otelcol:4318, e docker/otel-collector.yaml è dove aggiungi l’esporter per il tuo backend. I processi web, worker, scheduler, content e collab esportano span su OTLP/HTTP (richieste web, transazioni database tenant, job worker e chiamate in uscita) quando è impostato, e metriche allo stesso endpoint ogni minuto (OTEL_METRICS_EXPORTER=none le disattiva). OTEL_TRACES_SAMPLER_ARG imposta la quota di tracce conservate. I log vanno sullo standard output a LOG_LEVEL, e Compose li ruota. Le tracce non contengono mai dati personali.

Egress regionale (residenza dati UE)

QUIRE_REGION=eu indica che lo stack serve organizzazioni dell’Unione europea. Il worker trattiene allora ogni richiesta in uscita effettuata per un’organizzazione vincolata alla UE a un allowlist (sezione 8.1 di 21-compliance.md). L’allowlist è gli host dichiarati per l’area geografica dai servizi configurati (l’endpoint storage, il provider email, un provider video ospitato, i target storage propri dell’organizzazione, provider IA e account email), gli host di ogni servizio sotto deroga attiva, e gli host elencati da te in QUIRE_EGRESS_ALLOW_HOSTS. Una richiesta a qualsiasi altro host pubblico viene rifiutata prima dell’invio, il rifiuto è scritto nella traccia di audit dell’organizzazione come privacy/egress_refused, ed è elencato in Conformità, Residenza dati.

Le organizzazioni UK e US non sono vincolate a un elenco host; conservano i controlli di area geografica dei servizi. Imposta l’elenco sul worker; la pagina admin lo legge sul livello web per mostrare l’allowlist, quindi mettilo in docker/.env, che ogni servizio legge.

Il controllo applicativo dà un errore chiaro e una voce di audit, e non è la garanzia: il codice può sbagliare. La garanzia è la rete. Compose non la applica per te. Per uno stack regionale, metti i servizi worker e web su una rete internal: true la cui unica via d’uscita sia un proxy di egress (ad esempio un contenitore Squid o tinyproxy) che consente gli stessi host di QUIRE_EGRESS_ALLOW_HOSTS più gli host dei tuoi servizi configurati, e imposta HTTPS_PROXY per quei servizi. La pagina di residenza elenca gli host esatti consentiti dall’applicazione, così le due liste si possono confrontare.

Stato

docker compose -f docker/compose.yaml ps mostra lo stato di ciascun servizio.

TLS

Il servizio proxy (Caddy, Apache-2.0, docker/caddy/Caddyfile) fa parte dello stack predefinito. Risponde sulle porte 80 e 443 e instrada:

init-env.sh deriva QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL e IMGPROXY_URL dalle due origini, così non possono divergere. Modificali insieme se cambi un’origine a mano.

I certificati seguono QUIRE_PROXY_TLS:

• internal (il default): l’autorità di certificazione propria di Caddy, per localhost, *.localhost e lvh.me. Considera attendibile la sua radice una volta, poi naviga:

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

  Aggiungi quire-local-ca.crt al trust store di sistema o del browser. curl lo accetta con --cacert.

• Un indirizzo e-mail: certificati ACME automatici (Let’s Encrypt, poi ZeroSSL) per hostname reali. Il DNS di entrambe le origini e di ogni host tenant deve puntare qui, e le porte 80 e 443 devono essere raggiungibili da internet.

Gli host tenant sono emessi su richiesta, alla prima visita, e solo quando web conferma che il nome appartiene a questa installazione (/tls-allowed, chiesto sulla rete Compose). Non servono certificati wildcard né plugin DNS, e un estraneo che punta un nome all’host non può fargli richiedere certificati. Certificati e autorità locale vivono nel volume caddy-data; includilo nel backup col resto se usi internal.

Web considera X-Forwarded-For solo dal proxy: il proxy ha un indirizzo fisso (QUIRE_PROXY_ADDRESS, default 172.29.64.10) su una sottorete fissa (QUIRE_COMPOSE_SUBNET), e QUIRE_TRUSTED_PROXY_CIDRS nomina quell’indirizzo. Se la sottorete collide con una rete sull’host, cambia entrambi ed esegui docker compose down prima di up.

Dietro il proprio reverse proxy

Per usare un bilanciatore o proxy già in uso, lascia fuori proxy (docker compose up -d --scale proxy=0) e termina TLS davanti a web (8080), content (8081), collab (1234, websocket) e centrifugo (8000, websocket). Imposta gli indirizzi pubblici in QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN e QUIRE_COLLAB_URL (wss://), e l’intervallo di indirizzi del tuo proxy in QUIRE_TRUSTED_PROXY_CIDRS.

Risoluzione dei problemi

• init esce con “QUIRE_DATABASE_ID is not a UUID”: impostalo con uuidgen.
• web si riavvia con “did not start on compose”: il registro elenca ciascuna impostazione che non può onorare e cosa usare invece.
• Cambiare una password di ruolo in .env dopo il primo avvio non fa nulla: lo script di init gira una volta sola. Usa ALTER ROLE.
• I caricamenti falliscono con errore di scansione mentre CLAMAV_URL è impostato: ClamAV scarica le sue firme al primo avvio, il che richiede qualche minuto.