Quire a shuiteáil le Docker Compose

Seo an táirge iomlán ar óstach amháin: an LMS, a chuid oibre cúlra, na seirbhísí fíor-ama agus eagarthóireachta comhoibríche, agus gach seirbhís roghnach atá taobh thiar de phróifíl. Is in alt 2 de docs/architecture/23-ops.md atá an dearadh.

Spriocanna eile: ní ritheann Vercel ná Cloudflare Workers ach an tsraith ghréasáin. Tá uasghráduithe in upgrade.md, agus cúltacaí agus an cleachtadh athchóirithe in backup-restore.md.

Na rudaí atá de dhíth

• Docker Engine 27 nó níos déanaí leis an mbreiseán Compose 2.30 nó níos déanaí.
• 4 chroí LAP agus 8 GB cuimhne don chruach réamhshocraithe; 8 gcroí agus 16 GB le --profile full (coinníonn ClamAV féin tuairim is 1.5 GB de shínithe).
• Ainm DNS don tsraith ghréasáin agus ainm eile d’ábhar neamhiontaofa. Caithfidh siad a bheith ina n-óstach éagsúla: ritheann pacáistí SCORM agus HTML uaslódáilte ar bhunús an ábhair ionas nach mbeidh siad in ann fianáin an LMS a léamh choíche.
• Le haghaidh tástáil áitiúil, réitíonn lvh.me agus *.localhost go 127.0.0.1, agus sin a úsáideann docker/.env.example. Freastalaíonn seirbhís proxy na cruaiche féin ar an dá cheann thar https le húdarás deimhnithe áitiúil, mar sin ní gá aon rud eile a shuiteáil (féach “TLS”).
• Caithfidh calafoirt 80 agus 443 a bheith saor ar an óstach (QUIRE_PROXY_HTTP_PORT agus QUIRE_PROXY_HTTPS_PORT chun iad a bhogadh).

An chéad rith

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

Scríobhann docker/scripts/init-env.sh docker/.env ó docker/.env.example, agus gineann sé gach rún (pasfhocail bhunachair sonraí, na heochracha sínithe agus máistir, péire eochracha seolta an ábhair) chomh maith leis an eochair shínithe sheicphointe iniúchta in docker/secrets/audit-signing-key.pem, a fheistíonn Compose sna próiseálaithe mar rún. Níl de dhíth air ach sh, awk agus openssl, agus diúltaíonn sé comhad docker/.env atá ann cheana a fhorscríobh. Cóipeáil an dá chomhad amach ón óstach: gan QUIRE_MASTER_KEY, ní féidir le bunachar sonraí athchóirithe dintiúir stóráilte a dhíchriptiú. Chun an comhad a líonadh de láimh ina ionad sin, úsáid cp docker/.env.example docker/.env; deir an comhad conas gach rún a ghiniúint.

Caithfidh an dá bhunús a bheith https: diúltaíonn an tseirbhís ábhair do ghnáth-http sa táirgeadh, agus ní ceadmhach dóibh fearann inchláraithe a roinnt. Críochnaíonn an tseirbhís proxy TLS don dá cheann (féach “TLS”); diúltaíonn init-env.sh do bhunús http://.

Tosaíonn an chruach in ord socraithe, agus fanann gach céim ar an gceann roimpi:

1. Éiríonn postgres sláintiúil. Ar an gcéad tosú riamh, socraíonn a script tionscanta (docker/postgres/init/90-passwords.sh) pasfhocail na gceithre ról.
2. Cuireann migrate gach aistriú i bhfeidhm agus tionscnaíonn sé scuaine na jabanna sa bhunachar rialaithe agus i ngach bunachar tionónta tiomnaithe, seiceálann sé go bhfuil siad ar fad ag teacht le chéile, agus críochnaíonn sé ansin (docs/ops/upgrade.md). Ritheann aistrithe ag gach tosú agus tá siad saor ó dhúbailt, mar sin ní gá ach íomhá nua agus atosú chun uasghrádú a dhéanamh.
3. Taifeadann init (apps/web/src/first-run.ts) bunachar sonraí an fheidhmchláir faoi QUIRE_DATABASE_ID agus, má tá QUIRE_SETUP_ADMIN_EMAIL socraithe, cruthaíonn sé an chéad eagraíocht agus a riarthóir. Priontáiltear seoladh sínithe isteach agus pasfhocal ginte uair amháin in docker compose logs init.
4. Tosaíonn web, content, worker, scheduler, collab agus centrifugo.
5. Tosaíonn proxy nuair atá web agus content sláintiúil.

Oscail https://demo. agus fearann d’fheidhmchláir ina dhiaidh (priontálann log init an seoladh cruinn sínithe isteach), agus sínigh isteach. Ar shuiteáil áitiúil, cuir muinín in údarás deimhnithe an seachfhreastalaí ar dtús (féach “TLS”). Athraigh an pasfhocal ginte ag /account/security.

Diúltaíonn próiseas a thosaítear gan rún riachtanach tosú agus ainmníonn sé an socrú atá ar iarraidh ina log. Ní thosaíonn tada leathchumraithe.

Seirbhísí agus próifílí

Tosaíonn --profile full gach seirbhís roghnach seachas backup agus h5p. Tosaigh ceann acu le docker compose -f docker/compose.yaml --profile scan up -d. Oibríonn Quire fós gan seirbhís roghnach agus insíonn sé cad atá ar iarraidh: gan scanóir, stóráiltear uaslódálacha gan scanadh agus cuirtear an riarthóir ar an eolas; gan Gotenberg, is féidir comhaid a íoslódáil in áit réamhamharc a fháil; gan traschódóir, seinntear físeán mar an comhad bunaidh.

Liostaítear gach íomhá tríú páirtí agus a ceanglais cheadúnais in docker/third-party-containers.yaml.

Soláthraí H5P a cheangal

Ní leabaíonn ná ní sheachadann Quire rith-am H5P ná seirbhíseach coimhdeach (ADR 0019). Má úsáideann tú H5P, tabhair do shíntiús óstáilte féin nó oibrigh cás H5P féinoibrithe ar leithligh ó Quire. Cláraigh an soláthraí sin mar uirlis sheachtrach LTI 1.3 agus cuir a ábhar le cúrsaí mar ghníomhaíochtaí uirlise. Malartaíonn Quire gráid agus dul chun cinn gníomhaíochta/grádaithe trí LTI Assignment and Grade Services (AGS). Má sheolann an soláthraí ráitis xAPI freisin, cumraigh é sin ar leithligh do stór ráiteas xAPI Quire; ní sheolann malartú gráid/dul chun cinn AGS ráitis xAPI. Tuairiscítear in iompórtálacha Moodle go dteastaíonn ceangal le huirlis LTI ó ghníomhaíochtaí H5P. Is ar an soláthraí atá freagracht as rith-am H5P, údarú, banc ábhair agus stair iarrachtaí.

Chun do chás féinoibrithe féin a rith ar an óstach seo, socraigh QUIRE_H5P_IMAGE dá íomhá agus tosaigh próifíl h5p. Foilsíonn Compose é ar QUIRE_H5P_PORT (8090) agus coinníonn sé na sonraí san imleabhar h5p-data; is leatsa an íomhá agus na hoibleagáidí a ghabhann léi.

Socruithe

Léann gach próiseas docker/.env. Liostaíonn an teimpléad, docker/.env.example, gach socrú agus a réamhshocrú. Seo na grúpaí:

Seoltaí

Rúin

Coinnigh cóip de QUIRE_MASTER_KEY in áit eile seachas an t-óstach seo. Ní féidir le bunachar sonraí athchóirithe gan í na dintiúir atá ann a dhíchriptiú.

Bunachar sonraí

Ní chuirtear pasfhocail róil i bhfeidhm ach nuair a chruthaítear imleabhar an bhunachair sonraí den chéad uair. Chun ceann a athrú níos déanaí, úsáid ALTER ROLE agus ansin nuashonraigh an URL meaitseála.

Úsáidtear QUIRE_REPORT_DATABASE_URL don bhunachar sonraí fisiciúil atá cumraithe le DATABASE_URL. I gcás bunachair fhisiciúla chláraithe eile, socraigh URL ceangail quire_report féin i dtimpeallachtaí web agus worker, agus cuir ainm na hathróige sa réimse Athróg timpeallachta tuairiscithe mar env:NAME. Ba cheart don tagairt an bunachar céanna lena cheangal feidhmchláir a ainmniú, macasamhail léite amháin más féidir. Leanann gach dromchla tuairiscithe an tionónta chuig ceangal tuairiscithe a bhunachair féin: an tógálaí tuarascálacha agus tuarascálacha sábháilte, seachadtaí sceidealaithe, easpórtálacha tuarascálacha, anailísíocht, log iniúchta, acmhainní iniúchta REST agus cuardach iniúchta an chúntóra. Ní fhaigheann aon cheann acu URL tuairiscithe ó bhunachar eile ar iasacht. Mura bhfuil ceangal tuairiscithe ag bunachar, ritheann tuarascálacha coitianta lena cheangal feidhmchláir féin, ach diúltaíonn anailísíocht agus gach léamh iniúchta agus míníonn siad sin, mar ní féidir leis an ról feidhmchláir lorg iniúchta a léamh.

Tiománaithe

Diúltaítear do luach tiománaí nach bhfuil san áireamh sa leagan seo nuair a thosaíonn an tsraith ghréasáin. Ainmnítear an socrú in áit luach réamhshocraithe a chur ina ionad gan fógra.

Íomhánna

Iarrann leathanaigh íomhánna ar cheithre mhéid sheasta trí /api/files/{id}/image/{size}, a sheiceálann an rochtain chéanna leis an gcomhad féin agus a atreoraíonn ansin chuig seirbhís na n-íomhánna. Féadfaidh gach eagraíocht QUIRE_IMAGE_SPECS_PER_HOUR (2000 de réir réamhshocraithe) péire nua íomhá agus méid a iarraidh in aghaidh na huaire; ní áirítear méideanna a cruthaíodh cheana san uair sin. Má tá níos mó ná coimeádán gréasáin amháin agat, úsáid valkey nó postgres mar QUIRE_CACHE_DRIVER ionas go mbeidh an teorainn i bhfeidhm trasna gach coimeádáin.

Coinníonn Cloudflare Images a chóip féin de gach bunleagan a bhfreastalaíonn sé air. Nuair a scriostar comhad, scriosann an próiseálaí an chóip sin roimh an mbunleagan.

Scuaine

Úsáideann jabanna cúlra pg-boss sa bhunachar Postgres céanna, mar sin ní gá seirbhís scuaine a rith ná rud ar bith a chumrú. Cuirtear jabanna sa scuaine san idirbheart céanna leis an athrú ba chúis leo, mar sin ní féidir le tuairt ceann a chailleadh ná ceann a sheoladh faoi dhó. Is é réamhshocrú QUIRE_QUEUE_DRIVER ná pgboss anseo; aistríonn vercel agus cloudflare seachadtaí éadroma fógraí agus webhook chuig scuaine an ardáin féin amháin. Míníonn treoracha Vercel agus Cloudflare iad sin agus an chaoi a gcuireann a sraitheanna gréasáin jabanna sa scuaine.

Ríomhphost

Socraigh ceann díobh seo:

• QUIRE_EMAIL_PROVIDER_CONFIG: réad JSON ina n-ainmnítear soláthraí HTTP agus a dhintiúir, mar shampla {"provider":"postmark","token":"..."}. Tacaítear le Postmark, Amazon SES, Mailgun, SendGrid agus Resend.
• QUIRE_SMTP_URL: smtp://user:password@host:587. An sprioc seo amháin; cuireann spriocanna gan fhreastalaí bac ar SMTP.

Is é QUIRE_MAIL_FROM an seoltóir. Chun Quire a thriail, tosaigh próifíl devmail, socraigh QUIRE_SMTP_URL=smtp://mailpit:1025, agus léigh an ríomhphost ag http://localhost:8025.

Seirbhísí roghnacha

Inbhraiteacht

Is é OTEL_EXPORTER_OTLP_ENDPOINT ainm an bhailitheora a sheolann gach próiseas rianta agus méadrachtaí chuige; leis an bpróifíl observability, is é http://otelcol:4318 é, agus is in docker/otel-collector.yaml a chuirtear onnmhaireoir do do chóras cúil leis. Onnmhairíonn próisis web, worker, scheduler, content agus collab réisí thar OTLP/HTTP (iarratais ghréasáin, idirbhearta bunachair thionónta, jabanna próiseálaí agus glaonna amach) nuair atá sé socraithe, agus méadrachtaí chuig an gcríochphointe céanna gach nóiméad (OTEL_METRICS_EXPORTER=none chun iad a mhúchadh). Socraíonn OTEL_TRACES_SAMPLER_ARG an cion rianta a choinnítear. Téann loganna chuig gnáth-aschur ag LOG_LEVEL, agus rothlaíonn Compose iad. Ní bhíonn sonraí pearsanta sna rianta choíche.

Sreabhadh amach réigiúnach (cónaitheacht sonraí AE)

Léiríonn QUIRE_REGION=eu go bhfreastalaíonn an chruach ar eagraíochtaí san Aontas Eorpach. Cuireann an próiseálaí gach iarratas amach thar liosta ceadaithe nuair a dhéantar é d’eagraíocht atá ceangailte den AE (21-compliance.md alt 8.1). Is ionann an liosta ceadaithe agus óstáin na seirbhísí cumraithe a dhearbhaíonn don réigiún (críochphointe stórála, soláthraí ríomhphoist, soláthraí físeáin óstáilte, spriocanna stórála eagraíochta, soláthraithe AI agus cuntas ríomhphoist), óstáin aon seirbhíse atá faoi mhaolú gníomhach, agus na hóstáin atá liostaithe agat in QUIRE_EGRESS_ALLOW_HOSTS. Diúltaítear d’iarratas chuig aon óstach poiblí eile sula seoltar é; scríobhtar an diúltú chuig lorg iniúchta na heagraíochta mar privacy/egress_refused, agus liostaítear é faoi Comhlíonadh, Cónaitheacht sonraí.

Ní chuirtear eagraíochtaí sa Ríocht Aontaithe ná sna Stáit Aontaithe faoi liosta óstach; coinníonn siad na seiceálacha ar réigiún seirbhíse. Socraigh an liosta ar an bpróiseálaí; léann leathanach an riarthóra ar an tsraith ghréasáin é chun an liosta ceadaithe a thaispeáint, mar sin cuir in docker/.env é, a léann gach seirbhís.

Tugann seiceáil an fheidhmchláir earráid shoiléir agus iontráil iniúchta, ach ní hí an ráthaíocht í: d’fhéadfadh cód a bheith mícheart. Is ag an líonra atá an ráthaíocht. Ní chuireann Compose i bhfeidhm í duit. I gcás cruach réigiúnach, cuir na seirbhísí worker agus web ar líonra internal: true nach bhfuil ach seachfhreastalaí sreafa amach amháin ina bhealach amach (Squid nó coimeádán beag tinyproxy, mar shampla); lig don seachfhreastalaí na hóstáin chéanna le QUIRE_EGRESS_ALLOW_HOSTS agus óstáin na seirbhísí cumraithe, agus socraigh HTTPS_PROXY do na seirbhísí sin. Liostaítear na hóstáin chruinne a cheadaíonn an feidhmchlár ar leathanach na cónaitheachta ionas gur féidir an dá liosta a chur i gcomparáid.

Sláinte

Taispeánann docker compose -f docker/compose.yaml ps stádas sláinte gach seirbhíse.

TLS

Tá seirbhís proxy (Caddy, Apache-2.0, docker/caddy/Caddyfile) sa chruach réamhshocraithe. Freagraíonn sí ar chalafoirt 80 agus 443 agus rianaíonn sí:

Díorthaíonn init-env.sh QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL agus IMGPROXY_URL ón dá bhunús, ionas nach n-imíonn siad ó chéile. Cuir in eagar le chéile iad má athraíonn tú bunús de láimh.

Leanann teastais QUIRE_PROXY_TLS:

• internal (an réamhshocrú): údarás teastais Caddy féin, do localhost, *.localhost agus lvh.me. Cuir muinín ina fhréamh uair amháin, ansin brabhsáil:

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

  Cuir quire-local-ca.crt le stór iontaoibhe an chórais nó an bhrabhsálaí. Glacann curl leis trí --cacert.

• Seoladh ríomhphoist: deimhnithe ACME uathoibríocha (Let’s Encrypt, ansin ZeroSSL) d’fhíorainmneacha óstach. Caithfidh DNS don dá bhunús agus do gach óstach tionónta díriú anseo, agus caithfidh calafoirt 80 agus 443 a bheith inrochtana ón idirlíon.

Eisítear óstáin tionónta ar éileamh, ar an gcéad chuairt, agus nuair a dheimhníonn web gur leis an suiteáil seo an t-ainm (/tls-allowed, a iarrtar ar líonra Compose). Níl teastas saoróg ná breiseán soláthraí DNS de dhíth, agus ní féidir le strainséir a dhíríonn ainm ar an óstach iallach a chur ar theastais a iarraidh. Tá teastais agus an t-údarás áitiúil san imleabhar caddy-data; déan cúltaca de in éineacht leis an gcuid eile má úsáideann tú internal.

Creideann web X-Forwarded-For ón seachfhreastalaí amháin: tá seoladh seasta (QUIRE_PROXY_ADDRESS, 172.29.64.10 de réir réamhshocraithe) ag an seachfhreastalaí ar fholíon seasta (QUIRE_COMPOSE_SUBNET), agus ainmníonn QUIRE_TRUSTED_PROXY_CIDRS an seoladh sin. Má thagann an folíon salach ar líonra ar an óstach, athraigh an dá cheann agus rith docker compose down roimh up.

Taobh thiar de do sheachfhreastalaí droim ar ais féin

Chun cothromóir ualaigh nó seachfhreastalaí atá á rith agat cheana a úsáid, fág proxy ar lár (docker compose up -d --scale proxy=0) agus críochnaigh TLS os comhair web (8080), content (8081), collab (1234, soicéad gréasáin) agus centrifugo (8000, soicéad gréasáin). Socraigh seoltaí poiblí in QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN agus QUIRE_COLLAB_URL (wss://), agus raon seoltaí do sheachfhreastalaí in QUIRE_TRUSTED_PROXY_CIDRS.

Fabhtcheartú

• Críochnaíonn init le “QUIRE_DATABASE_ID is not a UUID”: socraigh é le uuidgen.
• Atosaíonn web leis an teachtaireacht “did not start on compose”: liostaíonn an log gach socrú nach féidir leis a chomhlíonadh agus luach le húsáid ina ionad.
• Ní dhéanann athrú ar phasfhocal róil in .env tar éis an chéad tosaithe dada: ní ritheann an script tionscanta ach uair amháin. Úsáid ALTER ROLE.
• Teipeann uaslódálacha le hearráid scanadh agus CLAMAV_URL socraithe: íoslódálann ClamAV a shínithe ar an gcéad tosú, agus tógann sé sin cúpla nóiméad.