Quire ynstallearje mei Docker Compose

Dit is it folsleine produkt op ien host: de LMS, it eftergrûnwurk, de tsjinsten foar realtime en tegearre bewurkjen en alle opsjonele tsjinsten ûnder in profile. De ûntwerpbesluten steane yn seksje 2 fan docs/architecture/23-ops.md.

Oare doelen: Vercel en Cloudflare Workers rinne allinnich de web tier. Upgrades steane yn upgrade.md, reservekopyen en de restore drill yn backup-restore.md.

Watsto nedich hast

• Docker Engine 27 of nijer mei Compose-plugin 2.30 of nijer.
• 4 CPU-kearnen en 8 GB ûnthâld foar de standertstack; 8 kearnen en 16 GB mei --profile full (ClamAV allinnich brûkt sa’n 1.5 GB oan hantekeningen).
• In DNS-namme foar de web tier en in twadde foar net-fertroude ynhâld. Dat moatte ferskillende hosts wêze: SCORM-pakketten en uploade HTML draaie op de content-origin, sadat se de cookies fan de LMS nea lêze kinne.
• Foar in lokale test ferwize lvh.me en *.localhost nei 127.0.0.1, lykas docker/.env.example brûkt. De eigen proxy-tsjinst fan de stack biedt beide oer https mei in lokale certificate authority oan; der hoecht dus neat oars ynstallearre te wurden (sjoch “TLS”).
• De porten 80 en 443 moatte frij wêze op de host (QUIRE_PROXY_HTTP_PORT en QUIRE_PROXY_HTTPS_PORT kinne dy feroarje).

Earste start

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 makket docker/.env út docker/.env.example, mei alle geheimen oanmakke (databasewachtwurden, signing- en masterkaaien, it keypair foar content launch) en de audit checkpoint signing key yn docker/secrets/audit-signing-key.pem, dy’t Compose as secret yn de workers mount. Allinnich sh, awk en openssl binne nedich; it skript wegeret in besteande docker/.env te oerskriuwen. Kopiearje beide bestannen fan dizze host ôf: sûnder QUIRE_MASTER_KEY kin in weromsette database de bewarre bewiisgegevens net ûntsiferje. Om it bestân mei de hân yn te foljen, brûk cp docker/.env.example docker/.env; yn it bestân stiet hoe’tst elk geheim meitsje kinst.

Beide origins moatte https wêze: de content service wegeret plain http yn produksje, en de registrable domain fan beide mei net itselde wêze. De proxy-tsjinst makket TLS foar beide ôf (sjoch “TLS”); init-env.sh wegeret in http://-origin.

De stack begjint yn in fêste folchoarder; elke stap wachtet op de foargeande:

1. postgres wurdt sûn. By de earste start stelt it init-skript (docker/postgres/init/90-passwords.sh) de fjouwer rolwachtwurden yn.
2. migrate past alle migrations ta en bootstrapt de job queue yn de control-database en elke tawijde tenant-database, kontrolearret dat se oerienkomme en einiget dan (docs/ops/upgrade.md). Migrations rinne by elke start en binne idempotint, dus in upgrade is in nije image en in trochstart.
3. init (apps/web/src/first-run.ts) registrearret de application database ûnder QUIRE_DATABASE_ID en makket, as QUIRE_SETUP_ADMIN_EMAIL ynsteld is, de earste organisaasje en behearder oan. It oanmeldadres en in oanmakke wachtwurd wurde ien kear printe yn docker compose logs init.
4. web, content, worker, scheduler, collab en centrifugo begjinne.
5. proxy begjint as web en content sûn binne.

Iepenje https://demo. folge troch dyn applikaasjedomein (it init-logboek print it eksakte oanmeldadres) en meld dy oan. By in lokale ynstallaasje moatst earst de certificate authority fan de proxy fertrouwe (sjoch “TLS”). Feroarje it oanmakke wachtwurd op /account/security.

In proses sûnder fereaske geheim wegeret te starten en neamt de ûntbrekkende ynstelling yn it logboek. Der start neat heal ynsteld.

Tsjinsten en profiles

--profile full start alle opsjonele tsjinsten útsein backup en h5p. Start ien mei docker compose -f docker/compose.yaml --profile scan up -d. Sûnder in opsjonele tsjinst wurket Quire noch en jout oan wat ûntbrekt: sûnder scanner wurde uploads net-scanne opslein en wurdt de behearder warskôge; sûnder Gotenberg kinne bestannen wol downloade mar net foarbesjoen wurde; sûnder transcoder spilet fideo ôf as it orizjinele bestân.

Elke ôfbylding fan in tredde partij en de lisinsjeferplichtingen steane yn docker/third-party-containers.yaml.

In H5P-provider ferbine

Quire befettet of ferstjoert gjin H5P-runtime of sidecar (ADR 0019). As H5P brûkt wurdt, soargje foar in eigen hosted abonnemint of in selsbehearde H5P-ynstallaasje apart fan Quire. Registrearje de provider as LTI 1.3 external tool en foegje de ynhâld ta oan kursussen as toolaktiviteiten. Quire wikselet sifers en aktiviteit-/beoardielingsfuortgong út fia LTI Assignment and Grade Services (AGS). As de provider ek xAPI-statements stjoert, konfigurearje dat apart foar de xAPI-statement store fan Quire; it útwikseljen fan sifer/foartgong fia AGS stjoert gjin xAPI-statements. Moodle-ymporten melde dat H5P-aktiviteiten in LTI-toolferbining nedich hawwe. De provider bliuwt ferantwurdlik foar de H5P-runtime, it meitsjen fan ynhâld, de ynhâldsbank en skiednis fan besykjen.

Om op dizze host in eigen selsbehearde ynstallaasje te draaien, set QUIRE_H5P_IMAGE op de image en start it h5p-profile. Compose publisearret it op QUIRE_H5P_PORT (8090) en bewarret de gegevens yn it h5p-data-volume; de image en byhearrende ferplichtingen bliuwe dyn eigen.

Ynstellingen

Elke proses lêst docker/.env. It sjabloan docker/.env.example list elke ynstelling mei de standertwearde. De groepen:

Adressen

Geheimen

Hâld in kopy fan QUIRE_MASTER_KEY earne oars as op dizze host. In database dy’t sûnder dy kaai weromset is, kin de bewarre bewiisgegevens net ûntsiferje.

Database

Rolwachtwurden wurde allinnich tapast as it databasevolume foar it earst oanmakke wurdt. Om ien letter te feroarjen, brûk ALTER ROLE en fernij dêrnei de byhearrende URL.

QUIRE_REPORT_DATABASE_URL wurdt brûkt foar de fysike database dy’t DATABASE_URL ynstelt. Stel foar oare registrearre fysike databases de eigen quire_report-ferbinings-URL yn de web- en workeromjouwing yn; set dêrnei de fariabelenamme yn it fjild Reporting environment variable fan dy database as env:NAME. De ferwizing moat nei deselde database as de appferbining wize, leafst de lêsreplika. Elk rapportflak folget de tenant nei de rapportferbining fan syn eigen database: rapportbouwer en bewarre rapporten, plande leveringen, rapporteksporten, analytics, auditlogboek, REST-auditboarnen en sykjen yn de assistant-audit. Gjin fan dy brûkt ea de rapport-URL fan in oare database. As in database gjin rapportferbining hat, rinne gewoane rapporten op de eigen applikaasjeferbining fan dy database, wylst analytics en elke auditlêzing wegerje en dat meidiele, om’t de applikaasjerol it auditspoar net lêze kin.

Drivers

In driverwearde dy’t dizze release net befettet, wurdt ôfwiisd as de web tier begjint; de ynstelling wurdt neamd ynstee fan stilwei ferfongen te wurden troch de standertwearde.

Ofbyldings

Siden freegje ôfbyldings yn fjouwer fêste maten fia /api/files/{id}/image/{size}; dat kontrolearret deselde tagong as it bestân sels en ferwiist dêrnei troch nei de ôfbyldingstsjinst. Elke organisaasje kin yn in oere QUIRE_IMAGE_SPECS_PER_HOUR (standert 2000) nije kombinaasjes fan ôfbylding en grutte oanfreegje; maten dy’t dat oere al makke binne telle net mei. Brûk valkey of postgres foar QUIRE_CACHE_DRIVER as der mear as ien webcontainer is, sadat de limyt foar alle containers jildt.

Cloudflare Images hâldt in eigen kopy fan elk orizjineel dat it tsjinnet. As in bestân fuorthelle wurdt, wisket de worker dy kopy foardat it orizjineel fuortgiet.

Wachtrige

Eftergrûntaken brûke pg-boss yn deselde Postgres-database, dus der hoecht gjin wachtrigetsjinst draaid of ynsteld te wurden. Taken wurde yn deselde transaksje op de wachtrige set as de feroaring dy’t se feroarsake, sadat in crash gjin taak kwytreitsje of dûbel ferstjoere kin. QUIRE_QUEUE_DRIVER is hjir standert pgboss; vercel en cloudflare ferpleatse allinnich lichte meidielingen en webhookleveringen nei de eigen wachtrige fan it platfoarm. De Vercel- en Cloudflare-hantliedingen beskriuwe dy en hoe’t harren web tiers taken op de wachtrige sette.

E-mail

Stel ien fan dizze yn:

• QUIRE_EMAIL_PROVIDER_CONFIG: in JSON-objekt mei de namme fan in HTTP-provider en syn bewiis, lykas {"provider":"postmark","token":"..."}. Postmark, Amazon SES, Mailgun, SendGrid en Resend wurde stipe.
• QUIRE_SMTP_URL: smtp://user:password@host:587. Allinnich foar dizze target; de serverless-targets blokkearje SMTP.

QUIRE_MAIL_FROM is de ôfstjoerder. Om Quire út te probearjen, start it devmail-profile, set QUIRE_SMTP_URL=smtp://mailpit:1025 yn en lês de e-mail op http://localhost:8025.

Opsjonele tsjinsten

Observability

OTEL_EXPORTER_OTLP_ENDPOINT neamt de collector dêr’t elk proses traces en metrics hinne stjoert; mei it observability-profile is dat http://otelcol:4318, en yn docker/otel-collector.yaml foegest de exporter foar dyn backend ta. As dit ynsteld is, eksportearje de web tier, worker, scheduler, content- en collabprosessen spans fia OTLP/HTTP (webfersiken, tenant-databasetransaksjes, workertaken en útgeande oproppen) en elke minút metrics nei itselde einpunt (OTEL_METRICS_EXPORTER=none skeakelet dy út). OTEL_TRACES_SAMPLER_ARG set it oanpart fan traces dat bewarre wurdt. Logs geane nei standard output op LOG_LEVEL en Compose draait se troch. Traces befetsje gjin persoansgegevens.

Regionale egress (dataferbliuw yn de EU)

QUIRE_REGION=eu jout oan dat de stack organisaasjes yn de Europeeske Uny betsjinnet. De worker beheint dan elk útgeand fersyk foar in organisaasje dy’t oan de EU ferbûn is ta in allowlist (21-compliance.md seksje 8.1). Dêr steane hosts op dy’t ynstelde tsjinsten foar de regio oanjouwe (opslach-einpunt, e-mailprovider, hosted fideoprovider, eigen opslachdoelen fan de organisaasje, AI-providers en e-mailakkount), hosts fan tsjinsten ûnder in aktive ôfwiking en hosts dy’tst yn QUIRE_EGRESS_ALLOW_HOSTS neamst. In fersyk nei in oare iepenbiere host wurdt wegere foardat it ferstjoerd wurdt; de wegere poging komt as privacy/egress_refused yn it auditspoar fan de organisaasje en wurdt neamd ûnder Neilibjen, Data residency.

Organisaasjes yn it Feriene Keninkryk en de FS binne net bûn oan in hostlist; de regio- kontrôles fan de tsjinst bliuwe jilde. Stel de list yn by de worker; de behearderside lêst him yn de web tier om de allowlist sjen te litten, dus set him yn docker/.env dat elke tsjinst lêst.

De kontrôle yn de applikaasje jout in dúdlike flater en audit-yngong, mar is net de garânsje: koade kin ferkeard wêze. It netwurk is de garânsje. Compose hanthavenet it net foar dy. Foar in regionale stack, set de tsjinsten worker en web op in netwurk internal: true dat allinnich fia in egress-proxy nei bûten kin (bygelyks Squid of in tinyproxy-container). Lit dy deselde hosts tastean as QUIRE_EGRESS_ALLOW_HOSTS plus de hosts fan dyn ynstelde tsjinsten en set HTTPS_PROXY foar dy tsjinsten yn. De side oer dataferbliuw list de eksakte hosts dy’t de applikaasje tastiet, sadatst beide listen ferlykje kinst.

Sûnens

docker compose -f docker/compose.yaml ps lit de sûnens fan elke tsjinst sjen.

TLS

De proxy-tsjinst (Caddy, Apache-2.0, docker/caddy/Caddyfile) heart by de standertstack. Hy antwurdet op porten 80 en 443 en stjoert troch:

init-env.sh liedt QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL en IMGPROXY_URL ôf fan de twa origins, sadat se net útinoar rinne kinne. Bewurkje se mei-inoar as in origin mei de hân feroare wurdt.

Sertifikaten folgje QUIRE_PROXY_TLS:

• internal (standert): de eigen certificate authority fan Caddy, foar localhost, *.localhost en lvh.me. Fertrou ien kear de root en blêdzje dan:

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

  Foegje quire-local-ca.crt ta oan it fertrouwe-sertifikatenopslach fan it systeem of de browser. curl brûkt it mei --cacert.

• In e-mailadres: automatyske ACME-sertifikaten (Let’s Encrypt, dêrnei ZeroSSL) foar echte hostnammen. DNS fan beide origins en elke tenanthost moat hjirhinne wize; porten 80 en 443 moatte fan it ynternet ôf berikber wêze.

Tenanthosts krije op oanfraach in sertifikaat by it earste besyk en allinnich as web befêstiget dat de namme by dizze ynstallaasje heart (/tls-allowed, oanroppen oer it Compose-netwurk). In wildcard-sertifikaat of DNS-providerplugin is net nedich; in frjemde namme dy’t nei de host wize lit, kin gjin sertifikaatoanfraach útlokje. Sertifikaten en de lokale authority steane yn it caddy-data-volume; meitsje dêr tegearre mei de rest in reservekopy fan as internal brûkt wurdt.

Web fertrout allinnich de X-Forwarded-For fan de proxy: dy hat in fêst adres (QUIRE_PROXY_ADDRESS, standert 172.29.64.10) op in fêst subnet (QUIRE_COMPOSE_SUBNET), en QUIRE_TRUSTED_PROXY_CIDRS neamt dat adres. As it subnet botst mei in netwurk op de host, feroarje beide en fier docker compose down út foar up.

Efter dyn eigen reverse proxy

Om ynstee in load balancer of proxy te brûken dy’tst al draait, lit proxy fuort (docker compose up -d --scale proxy=0) en beëinigje TLS foar web (8080), content (8081), collab (1234, websocket) en centrifugo (8000, websocket). Stel de iepenbiere adressen yn QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN en QUIRE_COLLAB_URL (wss://) yn, en it adresberik fan de proxy yn QUIRE_TRUSTED_PROXY_CIDRS.

Problemen oplosse

• init einiget mei “QUIRE_DATABASE_ID is not a UUID”: set it mei uuidgen yn.
• web start hieltyd opnij mei “did not start on compose”: it logboek list elke ynstelling dy’t net útfierd wurde kin en watst ynstee brûke moatst.
• In rolwachtwurd feroarje yn .env nei de earste start docht neat: it init-skript rint mar ien kear. Brûk ALTER ROLE.
• Uploads mislearje mei in scanflater wylst CLAMAV_URL ynsteld is: ClamAV downloadt de hantekeningen by de earste start en dat duorret in pear minuten.