Quire'i paigaldamine Docker Compose'iga

See on täisfunktsionaalne toode ühes hostis: õppehaldussüsteem, selle taustatööd, reaalaja- ja ühise muutmise teenused ning kõik profiili taga olevad valikulised teenused. Arhitektuur on dokumendi docs/architecture/23-ops.md jaotises 2.

Muud sihtkohad: Vercel ja Cloudflare Workers käitavad ainult veebikihti. Uuendused on juhendis upgrade.md, varundamine ja taastamise proov aga juhendis backup-restore.md.

Vajalikud eeldused

• Docker Engine 27 või uuem koos Compose’i pistikprogrammiga 2.30 või uuem.
• Vaikimisi virna jaoks 4 protsessorituuma ja 8 GB mälu; --profile full korral 8 tuuma ja 16 GB (ainuüksi ClamAV hoiab umbes 1,5 GB signatuure).
• Veebikihile DNS-nimi ja usaldamatu sisu jaoks teine nimi. Need peavad olema eri hostid: SCORM-paketid ja üleslaaditud HTML töötavad sisu päritolus, et nad ei saaks kunagi lugeda õppehaldussüsteemi küpsiseid.
• Kohalikuks katseks lahenduvad lvh.me ja *.localhost aadressiks 127.0.0.1, mida kasutab docker/.env.example. Virna proxy-teenus serveerib mõlemat HTTPS-i kaudu kohaliku sertimiskeskusega, nii et midagi muud pole vaja paigaldada (vt „TLS”).
• Hostis peavad olema vabad pordid 80 ja 443; neid saab muuta seadetega QUIRE_PROXY_HTTP_PORT ja QUIRE_PROXY_HTTPS_PORT.

Esmakäivitus

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 loob faili docker/.env failist docker/.env.example, genereerides kõik saladused (andmebaasi paroolid, allkirjastamis- ja peavõtmed ning sisu käivitamise võtmed) ning auditi kontrollpunkti allkirjastamisvõtme failis docker/secrets/audit-signing-key.pem. Compose ühendab selle töötlejatele saladusena. Skript vajab ainult sh, awk ja openssl-i ning keeldub olemasolevat docker/.env-i üle kirjutamast. Kopeeri mõlemad failid hostist välja: QUIRE_MASTER_KEY-ta taastatud andmebaas ei saa salvestatud mandaate dekrüptida. Faili võib täita ka käsitsi, kopeerides cp docker/.env.example docker/.env; mall kirjeldab iga saladuse genereerimist.

Mõlemad päritolud peavad olema https: tootmiskeskkonnas keeldub sisuteenus lihtsast HTTP-st ning neil ei tohi olla sama registreeritavat domeeni. proxy teenus lõpetab mõlema TLS-i (vt „TLS”); init-env.sh keeldub http:// aadressist.

Virn käivitub kindlas järjekorras ning iga samm ootab eelmist:

1. postgres muutub terveks. Esmakäivitusel määrab selle algskript (docker/postgres/init/90-passwords.sh) nelja rolli paroolid.
2. migrate rakendab kõik migratsioonid ja algseadistab tööjärjekorra juhtandmebaasis ning igas eriandmebaasiga rentniku andmebaasis; see kontrollib, et need ühtivad, ja väljub (docs/ops/upgrade.md). Migratsioonid käivituvad igal korral ning on korduskindlad, seega on uuendus uus kujutis ja taaskäivitus.
3. init (apps/web/src/first-run.ts) registreerib rakenduse andmebaasi QUIRE_DATABASE_ID all ning loob muutuja QUIRE_SETUP_ADMIN_EMAIL määramisel esimese organisatsiooni ja selle halduri. Sisselogimisaadress ja genereeritud parool trükitakse ühe korra docker compose logs init väljundisse.
4. Käivituvad web, content, worker, scheduler, collab ja centrifugo.
5. proxy käivitub pärast seda, kui web ja content on terved.

Ava https://demo. koos rakenduse domeeniga (täpse sisselogimisaadressi leiab init-logist) ja logi sisse. Kohalikus paigaldises usalda esmalt puhverserveri sertimiskeskust (vt „TLS”). Muuda genereeritud parool aadressil /account/security.

Nõutava saladuseta protsess keeldub käivitumast ja nimetab logis puuduva seade. Miski ei käivitu pooliku seadistusega.

Teenused ja profiilid

--profile full käivitab kõik valikulised teenused peale backupi ja h5p. Käivita üks profiil näiteks käsuga docker compose -f docker/compose.yaml --profile scan up -d. Ilma valikulise teenuseta töötab Quire edasi ja selgitab, mis puudu: skannerita salvestatakse üleslaadimised kontrollimata ning haldurit teavitatakse; Gotenbergita pakutakse eelvaate asemel allalaadimist; videokodeerijata esitatakse algne fail.

Kolmanda osapoole kujutised ja nendega seotud litsentsikohustused on loetletud failis docker/third-party-containers.yaml.

H5P pakkuja ühendamine

Quire ei lisa ega tarni H5P käituskeskkonda ega kõrvalprotsessi (ADR 0019). H5P kasutamiseks hangi majutatud tellimus või käita enda H5P eksemplari Quire’ist eraldi. Registreeri pakkuja välise LTI 1.3 tööriistana ja lisa selle sisu kursusele tööriistategevusena. Quire vahetab hindeid ning tegevuse ja hindamise edenemist LTI Assignment and Grade Servicesi (AGS) kaudu. Kui pakkuja saadab ka xAPI-lauseid, seadista need Quire’i xAPI lausete salvesti jaoks eraldi; AGS-i hinde- ja edenemisvahetus xAPI-lauseid ei saada. Moodle’i impordiaruanded märgivad H5P-tegevused LTI-tööriista ühendust vajavaks. Pakkuja vastutab enda H5P käituskeskkonna, sisu loomise, sisupanga ja katsete ajaloo eest.

Oma hostis paikneva eksemplari käivitamiseks määra QUIRE_H5P_IMAGE selle kujutiseks ja käivita h5p-profiil. Compose avaldab selle pordil QUIRE_H5P_PORT (8090) ja säilitab andmeid köites h5p-data; kujutis ning sellega kaasnevad kohustused jäävad sinu vastutusele.

Seaded

Iga protsess loeb faili docker/.env. Mall docker/.env.example loetleb iga seade koos vaikeväärtusega. Rühmad:

Aadressid

Saladused

Hoia QUIRE_MASTER_KEY-i koopiat hostist eemal. Ilma selleta taastatud andmebaas ei suuda selles hoitavaid mandaate dekrüptida.

Andmebaas

Rollide paroolid rakendatakse ainult andmebaasiköite loomisel. Hiljem ühe muutmiseks kasuta ALTER ROLE-i ja uuenda vastavat URL-i.

QUIRE_REPORT_DATABASE_URL on füüsilise andmebaasi jaoks, mille määrab DATABASE_URL. Iga muu registreeritud füüsilise andmebaasi jaoks määra oma quire_report ühenduse URL nii veebirakenduse kui ka töötleja keskkonnas ning registreeri selle andmebaasi väljal Reporting environment variable muutuja nimi kujul env:NAME. Viide peab osutama samale andmebaasile kui rakenduse ühendus, soovitatavalt selle lugemiskoopiale. Iga aruandepind kasutab rentniku enda andmebaasi aruandeühendust: aruandelooja ja salvestatud aruanded, ajastatud edastused, aruannete eksport, analüütika, auditilogi, REST-i auditite ressursid ning assistendi auditiotsing. Ükski neist ei laena teise andmebaasi aruande-URL-i. Kui andmebaasil aruandeühendust pole, käitatakse tavapärased aruanded selle enda rakendusühenduses; analüütika ja auditi lugemine aga keelduvad, sest rakenduseroll ei saa auditijälge lugeda.

Draiverid

Selles väljalaskes mittesisalduv draiver lükatakse veebikihi käivitamisel tagasi ning seade nimetatakse, mitte ei asendata vaikimisi väärtusega.

Pildid

Lehed küsivad pilte neljas kindlas suuruses marsruudi kaudu /api/files/{id}/image/{size}, mis kontrollib faili ligipääsu ning suunab seejärel pildivõrku. Iga organisatsioon võib küsida QUIRE_IMAGE_SPECS_PER_HOUR (vaikimisi 2000) uut pildi ja suuruse paari tunnis; samal tunnil juba loodud suuruseid selle hulka ei loeta. Kui veebikonteinereid on mitu, kasuta Kasuta valkey või postgres väärtust muutujas QUIRE_CACHE_DRIVER, et limiit kehtiks nende kõigi peale.

Cloudflare Images salvestab iga esitatud algpildi enda koopiana. Faili kustutamisel kustutab töötleja koopia enne algfaili.

Tööjärjekord

Taustatööd kasutavad sama Postgresi andmebaasi pg-bossi, seega eraldi järjekorrateenust käivitada ega seadistada pole vaja. Tööd lisatakse järjekorda muudatuse tekitava andmebaasitehingu sees, nii et krahh ei saa tööd kaotada ega seda kaks korda saata. Siin on QUIRE_QUEUE_DRIVER vaikeväärtus pgboss; vercel ja cloudflare suunavad ainult kerged teavituste ning veebikonksude edastused platvormi järjekorda. Nende järjekordade ja veebikihtide kaudu lisamise kohta leiad juhised Verceli ja Cloudflare’i juhenditest.

E-post

Määra üks järgmistest:

• QUIRE_EMAIL_PROVIDER_CONFIG: HTTP-pakkujat ja selle mandaate nimetav JSON-objekt, näiteks {"provider":"postmark","token":"..."}. Toetatud on Postmark, Amazon SES, Mailgun, SendGrid ja Resend.
• QUIRE_SMTP_URL: smtp://user:password@host:587. Ainult see sihtkoht; serverita keskkondades blokeeritakse SMTP.

QUIRE_MAIL_FROM on saatja aadress. Quire’i katsetamiseks käivita devmail profiil, määra QUIRE_SMTP_URL=smtp://mailpit:1025 ja vaata kirju aadressil http://localhost:8025.

Valikulised teenused

Jälgitavus

OTEL_EXPORTER_OTLP_ENDPOINT määrab koguja, kuhu iga protsess saadab jäljed ja mõõdikud; profiiliga observability on väärtus http://otelcol:4318 ning failis docker/otel-collector.yaml saab lisada taustsüsteemi eksportija. Selle seadmisel ekspordivad veebikiht, töötleja, ajastaja, sisu- ja collab-protsessid vahemäluprotokolli HTTP kaudu lõigud (veebipäringud, rentniku andmebaasitehingud, töötleja tööd ja väljaminevad kutsed) ning saadavad iga minuti järel samasse kohta mõõdikud (OTEL_METRICS_EXPORTER=none lülitab need välja). Jälgede säilitatavat osa määrab OTEL_TRACES_SAMPLER_ARG. Logid lähevad tasemel LOG_LEVEL standardväljundisse ning Compose pöörab neid. Jäljed ei sisalda isikuandmeid.

Piirkondlik väljaminev liiklus (EL-i andmeresidentsus)

QUIRE_REGION=eu näitab, et virn teenindab Euroopa Liidu organisatsioone. Töötleja piirab seejärel kõigi EL-i piirkonnaga seotud organisatsioonide nimel tehtavad väljaminevad päringud lubatud loendiga (21-compliance.md jaotis 8.1). Loendis on piirkonnale seadistatud teenuste deklareeritud hostid (salvestuslõpp-punkt, e-posti pakkuja, majutatud videopakkuja, organisatsiooni enda salvestuskohad, tehisintellektipakkujad ja meilikonto), aktiivse erandi all oleva teenuse hostid ning QUIRE_EGRESS_ALLOW_HOSTS loetletud hostid. Iga muu avalikule hostile minev päring lükatakse enne saatmist tagasi, keeld kantakse organisatsiooni auditi jälge kirjena privacy/egress_refused ning see kuvatakse jaotises Compliance, Data residency.

Ühendkuningriigi ja USA organisatsioone hostiloend ei piira; nende puhul kontrollitakse endiselt ainult teenuse piirkonda. Määra loend töötlejal; haldusleht loeb seda veebikihis, et kuvada lubatud hostid, seega lisa see faili docker/.env, mida loevad kõik teenused.

Rakenduse kontroll annab selge vea ja auditisissekande, kuid see pole tagatis: kood võib eksida. Tagatise annab võrk. Compose ei rakenda seda sinu eest. Piirkondliku virna jaoks pane teenused worker ja web sisevõrku (internal: true), mille ainus väljamineku tee on liiklust filtreeriv puhverserver (näiteks Squid või pisike tinyproxy), mis lubab samu hoste kui QUIRE_EGRESS_ALLOW_HOSTS ja seadistatud teenuste hostid; määra nendele teenustele HTTPS_PROXY. Residentsusleht loetleb rakenduse lubatud hostid, et saaksid kahte loendit võrrelda.

Tervis

docker compose -f docker/compose.yaml ps näitab iga teenuse terviseolekut.

TLS

proxy-teenus (Caddy, Apache-2.0, docker/caddy/Caddyfile) kuulub vaikimisi virna. See vastab portidel 80 ja 443 ning suunab päringuid järgmiselt:

init-env.sh tuletab kahe päritolu põhjal väärtused QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL ja IMGPROXY_URL, et need lahku ei läheks. Kui muudad lähteaadressi käsitsi, tuleb neid muuta koos.

Sertifikaadid määrab QUIRE_PROXY_TLS:

• internal (vaikimisi): Caddy enda sertimiskeskus hostidele localhost, *.localhost ja lvh.me. Usalda juursertifikaati üks kord ja ava seejärel järgmise käsuga:

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

  Lisa quire-local-ca.crt süsteemi või brauseri usaldatud sertifikaatide hoidlasse. curl-iga kasuta valikut --cacert.

• E-posti aadressina antud väärtus: automaatsed ACME sertifikaadid (esmalt Let’s Encrypt, seejärel ZeroSSL) päris hostinimedele. Mõlema päritolu ja iga rentniku hosti DNS peab siia osutama ning pordid 80 ja 443 peavad internetist ligipääsetavad olema.

Rentniku hostide sertifikaadid väljastatakse vajaduse korral esmakülastusel ning ainult pärast seda, kui veebikiht kinnitab, et nimi kuulub sellele paigaldusele (/tls-allowed, päring tehakse Compose’i võrgus). Tärniga sertifikaati ega DNS-pakkuja pistikprogrammi pole vaja; võõras, hostile osutav nimi ei saa panna seda sertifikaati taotlema. Sertifikaadid ja kohalik sertimiskeskus asuvad caddy-data-köites; varunda see koos ülejäänuga, kui kasutad internal-režiimi.

Veebikiht usaldab X-Forwarded-For päist ainult puhverserverist: sellel on fikseeritud aadress QUIRE_PROXY_ADDRESS (vaikimisi 172.29.64.10) fikseeritud alamvõrgus QUIRE_COMPOSE_SUBNET ning QUIRE_TRUSTED_PROXY_CIDRS määrab selle aadressi. Kui alamvõrk kattub hosti võrguga, muuda mõlemat ning käivita käsk docker compose down enne up-i.

Oma vastupidise puhverserveri taga

Olemasoleva koormusjaoturi või puhverserveri kasutamiseks jäta proxy välja (docker compose up -d --scale proxy=0) ning lõpeta TLS nende ees: web (8080), content (8081), collab (1234, veebipesa) ja centrifugo (8000, veebipesa). Määra avalikud aadressid muutujates QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN ja QUIRE_COLLAB_URL (wss://) ning puhverserveri aadressivahemik muutujas QUIRE_TRUSTED_PROXY_CIDRS.

Tõrkeotsing

• init väljub veaga “QUIRE_DATABASE_ID is not a UUID”: määra see käsuga uuidgen.
• web taaskäivitub teatega “did not start on compose”: logi loetleb seaded, mida ei saa rakendada, ja soovitatud väärtused.
• Rolli parooli muutmine failis .env pärast esmakäivitust ei mõju: algskript käivitub vaid ühe korra. Kasuta ALTER ROLE-i.
• Üleslaadimine ebaõnnestub skannimise veaga, kuigi CLAMAV_URL on määratud: esmakäivitusel laadib ClamAV signatuurid alla, milleks kulub mõni minut. bun apps/docs-site/scripts/import-guide.ts et ops/install.md