Uppsetning Quire með Docker Compose

Þetta er öll varan á einum hýsil: LMS-ið, bakgrunnsvinnan þess, rauntíma- og samvinnuritþjónusturnar, og hver valkvæm þjónusta bak við snið. Hönnunin er í docs/architecture/23-ops.md kafla 2.

Önnur markumhverfi: Vercel og Cloudflare Workers keyra aðeins vefþrepið. Uppfærslur eru í upgrade.md, og öryggisafrit og endurheimtaræfingin í backup-restore.md.

Hvað þú þarft

• Docker Engine 27 eða nýrri með Compose-viðbótinni 2.30 eða nýrri.
• 4 örgjörvakjarna og 8 GB af minni fyrir sjálfgefinn stakk; 8 kjarna og 16 GB með --profile full (ClamAV einn heldur um 1,5 GB af undirskriftum).
• DNS-nafn fyrir vefþrepið og annað fyrir ótreytt efni. Þau verða að vera ólík hýsilnöfn: SCORM-pakkar og upphlaðið HTML keyra á efnis- upprunanum svo þau geti aldrei lesið kökur LMS-ins.
• Fyrir staðbundið próf leysast lvh.me og *.localhost í 127.0.0.1, sem er það sem docker/.env.example notar. Eigin proxy-þjónusta stakkans þjónar báðum yfir https með staðbundnu útgefendastofnuninni, svo ekkert annað er sett upp (sjá „TLS“).
• Gáttir 80 og 443 lausar á hýsilnum (QUIRE_PROXY_HTTP_PORT og QUIRE_PROXY_HTTPS_PORT færa þær).

Fyrsta keyrsla

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 skrifar docker/.env frá docker/.env.example með öll leyndarmál mynduð (lykilorð gagnagrunns, undirritunar- og aðallyklar, efnisræsingarlyklaparið) og úttektareftirlits-undirritunarlykilinn í docker/secrets/audit-signing-key.pem, sem Compose tengir inn í vinnsluvélarnar sem leyndarmál. Það þarf aðeins sh, awk og openssl, og það neitar að skrifa yfir núverandi docker/.env. Afritaðu báðar skrár af hýsilnum: án QUIRE_MASTER_KEY getur endurheimtur gagnagrunnur ekki afdulritað geymd auðkenni sín. Til að fylla skrána með hendi í staðinn, cp docker/.env.example docker/.env; skráin segir hvernig á að mynda hvert leyndarmál.

Báðir upprunar verða að vera https: efnisþjónustan neitar látlausu http í framleiðslu, og þeir mega ekki deila skráanlegu léni. proxy- þjónustan endar TLS fyrir báða (sjá „TLS“); init-env.sh hafnar http://-uppruna.

Stakkinn ræsir í fastri röð, og hvert skref bíður eftir því fyrra:

1. postgres verður heilbrigður. Við allra fyrstu ræsingu stillir frumstillingarskriftan hans (docker/postgres/init/90-passwords.sh) lykilorð fjögurra hlutverka.
2. migrate beitir hverjum flutningi og ræsir verkbiðröðina í stjórngagnagrunninum og í hverjum sérstökum leigjendagagrunni, athugar að þeir séu allir sammála, hættir síðan (docs/ops/upgrade.md). Flutningar keyra við hverja ræsingu og eru samtaka, svo uppfærsla er ný mynd og endurræsing.
3. init (apps/web/src/first-run.ts) skráir forritsgagnagrunninn undir QUIRE_DATABASE_ID og, þegar QUIRE_SETUP_ADMIN_EMAIL er stillt, býr til fyrstu stofnunina og stjórnanda hennar. Innskráningarfangið og myndað lykilorð er prentað einu sinni, í docker compose logs init.
4. web, content, worker, scheduler, collab og centrifugo ræsa.
5. proxy ræsir þegar web og content eru heilbrigð.

Opnaðu https://demo. fylgt eftir með forritsléninu þínu (init-annállinn prentar nákvæmt innskráningarfang), og skráðu þig inn. Á staðbundinni uppsetningu skaltu fyrst treysta útgefendastofnun milliþjónsins (sjá „TLS“). Skiptu um myndaða lykilorðið á /account/security.

Ferli ræst án krafins leyndarmáls neitar að ræsa og nefnir vantarandi stillingu í annál sínum. Ekkert ræsir hálfstillt.

Þjónustur og snið

--profile full ræsir hverja valkvæma þjónustu nema backup og h5p. Ræstu eina með docker compose -f docker/compose.yaml --profile scan up -d. Án valkvæmrar þjónustu virkar Quire samt og segir hvað vantar: enginn skanni þýðir að upphlaðið er geymt óskannað og stjórnandanum er sagt; enginn Gotenberg þýðir að skrár bjóða niðurhal í stað forsýningar; enginn umkóðari þýðir að myndband spilast sem upprunalega skráin.

Hver þriðjaaðilamynd og leyfisskyldur hennar eru taldar í docker/third-party-containers.yaml.

Að tengja H5P-veitu

Quire fellir ekki inn né sendir H5P-keyrslutíma eða hliðarvagn (ADR 0019). Ef þú notar H5P skaltu leggja til eigin hýsta áskrift eða reka eigin sjálfhýsta H5P- tilvik aðskilið frá Quire. Skráðu þá veitu sem LTI 1.3 ytra tæki og bættu efni hennar við námskeið sem tækjaverkefni. Quire skiptir einkunnum og framvindu verkefna/einkunna í gegnum LTI Assignment and Grade Services (AGS). Ef veitan sendir einnig xAPI-yfirlýsingar skaltu stilla það aðskilið fyrir xAPI-yfirlýsingageymslu Quire; AGS einkunna-/framvinduskipti senda ekki xAPI- yfirlýsingar. Moodle-innflutningar melda H5P-verkefni sem þarfnast LTI-tækis- tengingar. Veitan ber áfram ábyrgð á H5P-keyrslutíma sínum, höfundun, efnisbanka og tilraunasögu.

Til að keyra eigið sjálfhýst tilvik á þessum hýsil skaltu stilla QUIRE_H5P_IMAGE á mynd þess og ræsa h5p-sniðið. Compose gefur það út á QUIRE_H5P_PORT (8090) og heldur gögnum þess í h5p-data bindinu; myndin, og skyldurnar sem fylgja henni, haldast þínar.

Stillingar

Hvert ferli les docker/.env. Sniðmátið, docker/.env.example, telur hverja stillingu með sjálfgefnu gildi. Hóparnir:

Vistföng

Leyndarmál

Haltu afriti af QUIRE_MASTER_KEY annars staðar en á þessum hýsil. Gagnagrunnur endurheimtur án hans getur ekki afdulritað auðkennin sem hann heldur.

Gagnagrunnur

Lykilorð hlutverka eru aðeins beitt þegar gagnagrunnsbindið er fyrst stofnað. Til að skipta um eitt síðar skaltu nota ALTER ROLE og uppfæra síðan samsvarandi slóð.

QUIRE_REPORT_DATABASE_URL er notað fyrir líkamlega gagnagrunninn sem stilltur er með DATABASE_URL. Fyrir hvern annan skráðan líkamlegan gagnagrunn skaltu stilla hans eigin quire_report tengislóð í vef- og vinnsluumhverfunum, settu síðan breytunafnið í reit gagnagrunnsins Skýrsluumhverfisbreyta sem env:NAME. Tilvísunin verður að benda á sama gagnagrunn og forrits- tenging hans, helst lesafrit hans. Hvert skýrsluyfirborð fylgir leigjandanum að skýrslutengingu eigin gagnagrunns: skýrslusmiðurinn og vistaðar skýrslur, tímasettar afhendingar, skýrsluútflutningar, greiningar, úttektar- annállinn, REST-úttektartilföngin og úttektarleit aðstoðarfulltrúans. Ekkert þeirra lánar nokkurn tíma skýrsluslóð annars gagnagrunns. Þegar gagnagrunnur hefur enga skýrslutengingu keyra venjulegar skýrslur á forritstengingu þess gagnagrunns, meðan greiningar og hver úttektarlestur neita og segja það, því forritshlutverkið getur ekki lesið úttektarslóðina.

Reklar

Rekilsgildi sem þessi útgáfa hefur ekki er hafnað þegar vefþrepið ræsir, með stillinguna nefnda, frekar en að vera þegjandi skipt út fyrir sjálfgefið.

Myndir

Síður biðja um myndir í fjórum föstum stærðum í gegnum /api/files/{id}/image/{size}, sem athugar sama aðgang og skráin sjálf og vísar síðan áfram á myndþjónustuna. Hver stofnun má biðja um QUIRE_IMAGE_SPECS_PER_HOUR (sjálfgefið 2000) ný mynd- og stærðarpör á klukkutíma; stærðir þegar framleiddar þann tíma telja ekki. Notaðu valkey eða postgres fyrir QUIRE_CACHE_DRIVER með fleiri en einum vefgámi, svo mörkin haldi þvert á þá.

Cloudflare Images heldur eigin afriti af hverju frumriti sem það þjónar. Þegar skrá er eytt eyðir vinnsluvélin því afriti á undan frumritinu.

Biðröð

Bakgrunnsverk nota pg-boss í sama Postgres-gagnagrunni, svo engin biðraðaþjónusta er til að keyra og ekkert til að stilla. Verk eru sett í biðröð í sama viðskipti og breytingin sem olli þeim, svo hrun getur hvorki týnt einu né sent eitt tvisvar. QUIRE_QUEUE_DRIVER er pgboss hér, sjálfgefið þess; vercel og cloudflare færa aðeins léttu tilkynninga- og vefkrókasendingarnar í eigin biðröð vettvangsins, og Vercel- og Cloudflare-leiðbeiningarnar lýsa þeim og hvernig vefþrep þeirra setja í biðröð.

Tölvupóstur

Stilltu annaðhvort:

• QUIRE_EMAIL_PROVIDER_CONFIG: JSON-hlut sem nefnir HTTP-veitu og auðkenni hennar, svo sem {"provider":"postmark","token":"..."}. Postmark, Amazon SES, Mailgun, SendGrid og Resend eru studd.
• QUIRE_SMTP_URL: smtp://user:password@host:587. Aðeins þetta markumhverfi; þjónustulausu markumhverfin loka á SMTP.

QUIRE_MAIL_FROM er sendandinn. Til að prófa Quire skaltu ræsa devmail- sniðið, stilla QUIRE_SMTP_URL=smtp://mailpit:1025, og lesa póst á http://localhost:8025.

Valkvæmar þjónustur

Sýnileiki

OTEL_EXPORTER_OTLP_ENDPOINT nefnir söfnunartækið sem hvert ferli sendir spor og mæligildi til; með observability-sniðinu er það http://otelcol:4318, og docker/otel-collector.yaml er þar sem þú bætir við útflytjandanum fyrir bakendann þinn. Vefþrepið, vinnsluvélin, stýringin, efni og samvinna flytja út spönn yfir OTLP/HTTP (vefbeiðnir, leigjendagagnagrunns- viðskipti, vinnsluverk og útfararköll) þegar það er stillt, og mæligildi til sama endapunkts á mínútu (OTEL_METRICS_EXPORTER=none slekkur á þeim). OTEL_TRACES_SAMPLER_ARG stillir hlutfall spora sem haldið er. Annálar fara á staðal- úttak við LOG_LEVEL, og Compose snýr þeim. Spor bera aldrei persónugreinanleg gögn.

Svæðisbundinn útfari (EU-gagnavarsla)

QUIRE_REGION=eu segir að stakkinn þjóni stofnunum Evrópusambandsins. Vinnsluvélin heldur þá hverri útfarabeiðni gerðri fyrir stofnun festri við ESB við leyfilista (21-compliance.md kafli 8.1). Leyfilistinn er hýslarnir sem stilltu þjónusturnar lýsa yfir fyrir svæðið (geymslu- endapunkturinn, tölvupóstveitan, hýst myndbandsveita, eigin geymslumark stofnunarinnar, gervigreindarveitur og tölvupóstreikningur), hýslar hverrar þjónustu undir virkri undanþágu, og hýslarnir sem þú telur í QUIRE_EGRESS_ALLOW_HOSTS. Beiðni til annars opinbers hýsils er hafnað áður en hún er send, höfnunin er skrifuð í úttektarslóð stofnunarinnar sem privacy/egress_refused, og hún er talin undir Samræmi, Gagnavarsla.

Breskar og bandarískar stofnanir eru ekki haldnar við hýsilista; þær halda svæðis- athugunum þjónustunnar. Stilltu listann á vinnsluvélinni; stjórnsíðan les hann á vefnum þrepinu til að sýna leyfilistann, svo settu hann í docker/.env, sem hver þjónusta les.

Forritsathugunin gefur skýra villu og úttektarfærslu, og hún er ekki ábyrgðin: kóði getur verið rangur. Ábyrgðin er netið. Compose framfylgir því ekki fyrir þig. Fyrir svæðisstakk skaltu setja worker- og web- þjónusturnar á internal: true neti þar sem eina leiðin út er útfara- milliþjónn (til dæmis Squid- eða tinyproxy-gámur) sem leyfir sömu hýsla og QUIRE_EGRESS_ALLOW_HOSTS auk hýsla stilltra þjónustu þinna, og stilltu HTTPS_PROXY fyrir þær þjónustur. Varslusíðan telur upp nákvæmlega hýslana sem forritið leyfir, svo hægt er að bera listana tvo saman.

Heilsa

docker compose -f docker/compose.yaml ps sýnir heilsu hverrar þjónustu.

TLS

proxy-þjónustan (Caddy, Apache-2.0, docker/caddy/Caddyfile) er hluti af sjálfgefna stakknum. Hún svarar á gáttum 80 og 443 og beinir:

init-env.sh leiðir QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL og IMGPROXY_URL frá upprununum tveimur, svo þeir geti ekki rekið í sundur. Breyttu þeim saman ef þú breytir uppruna með hendi.

Skírteini fylgja QUIRE_PROXY_TLS:

• internal (sjálfgefið): Eigin útgefendastofnun Caddy, fyrir localhost, *.localhost og lvh.me. Treystu rótinni einu sinni, skoðaðu síðan:

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

  Bættu quire-local-ca.crt við traustbúð kerfisins eða vafrans. curl tekur hana með --cacert.

• Netfang: sjálfvirk ACME-skírteini (Let’s Encrypt, síðan ZeroSSL) fyrir raunveruleg hýsilnöfn. DNS fyrir báða uppruna og hvern leigjendahýsil verður að benda hingað, og gáttir 80 og 443 verða að vera náanlegar af internetinu.

Leigjendahýslar eru gefnir út við þörf, við fyrstu heimsókn, og aðeins þegar vefur staðfestir að nafnið tilheyri þessari uppsetningu (/tls-allowed, spurt á Compose-netinu). Engin joktatáknsskírteini eða DNS-veituviðbót er þörf, og ókunnugur sem bendir nafni á hýsilinn getur ekki látið hann biðja um skírteini. Skírteini og staðbundna stofnunin lifa í caddy-data bindinu; taktu öryggisafrit af því með hinu ef þú notar internal.

Vefur trúir X-Forwarded-For frá milliþjóninum einum: milliþjónninn hefur fast fang (QUIRE_PROXY_ADDRESS, sjálfgefið 172.29.64.10) á föstu undirneti (QUIRE_COMPOSE_SUBNET), og QUIRE_TRUSTED_PROXY_CIDRS nefnir það fang. Ef undirnetið rekst á net á hýsilnum skaltu breyta báðum og keyra docker compose down fyrir up.

Bak við eiginn öfugan milliþjón

Til að nota álagsdreifara eða milliþjón sem þú þegar rekur í staðinn skaltu sleppa proxy (docker compose up -d --scale proxy=0) og enda TLS framan við web (8080), content (8081), collab (1234, vefstokkur) og centrifugo (8000, vefstokkur). Stilltu opinberu föngin í QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN og QUIRE_COLLAB_URL (wss://), og vistfangssvið milliþjóns þíns í QUIRE_TRUSTED_PROXY_CIDRS.

Úrræðaleit

• init hættir með „QUIRE_DATABASE_ID is not a UUID“: stilltu það með uuidgen.
• web endurræsir með „did not start on compose“: annállinn telur upp hverja stillingu sem hann getur ekki virt og hvað á að nota í staðinn.
• Breyting á hlutverkslykilorði í .env eftir fyrstu ræsingu gerir ekkert: frumstillingar- skriftan keyrir einu sinni. Notaðu ALTER ROLE.
• Upphlöð bilar með skönnunarvillu meðan CLAMAV_URL er stillt: ClamAV sækir undirskriftir sínar við fyrstu ræsingu, sem tekur nokkrar mínútur.