Stàlaich Quire le Docker Compose

‘S e seo am bathar slàn air aon aoigh: an LMS, obair a’ chùl-raoin, seirbheisean fìor-ùine is deasachaidh cho-obrachail, agus gach seirbheis roghainneil a tha air cùl pròifil. Tha an dealbhadh ann an earrann 2 de docs/architecture/23-ops.md.

Targaidean eile: chan eil Vercel agus Cloudflare Workers a’ ruith ach an t-sreath-lìn. Tha ùrachaidhean ann an upgrade.md, agus cùl-taicean is an deuchainn ath-nuadhachaidh ann an backup-restore.md.

Na tha a dhìth ort

• Docker Engine 27 no nas ùire leis a’ phlugan Compose 2.30 no nas ùire.
• 4 coirean CPU agus 8 GB de chuimhne airson a’ chàirn bhunaiteach; 8 coirean agus 16 GB le --profile full (tha mu 1.5 GB de shoidhnichean aig ClamAV leis fhèin).
• Ainm DNS airson an t-sreath-lìn agus dàrna tè airson susbaint neo-earbsach. Feumaidh iad a bhith nan diofar aoighean: ruithidh pasganan SCORM agus HTML a chaidh a luchdadh suas air tùs an t-susbaint gus nach urrainn dhaibh briosgaidean an LMS a leughadh.
• Airson deuchainn ionadail, tha lvh.me agus *.localhost a’ fuasgladh gu 127.0.0.1, mar a tha docker/.env.example a’ cleachdadh. Tha seirbheis proxy a’ chàirn a’ frithealadh an dà chuid thairis air https le ùghdarras teisteanais ionadail, agus mar sin cha tèid dad eile a stàladh (faic “TLS”).
• Feumaidh puirt 80 agus 443 a bhith saor air an aoigh (QUIRE_PROXY_HTTP_PORT agus QUIRE_PROXY_HTTPS_PORT gan gluasad).

A’ chiad ruith

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

Sgrìobhaidh docker/scripts/init-env.sh docker/.env bho docker/.env.example, leis gach dìomhaireachd air a gineadh (faclan-faire stòr-dàta, iuchraichean-soidhnidh is maighstir, paidhir iuchrach cur-air-bhog an t-susbaint), agus an iuchair-soidhnidh puing-sgrùdaidh aig docker/secrets/audit-signing-key.pem, a chuireas Compose suas dhan luchd-obrach mar dhìomhaireachd. Chan fheum e ach sh, awk agus openssl, agus diùltas e docker/.env a tha ann mar-thà a sgrìobhadh thairis air. Dèan lethbhreac dhen dà fhaidhle far an aoigh: às aonais QUIRE_MASTER_KEY chan urrainn do stòr-dàta ath-nuadhaichte na teisteanasan stòraichte aige a dhì-chrioptachadh. Gus am faidhle a lìonadh le làimh, ruith cp docker/.env.example docker/.env; tha am faidhle ag innse mar a ghineas tu gach dìomhaireachd.

Feumaidh an dà thùs a bhith https: diùltas seirbheis an t-susbaint http lom ann an riochdachadh, agus chan fhaod an aon àrainn chlàraichte a bhith aca. Bidh seirbheis proxy a’ crìochnachadh TLS airson an dà chuid (faic “TLS”); diùltas init-env.sh tùs http://.

Tòisichidh an càrn ann an òrdugh suidhichte, agus feithidh gach ceum gus am bi am fear roimhe deiseil:

1. Bidh postgres fallain. Aig a’ chiad tòiseachadh a-riamh suidhichidh an sgriobt tòiseachaidh aige (docker/postgres/init/90-passwords.sh) faclan-faire nan ceithir dreuchdan.
2. Cuiridh migrate gach imrich an sàs agus tòisichidh e ciudha nan obraichean ann an stòr-dàta smachd agus anns gach stòr-dàta neach-gabhail sònraichte, nì e cinnteach gu bheil iad uile ag aontachadh agus an uair sin sguiridh e (docs/ops/upgrade.md). Ruithidh imrichean aig gach tòiseachadh agus tha iad idempotent, agus mar sin ’s e ìomhaigh ùr agus ath-thòiseachadh a th’ ann an ùrachadh.
3. Clàraidh init (apps/web/src/first-run.ts) stòr-dàta na h-aplacaid fo QUIRE_DATABASE_ID agus, ma tha QUIRE_SETUP_ADMIN_EMAIL suidhichte, cruthaichidh e a’ chiad bhuidheann agus an rianaire aice. Clò-bhualar seòladh clàraidh a-steach agus facal-faire gineadh aon turas ann an docker compose logs init.
4. Tòisichidh web, content, worker, scheduler, collab agus centrifugo.
5. Tòisichidh proxy nuair a bhios web agus content fallain.

Fosgail https://demo. agus an uair sin àrainn na h-aplacaid agad (tha an log init a’ clò-bhualadh dearbh sheòladh a’ chlàraidh a-steach) agus clàraich a-steach. Air stàladh ionadail, earb ris an ùghdarras teisteanais aig an neach-ionaid an toiseach (faic “TLS”). Atharraich am facal-faire gineadh aig /account/security.

Diùltas pròiseas a thòisicheas gun dìomhaireachd riatanach tòiseachadh agus ainmichidh e an roghainn a tha a dhìth san log aige. Cha tòisich dad le rèiteachadh leth-choileanta.

Seirbheisean is pròifilean

Tòisichidh --profile full gach seirbheis roghainneil ach backup agus h5p. Tòisich fear le docker compose -f docker/compose.yaml --profile scan up -d. Obraichidh Quire às aonais seirbheis roghainneil agus innsidh e dè tha a dhìth: mura h-eil sganair ann, thèid luchdachadh suas a stòradh gun sganair agus thèid innse dhan rianaire; às aonais Gotenberg, faodar faidhlichean a luchdadh a-nuas seach an ro-shealladh; às aonais transcoder, cluichidh bhidio mar am faidhle tùsail.

Tha gach ìomhaigh treas-phàrtaidh agus na dleastanasan ceadachais aice air an liostadh ann an docker/third-party-containers.yaml.

A’ ceangal solaraiche H5P

Chan eil Quire a’ fighe a-steach no a’ cur inneal-ruith no sidecar H5P air falbh (ADR 0019). Ma chleachdas tu H5P, faigh fo-sgrìobhadh aoigheachd agad fhèin no obraich eisimpleir H5P fèin-aoigheachd air leth bho Quire. Clàraich an solaraiche mar inneal LTI 1.3 taobh a-muigh agus cuir an t-susbaint aige ri cùrsaichean mar ghnìomhan inneil. Bidh Quire ag iomlaid ìrean agus adhartas gnìomh/rangachaidh tro LTI Assignment and Grade Services (AGS). Ma chuireas an solaraiche aithrisean xAPI cuideachd, rèitich sin air leth airson stòr aithrisean xAPI Quire; cha chuir iomlaid ìre/adhartais AGS aithrisean xAPI. Tha ion-phortaidhean Moodle ag aithris gu bheil ceangal inneil LTI a dhìth air gnìomhan H5P. Bidh an solaraiche fhathast an urra ris an inneal-ruith H5P, sgrìobhadh, banca susbaint agus eachdraidh oidhirpean aige fhèin.

Gus eisimpleir fèin-aoigheachd agad fhèin a ruith air an aoigh seo, suidhich QUIRE_H5P_IMAGE dhan ìomhaigh aige agus tòisich pròifil h5p. Foillsichidh Compose e air QUIRE_H5P_PORT (8090) agus cumaidh e dàta san leabhar h5p-data; ’s ann leat fhèin a tha an ìomhaigh agus na dleastanasan a thig na cois.

Roghainnean

Leughaidh gach pròiseas docker/.env. Tha an teamplaid docker/.env.example a’ liostadh gach roghainn agus a luach bunaiteach. Seo na buidhnean:

Seòlaidhean

Dìomhaireachdan

Cùm lethbhreac de QUIRE_MASTER_KEY ann an àite eile seach an aoigh seo. Chan urrainn do stòr-dàta ath-nuadhaichte às aonais a theisteanasan a dhì-chrioptachadh.

Stòr-dàta

Cha chuirear faclan-faire dreuchd an sàs ach nuair a chruthaichear leabhar an stòr-dàta an toiseach. Gus fear atharrachadh nas anmoiche, cleachd ALTER ROLE agus ùraich an URL fhreagarrach an uair sin.

Thèid QUIRE_REPORT_DATABASE_URL a chleachdadh airson an stòr-dàta fiosaigeach a tha DATABASE_URL a’ rèiteachadh. Airson stòr-dàta fiosaigeach clàraichte sam bith eile, suidhich an URL ceangail quire_report aige fhèin ann an àrainneachdan web agus worker, agus cuir ainm a’ chaochladair ann an raon Caochladair àrainneachd aithisgean an stòr-dàta sin mar env:NAME. Feumaidh an t-iomradh sealltainn dhan aon stòr-dàta ri ceangal na h-aplacaid aige, mas fheàrr ri mac-samhail le leughadh a-mhàin. Leanaidh gach uachdar aithisgean an neach-gabhail gu ceangal aithisgean an stòr-dàta aige fhèin: togadair aithisgean agus aithisgean sàbhailte, lìbhrigeadh clàraichte, às-phortadh aithisgean, anailiseachd, log sgrùdaidh, goireasan sgrùdaidh REST agus lorg sgrùdaidh an neach-cuideachaidh. Cha toir gin dhiubh iasad uair sam bith de URL aithisgean stòr-dàta eile. Mura h-eil ceangal aithisgean aig stòr-dàta, ruithidh aithisgean àbhaisteach air a cheangal aplacaid fhèin; thèid anailiseachd agus gach leughadh sgrùdaidh a dhiùltadh leis an adhbhar, oir chan urrainn do dhreuchd na h-aplacaid sreath an sgrùdaidh a leughadh.

Draibhearan

Thèid luach draibhear nach eil san tionndadh seo a dhiùltadh nuair a thòisicheas an t-sreath-lìn, leis an roghainn air ainmeachadh, seach a chur na àite gu sàmhach leis a’ bhun-roghainn.

Ìomhaighean

Iarraidh duilleagan ìomhaighean aig ceithir meudan suidhichte tro /api/files/{id}/image/{size}; nì seo sgrùdadh air an aon chothrom ris an fhaidhle fhèin agus an uair sin ath-sheòlaidh e dhan t-seirbheis ìomhaighean. Faodaidh gach buidheann QUIRE_IMAGE_SPECS_PER_HOUR (2000 mar bhun-roghainn) paidhrichean ùra de dh’ìomhaigh is meud iarraidh gach uair; chan eil meudan a chaidh a dhèanamh mar-thà san uair sin a’ cunntadh. Cleachd valkey no postgres airson QUIRE_CACHE_DRIVER ma tha barrachd air aon soitheach-lìn ann gus am bi a’ chrìoch coitcheann eatorra.

Cumaidh Cloudflare Images a lethbhreac fhèin de gach ìomhaigh thùsail a bhios e a’ frithealadh. Nuair a sguabar faidhle às, sguabaidh an neach-obrach às an lethbhreac sin ron tùsail.

Ciudha

Cleachdaidh obraichean cùl-raoin pg-boss san aon stòr-dàta Postgres, agus mar sin chan eil seirbheis ciudha ri ruith no rèiteachadh. Thèid obraichean a chur sa chiudha anns an aon ghnothach ris an atharrachadh a dh’adhbhraich iad, agus mar sin chan urrainn do thubaist fear a chall no a chur dà thuras. Is e QUIRE_QUEUE_DRIVER pgboss an seo, a luach bunaiteach; gluaisidh vercel agus cloudflare lìbhrigeadh aotrom brathan is webhook a-mhàin gu ciudha an àrd-ùrlair fhèin. Tha na stiùiridhean Vercel agus Cloudflare a’ mìneachadh nan ciudha sin agus mar a chuireas na sreathan-lìn aca obraichean annta.

Post-d

Suidhich fear dhiubh seo:

• QUIRE_EMAIL_PROVIDER_CONFIG: nì JSON ag ainmeachadh solaraiche HTTP agus na teisteanasan aige, mar {"provider":"postmark","token":"..."}. Tha Postmark, Amazon SES, Mailgun, SendGrid agus Resend a’ faighinn taic.
• QUIRE_SMTP_URL: smtp://user:password@host:587. An targaid seo a-mhàin; bac targaidean gun fhrithealaiche SMTP.

Is e QUIRE_MAIL_FROM an seòladair. Gus Quire fheuchainn, tòisich pròifil devmail, suidhich QUIRE_SMTP_URL=smtp://mailpit:1025 agus leugh post-d aig http://localhost:8025.

Seirbheisean roghainneil

Amharcachd

Tha OTEL_EXPORTER_OTLP_ENDPOINT ag ainmeachadh an neach-cruinneachaidh dhan cuir gach pròiseas tracadh is meatraigean; leis a’ phròifil observability ’s e http://otelcol:4318 a th’ ann, agus ann an docker/otel-collector.yaml cuiridh tu às-phortaichear airson do chùl-raon. Ma tha e suidhichte, cuiridh na pròiseasan web, worker, scheduler, content agus collab raointean thairis air OTLP/HTTP (iarrtasan-lìn, gnothaichean stòr-dàta luchd-gabhail, obraichean agus gairmean a-mach) agus meatraigean chun an aon phuing gach mionaid (OTEL_METRICS_EXPORTER=none gan cur dheth). Suidhichidh OTEL_TRACES_SAMPLER_ARG a’ chuibhreann de thracan a thèid a chumail. Thèid logaichean dhan toradh àbhaisteach aig LOG_LEVEL, agus cuiridh Compose mun cuairt orra. Cha bhi dàta pearsanta anns na tracadh.

Trafaig a-mach roinneil (còmhnaidh dàta an EU)

Tha QUIRE_REGION=eu ag ràdh gu bheil an càrn a’ frithealadh bhuidhnean Aonaidh na h-Eòrpa. Cuiridh an neach-obrach liosta-cheadaichte an sàs air gach iarrtas a-mach a nithear airson buidheann a tha ceangailte ris an EU (21-compliance.md earrann 8.1). Tha an liosta nan aoighean a dh’ainmicheas seirbheisean rèitichte airson na roinne (puing-crìche stòraidh, solaraiche post-d, solaraiche bhidio aoigheachd, targaidean stòraidh na buidhne fhèin, solaraichean AI is cunntas post-d), aoighean seirbheis sam bith fo lagachadh gnìomhach, agus na h-aoighean a chuireas tu ann an QUIRE_EGRESS_ALLOW_HOSTS. Diùltar iarrtas gu aoigh poblach sam bith eile mus tèid a chur; thèid an diùltadh a sgrìobhadh ann an sreath sgrùdaidh na buidhne mar privacy/egress_refused, agus nochdaidh e fo Gèilleadh, Còmhnaidh dàta.

Chan eil liosta aoighean air buidhnean na RA no na SA; cumaidh iad na sgrùdaidhean roinn-seirbheise. Suidhich an liosta air an neach-obrach; leughaidh duilleag an rianaire i air an t-sreath-lìn gus an liosta cheadaichte a shealltainn, agus mar sin cuir ann an docker/.env i, a leughas gach seirbheis.

Bheir sgrùdadh na h-aplacaid mearachd shoilleir agus inntrigeadh sgrùdaidh, ach chan e am barantas a th’ ann: faodaidh còd a bhith ceàrr. ’S e an lìonra am barantas. Chan eil Compose ga chur an gnìomh dhut. Airson càrn roinneil, cuir na seirbheisean worker agus web air lìonra internal: true aig nach eil ach aon shlighe a-mach tro neach-ionaid egress (mar eisimpleir soitheach Squid no tinyproxy) a cheadaicheas na h-aon aoighean ri QUIRE_EGRESS_ALLOW_HOSTS agus aoighean nan seirbheisean rèitichte; suidhich HTTPS_PROXY dha na seirbheisean sin. Tha duilleag còmhnaidh a’ liostadh nan dearbh aoighean a tha ceadaichte leis an aplacaid, agus mar sin faodar an dà liosta a choimeas.

Slàinte

Tha docker compose -f docker/compose.yaml ps a’ sealltainn slàinte gach seirbheise.

TLS

Tha seirbheis proxy (Caddy, Apache-2.0, docker/caddy/Caddyfile) sa chàrn bhunaiteach. Freagraidh i air puirt 80 agus 443 agus stiùiridh i:

Bheir init-env.sh QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL agus IMGPROXY_URL às an dà thùs gus nach dealachadh iad. Deasaich iad còmhla ma dh’atharraicheas tu tùs le làimh.

Tha teisteanasan an urra ri QUIRE_PROXY_TLS:

• internal (bunaiteach): ùghdarras teisteanais Caddy fhèin, airson localhost, *.localhost agus lvh.me. Earb ris an fhreumh aige aon turas, agus an uair sin faigh an teisteanas:

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

  Cuir quire-local-ca.crt ri stòr teisteanasan earbsach an t-siostaim no a’ bhrabhsair. Gabhaidh curl ris le --cacert.

• Seòladh post-d: teisteanasan ACME fèin-obrachail (Let’s Encrypt agus an uair sin ZeroSSL) airson fìor ainmean-aoigheachd. Feumaidh DNS airson an dà thùs agus gach aoigh neach-gabhail comharrachadh an seo, agus feumaidh puirt 80 agus 443 ruigsinn bhon eadar-lìon.

Thèid aoighean luchd-gabhail a chruthachadh nuair a thadhlas cuideigin orra an toiseach agus dìreach ma dhearbhas web gum buin an t-ainm don stàladh seo (/tls-allowed, air iarraidh air lìonra Compose). Chan eil feum air teisteanas wildcard no plugan solaraiche DNS, agus chan urrainn do choigreach a chuireas ainm gu aoigh iarraidh air teisteanasan a chruthachadh. Tha teisteanasan agus an t-ùghdarras ionadail ann an leabhar caddy-data; dèan cùl-taic dheth leis a’ chòrr ma chleachdas tu internal.

Cha chreid Web ach X-Forwarded-For on neach-ionaid: tha seòladh stèidhichte aig an neach-ionaid (QUIRE_PROXY_ADDRESS, 172.29.64.10 mar bhun-roghainn) air fo-lìon stèidhichte (QUIRE_COMPOSE_SUBNET), agus ainmichidh QUIRE_TRUSTED_PROXY_CIDRS an seòladh sin. Ma tha am fo-lìon a’ bualadh ri lìonra air an aoigh, atharraich an dà roghainn agus ruith docker compose down mus ruith thu up.

Air cùl neach-ionaid cùil agad fhèin

Gus cothromaiche luchd no neach-ionaid a tha thu a’ ruith mar-thà a chleachdadh na àite, fàg proxy a-mach (docker compose up -d --scale proxy=0) agus cuir crìoch air TLS air beulaibh web (8080), content (8081), collab (1234, websocket) agus centrifugo (8000, websocket). Suidhich seòlaidhean poblach ann an QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN agus QUIRE_COLLAB_URL (wss://), agus raon sheòlaidhean an neach-ionaid ann an QUIRE_TRUSTED_PROXY_CIDRS.

Fuasgladh dhuilgheadasan

• Sguir init le “QUIRE_DATABASE_ID is not a UUID”: suidhich e le uuidgen.
• Bidh web ag ath-thòiseachadh le “did not start on compose”: tha an log a’ liostadh gach suidheachadh nach urrainn dha urram a thoirt dha agus dè chleachdas tu na àite.
• Chan eil atharrachadh facal-faire dreuchd ann an .env an dèidh a’ chiad tòiseachadh a’ dèanamh dad: ruithidh an sgriobt tòiseachaidh aon turas. Cleachd ALTER ROLE.
• Fàilligidh luchdachadh suas le mearachd sganaidh fhad ’s a tha CLAMAV_URL suidhichte: luchdaichidh ClamAV na soidhnichean a-nuas aig a’ chiad tòiseachadh, agus bheir seo beagan mhionaidean.