Installazzjoni ta' Quire b'Docker Compose

Dan huwa l-prodott sħiħ fuq host wieħed: l-LMS, ix-xogħol fl-isfond tiegħu, is- servizzi realtime u tal-editjar kollaborattiv, u kull servizz fakultattiv wara profil. Id-disinn jinsab f’docs/architecture/23-ops.md sezzjoni 2.

Miri oħra: Vercel u Cloudflare Workers imexxu l-livell web biss. L-aġġornamenti jinsabu f’upgrade.md, u l-backups u d-drill tar-restore f’backup-restore.md.

X’għandek bżonn

• Docker Engine 27 jew aktar ġdid bil-plugin Compose 2.30 jew aktar ġdid.
• 4 cores tas-CPU u 8 GB memorja għall-istack default; 8 cores u 16 GB b’--profile full (ClamAV waħdu jżomm madwar 1.5 GB ta’ signatures).
• Isem DNS għal-livell web u ieħor għall-kontenut mhux fdat. Iridu jkunu hosts differenti: pakketti SCORM u HTML imtella’ jaħdmu fuq l-oriġini tal-kontenut biex qatt ma jistgħu jaqraw il-cookies tal-LMS.
• Għal test lokali, lvh.me u *.localhost isolvu għal 127.0.0.1, li huwa dak li juża docker/.env.example. Is-servizz proxy tal-istack iservi lit-tnejn fuq https b’awtorità taċ-ċertifikati lokali, biex xejn ieħor ma huwa installat (ara “TLS”).
• Ports 80 u 443 ħielsa fuq il-host (QUIRE_PROXY_HTTP_PORT u QUIRE_PROXY_HTTPS_PORT iċaqalquhom).

L-ewwel tħaddim

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 jikteb docker/.env minn docker/.env.example b’kull sigriet iġġenerat (passwords tad-database, iċ-ċwievet tal-iffirmar u master, il-par taċ-ċwievet tat-tnedija tal-kontenut) u ċ-ċavetta tal-iffirmar tal-checkpoint tal-verifika f’ docker/secrets/audit-signing-key.pem, li Compose jmountja fil-workers bħala sigriet. Jeħtieġ biss sh, awk u openssl, u jirrifjuta li jissostitwixxi docker/.env eżistenti. Ikkopja ż-żewġ fajls barra l-host: mingħajr QUIRE_MASTER_KEY database rrestawrata ma tistax tiddekripta l-kredenzjali maħżuna tagħha. Biex timla l-fajl bl-idejn minflok, cp docker/.env.example docker/.env; il- fajl jgħid kif tiġġenera kull sigriet.

Iż-żewġ oriġini jridu jkunu https: is-servizz tal-kontenut jirrifjuta http sempliċi fi produzzjoni, u ma jridux jaqsmu dominju reġistrabbli. Is-servizz proxy itemm TLS għat-tnejn (ara “TLS”); init-env.sh jirrifjuta oriġini http://.

L-istack jibda f’ordni fissa, u kull pass jistenna lil ta’ qablu:

1. postgres isir b’saħħtu. Fl-ewwel bidu nett l-iskript init tiegħu (docker/postgres/init/90-passwords.sh) jissettja l-erba’ passwords tar-rwoli.
2. migrate japplika kull migrazzjoni u jibbutstrapja l-queue tax-xogħol fid- database tal-kontroll u f’kull database dedikata tat-tenant, jiċċekkja li huma kollha jaqblu, imbagħad joħroġ (docs/ops/upgrade.md). Il-migrazzjonijiet jaħdmu f’kull bidu u huma idempotenti, biex aġġornament huwa immaġni ġdida u restart.
3. init (apps/web/src/first-run.ts) jirreġistra d-database tal-applikazzjoni taħt QUIRE_DATABASE_ID u, meta QUIRE_SETUP_ADMIN_EMAIL huwa ssettjat, joħloq l- ewwel organizzazzjoni u l-amministratur tagħha. L-indirizz tad-dħul u password iġġenerata jiġu stampati darba, f’docker compose logs init.
4. web, content, worker, scheduler, collab u centrifugo jibdew.
5. proxy jibda ladarba web u content ikunu b’saħħithom.

Iftaħ https://demo. segwit mid-dominju tal-applikazzjoni tiegħek (il-log init jistampa l-indirizz eżatt tad-dħul), u idħol. Fuq installazzjoni lokali, afda l-awtorità taċ-ċertifikati tal-proxy l-ewwel (ara “TLS”). Biddel il-password iġġenerata f’/account/security.

Proċess mibdi mingħajr sigriet meħtieġ jirrifjuta li jibda u jsemmi s- setting nieqes fil-log tiegħu. Xejn ma jibda kkonfigurat nofsu.

Servizzi u profili

--profile full jibda kull servizz fakultattiv ħlief backup u h5p. Ibda wieħed b’docker compose -f docker/compose.yaml --profile scan up -d. Mingħajr servizz fakultattiv Quire xorta taħdem u tgħid x’huwa nieqes: l-ebda skenner ifisser uploads jinħażnu mhux skennjati u l-amministratur jingħad; l-ebda Gotenberg ifisser fajls joffru download minflok preview; l-ebda transcoder ifisser vidjo jindaqq bħala l-fajl oriġinali.

Kull immaġni ta’ parti terza u l-obbligi tal-liċenzja tagħha huma elenkati f’ docker/third-party-containers.yaml.

Konnessjoni ta’ fornitur H5P

Quire ma tinkorpora jew tibgħat l-ebda runtime H5P jew sidecar (ADR 0019). Jekk tuża H5P, ipprovdi l-abbonament hosted tiegħek jew opera l-istanza H5P self-hosted tiegħek separatament minn Quire. Irreġistra dak il-fornitur bħala għodda esterna LTI 1.3 u żid il-kontenut tiegħu mal-korsijiet bħala attivitajiet ta’ għodda. Quire tiskambja gradi u progress tal-attività/gradar permezz ta’ LTI Assignment and Grade Services (AGS). Jekk il-fornitur jibgħat ukoll dikjarazzjonijiet xAPI, ikkonfigura dan separatament għall- maħżen tad-dikjarazzjonijiet xAPI ta’ Quire; skambju ta’ gradi/progress AGS ma jibgħatx dikjarazzjonijiet xAPI. Imports ta’ Moodle jirrapportaw attivitajiet H5P bħala li jeħtieġu konnessjoni ta’ għodda LTI. Il-fornitur jibqa’ responsabbli għar-runtime H5P tiegħu, l-awtur, il-bank tal-kontenut u l-istorja tat-tentattivi.

Biex tħaddem l-istanza self-hosted tiegħek fuq dan il-host, issettja QUIRE_H5P_IMAGE għall- immaġni tiegħu u ibda l-profil h5p. Compose jippubblikaha fuq QUIRE_H5P_PORT (8090) u jżomm id-data tagħha fil-volum h5p-data; l-immaġni, u l- obbligi li jiġu magħha, jibqgħu tiegħek.

Settings

Kull proċess jaqra docker/.env. It-template, docker/.env.example, jelenka kull setting bid-default tiegħu. Il-gruppi:

Indirizzi

Sigrieti

Żomm kopja ta’ QUIRE_MASTER_KEY xi mkien ieħor barra dan il-host. Database rrestawrata mingħajrha ma tistax tiddekripta l-kredenzjali li żżomm.

Database

Passwords tar-rwoli jiġu applikati biss meta l-volum tad-database jinħoloq l-ewwel darba. Biex tbiddel waħda aktar tard, uża ALTER ROLE u mbagħad aġġorna l-URL li taqbel.

QUIRE_REPORT_DATABASE_URL jintuża għad-database fiżika kkonfigurata minn DATABASE_URL. Għal kull database fiżika reġistrata oħra, issettja l-URL tal-konnessjoni quire_report tagħha stess fl-ambjenti tal-web u tal-worker, imbagħad poġġi l-isem tal-varjabbli f’dik id-database Reporting environment variable bħala env:NAME. Ir-referenza trid tindika lill-istess database bħall-konnessjoni tal-app tagħha, idealment ir-replika tal-qari tagħha. Kull wiċċ tar-rapport isegwi l- tenant sad-database tiegħu stess konnessjoni tar-rapport: il-bennej tar-rapporti u rapporti ssejvjati, kunsinni skedati, esportazzjonijiet tar-rapporti, analitika, il-log tal-verifika, ir-riżorsi tal-verifika REST u t-tiftix tal-verifika tal-assistent. L-ebda waħda minnhom qatt ma tissellef URL tar-rapport ta’ database oħra. Meta database m’għandha l-ebda konnessjoni tar-rapport, rapporti ordinarji jaħdmu fuq il-konnessjoni tal-applikazzjoni tad-database stess, filwaqt li analitika u kull qari tal-verifika jirrifjutaw u jgħidu hekk, għax ir-rwol tal-applikazzjoni ma jistax jaqra t-trail tal-verifika.

Drivers

Valur ta’ driver li din ir-release ma tinkludix jiġi rifjutat meta l-livell web jibda, bis-setting imsemmija, aktar milli jiġi sostitwit bil-kwiet bid- default.

Immaġnijiet

Paġni jitolbu immaġnijiet f’erba’ daqsijiet fissi permezz ta’ /api/files/{id}/image/{size}, li jiċċekkja l-istess aċċess bħall-fajl innifsu u mbagħad jerġa’ jindirizza lejn is-servizz tal-immaġnijiet. Kull organizzazzjoni tista’ titlob għal QUIRE_IMAGE_SPECS_PER_HOUR (default 2000) pari ġodda ta’ immaġni u daqs fis-siegħa; daqsijiet diġà prodotti dik is-siegħa ma jgħoddux. Uża valkey jew postgres għal QUIRE_CACHE_DRIVER b’aktar minn container web wieħed, biex il- limitu jżomm bejniethom.

Cloudflare Images iżomm il-kopja tiegħu ta’ kull oriġinal li jservi. Meta fajl jitħassar, il-worker iħassar dik il-kopja qabel l-oriġinali.

Queue

Xogħol fl-isfond juża pg-boss fl-istess database Postgres, biex m’hemm l-ebda servizz queue x’tħaddem u xejn x’tikkonfigura. Xogħol jiġi kkwodjat fl-istess tranżazzjoni bħall-bidla li kkawżatu, biex ħabta ma tistax titlef wieħed jew tibgħat wieħed darbtejn. QUIRE_QUEUE_DRIVER huwa pgboss hawnhekk, id-default tiegħu; vercel u cloudflare iċaqalqu biss il-kunsinni ħfief ta’ notifiki u webhook lill-queue tal-pjattaforma stess, u l-gwidi Vercel u Cloudflare jiddeskrivuhom u kif il-livelli web tagħhom jikkwodjaw.

Email

Issettja waħda minn:

• QUIRE_EMAIL_PROVIDER_CONFIG: oġġett JSON li jsemmi fornitur HTTP u l-kredenzjali tiegħu, bħal {"provider":"postmark","token":"..."}. Postmark, Amazon SES, Mailgun, SendGrid u Resend huma appoġġjati.
• QUIRE_SMTP_URL: smtp://user:password@host:587. Din il-mira biss; il- miri serverless jimblokkaw SMTP.

QUIRE_MAIL_FROM huwa l-mittent. Biex tipprova Quire, ibda l-profil devmail, issettja QUIRE_SMTP_URL=smtp://mailpit:1025, u aqra l-posta f’ http://localhost:8025.

Servizzi fakultattivi

Osservabbiltà

OTEL_EXPORTER_OTLP_ENDPOINT isemmi l-kollettur li kull proċess jibgħat traċċi u metriki lilu; bil-profil observability huwa http://otelcol:4318, u docker/otel-collector.yaml huwa fejn iżżid l- esportatur għall-backend tiegħek. Il-livell web, worker, scheduler, content u collab jesportaw spans fuq OTLP/HTTP (talbiet web, tranżazzjonijiet tad-database tat-tenant, xogħol tal-worker u sejħiet ħerġin) meta jkun issettjat, u metriki lill- istess endpoint kull minuta (OTEL_METRICS_EXPORTER=none jitfihom). OTEL_TRACES_SAMPLER_ARG jissettja s-sehem ta’ traċċi miżmuma. Logs imorru fuq standard output f’LOG_LEVEL, u Compose ddawwarhom. Traċċi qatt ma jġorru data personali.

Egress reġjonali (residenza tad-data tal-UE)

QUIRE_REGION=eu jgħid li l-istack isservi organizzazzjonijiet tal-Unjoni Ewropea. Il- worker imbagħad iżomm kull talba ħierġa magħmula għal organizzazzjoni mwaħħla mal- UE għal allowlist (21-compliance.md sezzjoni 8.1). L-allowlist hija l- hosts li s-servizzi kkonfigurati jiddikjaraw għar-reġjun (l-endpoint tal-ħażna, il-fornitur tal-email, fornitur tal-vidjo hosted, il-miri tal-ħażna tal-organizzazzjoni stess, fornituri tal-AI u kont tal-email), il-hosts ta’ kull servizz taħt deroga attiva, u l-hosts li telenka int f’ QUIRE_EGRESS_ALLOW_HOSTS. Talba lil kull host pubbliku ieħor hija rifjutata qabel ma tintbagħat, ir-rifjut jinkiteb fit-trail tal-verifika tal-organizzazzjoni bħala privacy/egress_refused, u hija elenkata taħt Compliance, Data residency.

Organizzazzjonijiet tar-Renju Unit u tal-Istati Uniti mhumiex miżmuma ma’ lista ta’ hosts; iżommu l-kontrolli tar-reġjun tas-servizz. Issettja l-lista fuq il-worker; il-paġna tal-admin taqraha fuq il-livell web biex turi l-allowlist, għalhekk poġġiha f’docker/.env, li kull servizz jaqra.

Il-kontroll tal-applikazzjoni jagħti żball ċar u entrata tal-verifika, u mhuwiex il-garanzija: il-kodiċi jista’ jkun ħażin. Il-garanzija hija n-network. Compose ma jinfurzahiex għalik. Għal stack reġjonali, poġġi s-servizzi worker u web fuq network internal: true li l-unika rotta ħierġa tagħha hija proxy tal-egress (pereżempju container Squid jew tinyproxy) li jippermetti l-istess hosts bħala QUIRE_EGRESS_ALLOW_HOSTS flimkien mal-hosts tas-servizzi kkonfigurati tiegħek, u issettja HTTPS_PROXY għal dawk is-servizzi. Il-paġna tar-residenza telenka l-hosts eżatti li l-applikazzjoni tippermetti, biex iż-żewġ listi jkunu jistgħu jitqabblu.

Saħħa

docker compose -f docker/compose.yaml ps juri s-saħħa ta’ kull servizz.

TLS

Is-servizz proxy (Caddy, Apache-2.0, docker/caddy/Caddyfile) huwa parti mill- istack default. Iwieġeb fuq ports 80 u 443 u jgħaddi:

init-env.sh jidderiva QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL u IMGPROXY_URL miż-żewġ oriġini, biex ma jistgħux jinfirdu. Editjahom flimkien jekk tibdel oriġini bl-idejn.

Ċertifikati jsegwu QUIRE_PROXY_TLS:

• internal (id-default): l-awtorità taċ-ċertifikati ta’ Caddy stess, għal localhost, *.localhost u lvh.me. Afda l-għerq tagħha darba, imbagħad ibbrażja:

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

  Żid quire-local-ca.crt mal-maħżen tal-fiduċja tas-sistema jew tal-browser. curl jeħodha b’--cacert.

• Indirizz email: ċertifikati ACME awtomatiċi (Let’s Encrypt, imbagħad ZeroSSL) għal hostnames reali. DNS għaż-żewġ oriġini u kull host tat-tenant irid jindika hawnhekk, u ports 80 u 443 iridu jkunu milħuqa mill-internet.

Hosts tat-tenant jinħarġu meta jintalbu, fl-ewwel żjara, u biss meta web jikkonferma li l-isem huwa ta’ din l-installazzjoni (/tls-allowed, mistoqsi fuq in- network ta’ Compose). L-ebda ċertifikat wildcard jew plugin ta’ fornitur DNS mhu meħtieġ, u barrani li jindika isem lejn il-host ma jistax iġiegħlu jitlob ċertifikati. Ċertifikati u l-awtorità lokali jgħixu fil-volum caddy-data; agħmel backup tiegħu mal-bqija jekk tuża internal.

Web jemmen X-Forwarded-For mill-proxy waħdu: il-proxy għandu indirizz fiss (QUIRE_PROXY_ADDRESS, default 172.29.64.10) fuq subnet fissa (QUIRE_COMPOSE_SUBNET), u QUIRE_TRUSTED_PROXY_CIDRS isemmi dak l-indirizz. Jekk is-subnet tikkonfliġġi ma’ network fuq il-host, biddel it-tnejn u ħaddem docker compose down qabel up.

Wara l-proxy reverse tiegħek

Biex tuża load balancer jew proxy li diġà tħaddem minflok, ħalli proxy barra (docker compose up -d --scale proxy=0) u temm TLS quddiem web (8080), content (8081), collab (1234, websocket) u centrifugo (8000, websocket). Issettja l-indirizzi pubbliċi f’QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN u QUIRE_COLLAB_URL (wss://), u l-firxa tal-indirizzi tal-proxy tiegħek f’QUIRE_TRUSTED_PROXY_CIDRS.

Solvi problemi

• init joħroġ bi “QUIRE_DATABASE_ID is not a UUID”: issettjah b’uuidgen.
• web jerġa’ jibda b’“did not start on compose”’: il-log jelenka kull setting li ma jistax jonora u x’tuża minflok.
• Tibdil ta’ password ta’ rwol f’.env wara l-ewwel bidu ma jagħmel xejn: l- iskript init jaħdem darba. Uża ALTER ROLE.
• Uploads ifallu bi żball ta’ skennjar waqt li CLAMAV_URL huwa ssettjat: ClamAV jniżżel is-signatures tiegħu fl-ewwel bidu, li jieħu ftit minuti.