Gosod Quire gyda Docker Compose

Dyma’r cynnyrch llawn ar un host: y LMS, ei waith cefndir, y gwasanaethau amser real a golygu cydweithredol, a phob gwasanaeth dewisol y tu ôl i broffil. Mae’r dyluniad yn adran 2 o docs/architecture/23-ops.md.

Targedau eraill: dim ond haen we mae Vercel a Cloudflare Workers yn ei rhedeg. Mae uwchraddio yn upgrade.md, a chopïau wrth gefn a’r prawf adfer yn backup-restore.md.

Beth sydd ei angen

• Docker Engine 27 neu’n ddiweddarach gyda’r ategyn Compose 2.30 neu’n ddiweddarach.
• 4 craidd CPU ac 8 GB o gof ar gyfer y stack diofyn; 8 craidd ac 16 GB gyda --profile full (mae ClamAV yn unig yn dal tua 1.5 GB o lofnodion).
• Enw DNS ar gyfer yr haen we ac un arall ar gyfer cynnwys nad yw’n ddibynadwy. Rhaid iddynt fod yn hostiaid gwahanol: mae pecynnau SCORM a HTML a lwythir i fyny yn rhedeg o’r tarddiad cynnwys fel na allant byth ddarllen cwcis y LMS.
• Ar gyfer prawf lleol, mae lvh.me a *.localhost yn datrys i 127.0.0.1, sef yr hyn y mae docker/.env.example yn ei ddefnyddio. Mae gwasanaeth proxy y stack ei hun yn gwasanaethu’r ddau dros https gydag awdurdod tystysgrif lleol, felly nid oes angen gosod dim arall (gweler “TLS”).
• Porthladdoedd 80 a 443 yn rhydd ar y host (QUIRE_PROXY_HTTP_PORT a QUIRE_PROXY_HTTPS_PORT sy’n eu symud).

Rhediad cyntaf

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

Mae docker/scripts/init-env.sh yn ysgrifennu docker/.env o docker/.env.example gyda phob cyfrinach wedi’i chynhyrchu (cyfrineiriau cronfa ddata, yr allweddi llofnodi a meistr, pâr allweddi lansio cynnwys) ac allwedd llofnodi pwynt archwilio yn docker/secrets/audit-signing-key.pem, y mae Compose yn ei mowntio i’r gweithwyr fel cyfrinach. Dim ond sh, awk ac openssl sydd eu hangen arno, ac mae’n gwrthod ailysgrifennu docker/.env sy’n bodoli eisoes. Copïwch y ddwy ffeil oddi ar y host: heb QUIRE_MASTER_KEY ni all cronfa ddata a adferwyd ddadgryptio ei manylion mewngofnodi sydd wedi’u storio. I lenwi’r ffeil â llaw yn lle hynny, cp docker/.env.example docker/.env; mae’r ffeil yn dweud sut i gynhyrchu pob cyfrinach.

Rhaid i’r ddau darddiad fod yn https: mae’r gwasanaeth cynnwys yn gwrthod http plaen mewn cynhyrchu, ac ni ddylent rannu parth cofrestradwy. Mae’r gwasanaeth proxy yn terfynu TLS ar gyfer y ddau (gweler “TLS”); mae init-env.sh yn gwrthod tarddiad http://.

Mae’r stack yn cychwyn mewn trefn sefydlog, ac mae pob cam yn aros am y cam o’i flaen:

1. Daw postgres yn iach. Ar y cychwyn cyntaf mae ei sgript cychwyn (docker/postgres/init/90-passwords.sh) yn gosod pedwar cyfrinair rôl.
2. Mae migrate yn cymhwyso pob mudo ac yn cychwyn ciw’r swyddi yn y gronfa ddata reoli ac ym mhob cronfa ddata tenant benodedig, yn gwirio eu bod i gyd eu bod i gyd yn cytuno, ac yna’n gadael (docs/ops/upgrade.md). Mae mudo’n rhedeg ar bob cychwyn ac yn idempotent, felly delwedd newydd ac ailgychwyn yw uwchraddiad.
3. Mae init (apps/web/src/first-run.ts) yn cofnodi cronfa ddata’r rhaglen o dan QUIRE_DATABASE_ID a, phan osodir QUIRE_SETUP_ADMIN_EMAIL, yn creu’r sefydliad cyntaf a’i weinyddwr. Caiff cyfeiriad mewngofnodi a chyfrinair a gynhyrchwyd eu hargraffu unwaith yn docker compose logs init.
4. Mae web, content, worker, scheduler, collab a centrifugo yn cychwyn.
5. Mae proxy yn cychwyn unwaith y bydd web a content yn iach.

Agorwch https://demo. ac yna barth eich rhaglen (mae’r cofnod init yn argraffu’r union gyfeiriad mewngofnodi), a mewngofnodwch. Ar osodiad lleol, ymddiriedwch yn awdurdod tystysgrif y proxy yn gyntaf (gweler “TLS”). Newidiwch y cyfrinair a gynhyrchwyd yn /account/security.

Mae proses a gychwynnwyd heb gyfrinach ofynnol yn gwrthod cychwyn ac yn enwi’r gosodiad coll yn ei chofnod. Ni fydd dim yn cychwyn wedi’i ffurfweddu’n rhannol.

Gwasanaethau a phroffiliau

Mae --profile full yn cychwyn pob gwasanaeth dewisol heblaw backup a h5p. Dechreuwch un gyda docker compose -f docker/compose.yaml --profile scan up -d. Heb wasanaeth dewisol, mae Quire yn dal i weithio ac yn dweud beth sydd ar goll: heb sganiwr cedwir llwythiadau heb eu sganio a rhoddir gwybod i’r gweinyddwr; heb Gotenberg, cynigir lawrlwytho ffeiliau yn lle rhagolwg; heb drawsnewidydd, caiff fideo ei chwarae fel y ffeil wreiddiol.

Rhestrir pob delwedd trydydd parti a’i rhwymedigaethau trwydded yn docker/third-party-containers.yaml.

Cysylltu darparwr H5P

Nid yw Quire yn mewnosod nac yn cludo runtime neu sidecar H5P (ADR 0019). Os ydych yn defnyddio H5P, darparwch eich tanysgrifiad lletyol eich hun neu weithredwch eich instans H5P hunangynhaliol eich hun ar wahân i Quire. Cofrestrwch y darparwr hwnnw fel offeryn allanol LTI 1.3 ac ychwanegwch ei gynnwys at gyrsiau fel gweithgareddau offeryn. Mae Quire yn cyfnewid graddau a chynnydd gweithgaredd/marcio drwy LTI Assignment and Grade Services (AGS). Os bydd y darparwr hefyd yn anfon datganiadau xAPI, ffurfweddwch hynny ar wahân ar gyfer storfa datganiadau xAPI Quire; nid yw cyfnewid graddau/cynnydd AGS yn anfon datganiadau xAPI. Mae mewnforion Moodle yn adrodd bod angen cysylltiad offeryn LTI ar weithgareddau H5P. Mae’r darparwr yn parhau’n gyfrifol am ei runtime H5P, ei awduro, ei fanc cynnwys a’i hanes ymdrechion.

I redeg eich instans hunangynhaliol eich hun ar y host hwn, gosodwch QUIRE_H5P_IMAGE i’w ddelwedd a dechreuwch broffil h5p. Mae Compose yn ei gyhoeddi ar QUIRE_H5P_PORT (8090) ac yn cadw ei ddata yng nghyfrol h5p-data; eich cyfrifoldeb chi yw’r ddelwedd a’r rhwymedigaethau sy’n dod gyda hi.

Gosodiadau

Mae pob proses yn darllen docker/.env. Mae’r templed, docker/.env.example, yn rhestru pob gosodiad a’i ragosodiad. Y grwpiau:

Cyfeiriadau

Cyfrinachau

Cadwch gopi o QUIRE_MASTER_KEY rywle heblaw’r host hwn. Ni all cronfa ddata a adferwyd hebddi ddadgryptio’r manylion mewngofnodi sydd ynddi.

Cronfa ddata

Dim ond pan gaiff cyfrol y gronfa ddata ei chreu am y tro cyntaf y cymhwysir cyfrineiriau rôl. I newid un yn ddiweddarach, defnyddiwch ALTER ROLE ac yna diweddarwch yr URL cyfatebol.

Defnyddir QUIRE_REPORT_DATABASE_URL ar gyfer y gronfa ddata ffisegol a ffurfweddwyd gan DATABASE_URL. Ar gyfer unrhyw gronfa ddata ffisegol gofrestredig arall, gosodwch ei URL cysylltiad quire_report ei hun yn amgylcheddau’r we a’r worker, yna rhowch enw’r newidyn yng maes Newidyn amgylchedd adrodd y gronfa ddata honno fel env:NAME. Rhaid i’r cyfeirnod bwyntio at yr un gronfa ddata â chysylltiad yr ap, sef ei replica darllen yn ddelfrydol. Mae pob rhyngwyneb adrodd yn dilyn y tenant i gysylltiad adrodd ei gronfa ddata ei hun: yr adeiladydd adroddiadau a’r adroddiadau a gadwyd, dosbarthiadau wedi’u trefnu, allforion adroddiadau, dadansoddeg, cofnod archwilio, adnoddau archwilio REST a chwiliad archwilio’r cynorthwyydd. Nid oes un ohonynt byth yn benthyg URL adrodd cronfa ddata arall. Pan nad oes gan gronfa ddata gysylltiad adrodd, mae adroddiadau arferol yn rhedeg ar ei chysylltiad rhaglen ei hun, tra bo dadansoddeg a phob darlleniad archwilio’n gwrthod ac yn dweud hynny, oherwydd na all rôl y rhaglen ddarllen y cofnod archwilio.

Gyrwyr

Gwrthodir gwerth gyrrwr nad yw’r datganiad hwn yn ei gynnwys pan fydd yr haen we’n cychwyn, gan enwi’r gosodiad, yn hytrach na’i ddisodli’n dawel â’r rhagosodiad.

Delweddau

Mae tudalennau’n gofyn am ddelweddau mewn pedwar maint sefydlog drwy /api/files/{id}/image/{size}, sy’n gwirio’r un mynediad â’r ffeil ei hun ac yna’n ailgyfeirio at wasanaeth y ddelwedd. Gall pob sefydliad ofyn am QUIRE_IMAGE_SPECS_PER_HOUR (diofyn 2000) parau delwedd a maint newydd yr awr; nid yw meintiau a gynhyrchwyd eisoes yr awr honno’n cyfrif. Defnyddiwch valkey neu postgres ar gyfer QUIRE_CACHE_DRIVER gyda mwy nag un cynhwysydd web fel bod y terfyn yn berthnasol iddynt i gyd.

Mae Cloudflare Images yn cadw ei gopi ei hun o bob gwreiddiol mae’n ei wasanaethu. Pan gaiff ffeil ei dileu, mae’r worker yn dileu’r copi hwnnw cyn y gwreiddiol.

Ciw

Mae swyddi cefndir yn defnyddio pg-boss yn yr un gronfa ddata Postgres, felly nid oes angen rhedeg gwasanaeth ciw na ffurfweddu dim. Caiff swyddi eu ciwio yn yr un trafodiad â’r newid a’u hachosodd, felly ni all damwain golli un na’i hanfon ddwywaith. QUIRE_QUEUE_DRIVER yw pgboss yma, ei ragosodiad; mae vercel a cloudflare yn symud hysbysiadau ysgafn a dosbarthiadau webhook yn unig i giw y platfform ei hun; mae canllawiau Vercel a Cloudflare yn eu disgrifio a sut mae eu haenau gwe’n eu ciwio.

E-bost

Gosodwch un o’r rhain:

• QUIRE_EMAIL_PROVIDER_CONFIG: gwrthrych JSON sy’n enwi darparwr HTTP a’i fanylion mewngofnodi, megis {"provider":"postmark","token":"..."}. Cefnogir Postmark, Amazon SES, Mailgun, SendGrid a Resend.
• QUIRE_SMTP_URL: smtp://user:password@host:587. Ar y targed hwn yn unig; mae targedau heb weinydd yn rhwystro SMTP.

QUIRE_MAIL_FROM yw’r anfonwr. I roi cynnig ar Quire, dechreuwch broffil devmail, gosodwch QUIRE_SMTP_URL=smtp://mailpit:1025, a darllenwch bost yn http://localhost:8025.

Gwasanaethau dewisol

Arsylwadwyedd

Mae OTEL_EXPORTER_OTLP_ENDPOINT yn enwi’r casglwr y mae pob proses yn anfon olion a metrigau ato; gyda phroffil observability mae’n http://otelcol:4318, ac docker/otel-collector.yaml yw lle i ychwanegu’r allforiwr ar gyfer eich ôl-wyneb. Mae prosesau web, worker, scheduler, content a collab yn allforio bylchau dros OTLP/HTTP (ceisiadau web, trafodion cronfeydd data tenant, swyddi worker a galwadau allan) pan fydd wedi’i osod, a metrigau i’r un endpoint bob munud (OTEL_METRICS_EXPORTER=none sy’n eu diffodd). Mae OTEL_TRACES_SAMPLER_ARG yn gosod cyfran yr olion a gedwir. Mae logiau’n mynd i allbwn safonol ar LOG_LEVEL, ac mae Compose yn eu cylchdroi. Nid yw olion byth yn cario data personol.

Egress rhanbarthol (preswyliaeth data’r UE)

Mae QUIRE_REGION=eu yn datgan bod y stack yn gwasanaethu sefydliadau’r Undeb Ewropeaidd. Mae’r worker wedyn yn dal pob cais allanol a wneir ar ran sefydliad wedi’i binio i’r UE at restr ganiatáu (adran 8.1 yn 21-compliance.md). Y rhestr ganiatáu yw’r hostiaid y mae gwasanaethau wedi’u ffurfweddu’n eu datgan ar gyfer y rhanbarth (endpoint y storfa, darparwr e-bost, darparwr fideo lletyol, targedau storio’r sefydliad ei hun, darparwyr AI a chyfrif e-bost), hostiaid unrhyw wasanaeth sydd dan eithriad gweithredol, a’r hostiaid rydych yn eu rhestru yn QUIRE_EGRESS_ALLOW_HOSTS. Gwrthodir cais at unrhyw host cyhoeddus arall cyn ei anfon, ysgrifennir y gwrthodiad yng nghofnod archwilio’r sefydliad fel privacy/egress_refused, ac fe’i rhestrir o dan Cydymffurfiaeth, Preswyliaeth data.

Nid yw sefydliadau’r DU a’r Unol Daleithiau wedi’u cyfyngu i restr host; maent yn cadw gwiriadau rhanbarth gwasanaeth. Gosodwch y rhestr ar y worker; mae’r dudalen weinyddol yn ei darllen ar yr haen we i ddangos y rhestr ganiatáu, felly rhowch hi yn docker/.env, a ddarllenir gan bob gwasanaeth.

Mae gwiriad y rhaglen yn rhoi gwall clir a chofnod archwilio, ond nid dyma’r warant: gall cod fod yn anghywir. Y rhwydwaith yw’r warant. Nid yw Compose yn ei gorfodi drosoch. Ar gyfer stack rhanbarthol, rhowch wasanaethau worker a web ar rwydwaith internal: true a’i unig lwybr allan yw proxy egress (er enghraifft cynhwysydd Squid neu tinyproxy) sy’n caniatáu’r un hostiaid â QUIRE_EGRESS_ALLOW_HOSTS ynghyd â hostiaid eich gwasanaethau ffurfweddu, a gosodwch HTTPS_PROXY ar gyfer y gwasanaethau hynny. Mae’r dudalen preswyliaeth yn rhestru’r hostiaid union y mae’r rhaglen yn eu caniatáu, felly gellir cymharu’r ddwy restr.

Iechyd

Mae docker compose -f docker/compose.yaml ps yn dangos iechyd pob gwasanaeth.

TLS

Mae gwasanaeth proxy (Caddy, Apache-2.0, docker/caddy/Caddyfile) yn rhan o’r stack diofyn. Mae’n ateb ar borthladdoedd 80 a 443 ac yn llwybro:

Mae init-env.sh yn deillio QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL ac IMGPROXY_URL o’r ddau darddiad, felly ni allant wyro oddi wrth ei gilydd. Golygwch nhw gyda’i gilydd os newidiwch darddiad â llaw.

Mae tystysgrifau’n dilyn QUIRE_PROXY_TLS:

• internal (diofyn): awdurdod tystysgrif Caddy ei hun, ar gyfer localhost, *.localhost a lvh.me. Ymddiriedwch yn ei wraidd unwaith, yna porwch:

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

  Ychwanegwch quire-local-ca.crt at storfa ymddiriedaeth y system neu’r porwr. Mae curl yn ei dderbyn drwy --cacert.

• Cyfeiriad e-bost: tystysgrifau ACME awtomatig (Let’s Encrypt, yna ZeroSSL) ar gyfer enwau host go iawn. Rhaid i DNS y ddau darddiad a phob host tenant bwyntio yma, a rhaid bod modd cyrraedd porthladdoedd 80 a 443 o’r rhyngrwyd.

Rhoddir hostiaid tenant ar alw, ar yr ymweliad cyntaf, a dim ond pan fydd web yn cadarnhau bod yr enw’n perthyn i’r gosodiad hwn (/tls-allowed, a ofynnir ar rwydwaith Compose). Nid oes angen tystysgrif wildcard nac ategyn darparwr DNS, ac ni all dieithryn sy’n pwyntio enw at y host beri iddo ofyn am dystysgrifau. Mae tystysgrifau a’r awdurdod lleol yng nghyfrol caddy-data; gwnewch gopi wrth gefn gyda’r gweddill os defnyddiwch internal.

Mae Web yn ymddiried yn X-Forwarded-For o’r proxy yn unig: mae gan y proxy gyfeiriad sefydlog (QUIRE_PROXY_ADDRESS, diofyn 172.29.64.10) ar is-rwydwaith sefydlog (QUIRE_COMPOSE_SUBNET), ac mae QUIRE_TRUSTED_PROXY_CIDRS yn enwi’r cyfeiriad hwnnw. Os bydd yr is-rwydwaith yn gwrthdaro â rhwydwaith ar y host, newidiwch y ddau a rhedwch docker compose down cyn up.

Y tu ôl i’ch proxy gwrthdro eich hun

I ddefnyddio cydbwysydd llwyth neu proxy rydych eisoes yn ei redeg yn lle hynny, peidiwch â chynnwys proxy (docker compose up -d --scale proxy=0) a therfynwch TLS o flaen web (8080), content (8081), collab (1234, websocket) a centrifugo (8000, websocket). Gosodwch y cyfeiriadau cyhoeddus yn QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN a QUIRE_COLLAB_URL (wss://), ac ystod cyfeiriadau eich proxy yn QUIRE_TRUSTED_PROXY_CIDRS.

Datrys problemau

• Mae init yn gadael gyda “QUIRE_DATABASE_ID is not a UUID”: gosodwch ef gyda uuidgen.
• Mae web yn ailgychwyn gyda “did not start on compose”: mae’r log yn rhestru pob gosodiad na all ei barchu a beth i’w ddefnyddio yn ei le.
• Nid yw newid cyfrinair rôl yn .env ar ôl y cychwyn cyntaf yn gwneud dim: dim ond unwaith mae’r sgript cychwyn yn rhedeg. Defnyddiwch ALTER ROLE.
• Mae llwythiadau’n methu â gwall sgan tra bo CLAMAV_URL wedi’i osod: mae ClamAV yn lawrlwytho ei lofnodion ar y cychwyn cyntaf, sy’n cymryd ychydig funudau.