Quire diegimas su Docker Compose

Tai visas produktas vienoje sistemoje: LMS, jo foninis darbas, realiojo laiko ir bendro redagavimo paslaugos ir kiekviena pasirenkama paslauga už profilio. Projekto aprašas yra docs/architecture/23-ops.md 2 skyrius.

Kiti tikslai: Vercel ir Cloudflare Workers vykdo tik tinklo sluoksnį. Atnaujinimai yra upgrade.md, o atsatinės kopijos ir atkūrimo pratybos – backup-restore.md.

Ko jums reikia

• Docker Engine 27 arba vėlesnis su Compose įskiepiu 2.30 arba vėlesniu.
• 4 CPU branduoliai ir 8 GB atminties numatytajam masyvui; 8 branduoliai ir 16 GB su --profile full (vienas ClamAV laiko apie 1,5 GB parašų).
• DNS vardas tinklo sluoksniui ir antras nepatikimam turiniui. Jie turi būti skirtingi šeimininkai: SCORM paketai ir įkeltas HTML veikia turinio kilmės vietose, todėl jie niekada negali perskaityti LMS slapukų.
• Vietiniam bandymui lvh.me ir *.localhost išsprendžiami į 127.0.0.1, ką ir naudoja docker/.env.example. Pati masyvo proxy paslauga tiekia abu per https su vietine liudijimų įstaiga, todėl nieko kito neįdiegiama (žr. „TLS“).
• 80 ir 443 prievadai laisvi sistemoje (QUIRE_PROXY_HTTP_PORT ir QUIRE_PROXY_HTTPS_PORT juos perkelia).

Pirmasis paleidimas

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 įrašo docker/.env iš docker/.env.example su sugeneruota kiekviena paslaptimi (duomenų bazės slaptažodžiai, pasirašymo ir pagrindiniai raktai, turinio paleidimo raktų pora) ir audito kontrolinio taško pasirašymo raktu faile docker/secrets/audit-signing-key.pem, kurį Compose prijungia prie darbininkų kaip paslaptį. Jam reikia tik sh, awk ir openssl, ir jis atsisako perrašyti jau esamą docker/.env. Nukopijuokite abu failus už sistemos ribų: be QUIRE_MASTER_KEY atkurta duomenų bazė negali iššifruoti savo išsaugotų prisijungimo duomenų. Jei norite failą užpildyti ranka, cp docker/.env.example docker/.env; faile parašyta, kaip sugeneruoti kiekvieną paslaptį.

Abu kilmės adresai turi būti https: turinio paslauga atsisako paprasto http gamyboje, ir jie negali dalytis registruojamu domenu. Paslauga proxy nutraukia TLS abiem (žr. „TLS“); init-env.sh atmeta http:// kilmės adresą.

Masyvas paleidžiamas fiksuota tvarka, ir kiekvienas žingsnis laukia ankstesnio:

1. postgres tampa sveikas. Pirmojo paleidimo metu jo paleidimo skriptas (docker/postgres/init/90-passwords.sh) nustato keturių vaidmenų slaptažodžius.
2. migrate pritaiko kiekvieną migraciją ir įkuria užduočių eilę valdymo duomenų bazėje ir kiekvienoje atskiroje nuomininko duomenų bazėje, patikrina, ar jos visos sutampa, tada išeina (docs/ops/upgrade.md). Migracijos vykdomos kiekvieną kartą paleidus ir yra idempotentiškos, todėl atnaujinimas yra naujas atvaizdas ir paleidimas iš naujo.
3. init (apps/web/src/first-run.ts) užregistruoja programų duomenų bazę po QUIRE_DATABASE_ID ir, kai nustatytas QUIRE_SETUP_ADMIN_EMAIL, sukuria pirmąją organizaciją ir jos administratorių. Prisijungimo adresas ir sugeneruotas slaptažodis atspausdinami vieną kartą, docker compose logs init.
4. Paleidžiami web, content, worker, scheduler, collab ir centrifugo.
5. proxy paleidžiamas, kai web ir content yra sveiki.

Atidarykite https://demo. ir po jo savo programos domeną (init žurnalas atspausdina tikslų prisijungimo adresą) ir prisijunkite. Diegiant vietoje pirmiausia pasitikėkite proxy liudijimų įstaiga (žr. „TLS“). Pakeiskite sugeneruotą slaptažodį adresu /account/security.

Procesas, paleistas be privalomos paslapties, atsisako paleisti ir savo žurnale įvardija trūkstamą nustatymą. Niekas nepaleidžiamas pusiau sukonfigūruotas.

Paslaugos ir profiliai

--profile full paleidžia kiekvieną pasirenkamą paslaugą, išskyrus backup ir h5p. Vieną paslaugą paleiskite su docker compose -f docker/compose.yaml --profile scan up -d. Be pasirenkamos paslaugos Quire vis tiek veikia ir pasako, ko trūksta: be skenerio įkėlimai saugomi neskeniuojami ir administratorius apie tai informuojamas; be „Gotenberg“ failai vietoj peržiūros siūlo atsisiųsti; be transkoderio vaizdo įrašas groja toks, koks yra originalus failas.

Kiekvienas trečiosios šalies atvaizdas ir jo licencijos įsipareigojimai išvardyti faile docker/third-party-containers.yaml.

H5P teikėjo prijungimas

Quire neįdeda ir neteikia H5P vykdyklo arba šalutinio proceso (ADR 0019). Jei naudojate H5P, patys tiekite prieglobos prenumeratą arba valdykite savo H5P instanciją atskirai nuo Quire. Užregistruokite tą teikėją kaip LTI 1.3 išorinį įrankį ir pridėkite jo turinį prie kursų kaip įrankio veiklas. Quire keičiasi įvertinimais ir veiklos / tikrinimo eiga per LTI Priskyrimo ir įvertinimo paslaugas (AGS). Jei teikėjas taip pat siunčia xAPI teiginius, sukonfigūruokite tai atskirai Quire xAPI teiginių saugyklai; AGS įvertinimų / eigos keitimasis xAPI teiginių nesiunčia. Moodle importai praneša, kad H5P veikloms reikia LTI įrankio ryšio. Teikėjas ir toliau atsakingas už savo H5P vykdyklą, redagavimą, turinio banką ir bandymų istoriją.

Kad paleistumėte savo H5P instanciją šioje sistemoje, nustatykite QUIRE_H5P_IMAGE į jos atvaizdą ir paleiskite profilį h5p. Compose jį paskelbia ant QUIRE_H5P_PORT (8090) ir saugo jo duomenis h5p-data tome; atsakomybė už atvaizdą ir kartu su juo ateinančius įsipareigojimus lieka jūsų.

Nustatymai

Kiekvienas procesas skaito docker/.env. Šablonas docker/.env.example išvardija kiekvieną nustatymą su jo numatytąja reikšme. Grupės:

Adresai

Paslaptys

Laikykite QUIRE_MASTER_KEY kopiją kur kitur, ne šioje sistemoje. Duomenų bazė, atkurta be jo, negali iššifruoti joje esančių prisijungimo duomenų.

Duomenų bazė

Vaidmenų slaptažodžiai taikomi tik tada, kai duomenų bazės tomas sukuriamas pirmą kartą. Norėdami vėliau pakeisti vieną, naudokite ALTER ROLE ir tada atnaujinkite atitinkamą URL.

QUIRE_REPORT_DATABASE_URL naudojamas fizinei duomenų bazei, sukonfigūruotai DATABASE_URL. Kiekvienai kitai registruotai fizinei duomenų bazei nustatykite jos pačios quire_report ryšio URL web ir darbininko aplinkose, tada į tą duomenų bazę įrašykite kintamojo pavadinimą į lauką Reporting environment variable kaip env:NAME. Nuoroda turi nurodyti į tą pačią duomenų bazę, kaip ir jos programų ryšys, pageidautina, jos skaitymo kopiją. Kiekvienas ataskaitų paviršius seka nuomininką į jo paties duomenų bazės ataskaitų ryšį: ataskaitų kūrėjas ir išsaugotos ataskaitos, planiniai pristatymai, ataskaitų eksportai, analitika, audito žurnalas, REST audito ištekliai ir asistento audito paieška. Nė vienas iš jų niekados nesiima kitos duomenų bazės ataskaitų URL. Kai duomenų bazė neturi ataskaitų ryšio, eilinės ataskaitos vykdomos tos duomenų bazės paties programų ryšiu, o analitika ir kiekvienas audito skaitymas atmetami su paaiškinimu, nes programų vaidmuo negali skaityti audito pėdsako.

Varikliai

Variklio reikšmės, kurios šios versijos nėra, tinklo sluoksniui paleidžiant atmetamos su nurodytu nustatymu, vietoj to, kad būtų tyliai pakeista numatąja reikšme.

Paveikslėliai

Puslapiai prašo paveikslėlių keturiais fiksuotais dydžiais per /api/files/{id}/image/{size}, kuris tikrina tą patį prieinamumą kaip ir pats failas, o tada nukreipia į paveikslėlių paslaugą. Kiekviena organizacija gali per valandą paprašyti QUIRE_IMAGE_SPECS_PER_HOUR (pagal nutylėjimą 2000) naujų paveikslėlio ir dydžio porų; tą valandą jau pagaminti dydžiai nesiskaičiuoja. Kai web konteinerių daugiau nei vienas, naudokite valkey arba postgres kaip QUIRE_CACHE_DRIVER, kad limitas galiotų per visus.

Cloudflare Images laiko savo kiekvieno originalo, kurį tiekia, kopiją. Kai failas ištrinamas, darbininkas tą kopiją ištrina prieš originalą.

Eilė

Fono užduotys naudoja pg-boss toje pačioje Postgres duomenų bazėje, todėl eilės paslaugos paleisti nereikia ir nėra ko konfigūruoti. Užduotys dedamos į eilę toje pačioje transakcijoje, kaip ir pakeitimas, ją sukėlęs, todėl kritimas negali nė vienos prarasti arba nė vienos išsiųsti du kartus. QUIRE_QUEUE_DRIVER čia yra pgboss, jo numatytoji reikšmė; vercel ir cloudflare perkelia tik lengvus pranešimų ir „webhook“ pristatymus į pačios platformos eilę, o Vercel ir Cloudflare vadovai juos aprašo ir tai, kaip jų tinklo sluoksniai deda į eilę.

El. paštas

Nustatykite vieną iš:

• QUIRE_EMAIL_PROVIDER_CONFIG: JSON objektas, įvardijantis HTTP teikėją ir jo prisijungimo duomenis, pavyzdžiui {"provider":"postmark","token":"..."}. Palaikomi Postmark, Amazon SES, Mailgun, SendGrid ir Resend.
• QUIRE_SMTP_URL: smtp://user:password@host:587. Tik šiam tikslui; be serverio tikslai SMTP blokuoja.

QUIRE_MAIL_FROM yra siuntėjas. Norėdami išbandyti Quire, paleiskite profilį devmail, nustatykite QUIRE_SMTP_URL=smtp://mailpit:1025 ir skaitykite paštą adresu http://localhost:8025.

Pasirenkamos paslaugos

Stebėsena

OTEL_EXPORTER_OTLP_ENDPOINT įvardija rinktuvą, į kurį kiekvienas procesas siunčia pėdsakus ir matuoklius; su profiliumi observability tai yra http://otelcol:4318, o docker/otel-collector.yaml yra vieta, kur pridedate eksportuotoją savo sistemai. Tinklo sluoksnio, darbininko, tvarkytuvo, turinio ir bendradarbiavimo procesai eksportuoja intervalus per OTLP/HTTP (web užklausos, nuomininko duomenų bazės transakcijos, darbininko užduotys ir išeinančios užklausos), kai tai nustatyta, ir matuoklius į tą patį adresą kas minutę (OTEL_METRICS_EXPORTER=none juos išjungia). OTEL_TRACES_SAMPLER_ARG nustato laikomų pėdsakų dalį. Žurnalai eina į standartinę išvestį su LOG_LEVEL, o Compose juos sukasi. Pėdsakuose niekada nėra asmens duomenų.

Regioninis išėjimas (ES duomenų rezidavimas)

QUIRE_REGION=eu sako, kad masyvas aptarnauja Europos Sąjungos organizacijas. Tada darbininkas kiekvieną išeinantį užklausą, padarytą organizacijai, pririštai prie ES, laiko pagal leidžiamų adresų sąrašą (21-compliance.md 8.1 skyrius). Leidžiamų adresų sąrašą sudaro šeimininkai, kuriuos sukonfigūruotos paslaugos deklaruoja regionui (saugyklos adresas, el. pašto teikėjas, prieglobos vaizdo teikėjas, pačios organizacijos saugyklų adresai, DI teikėjai ir el. pašto paskyra), bet kokios paslaugos, esančios aktyvioje nuolaidoje, šeimininkai, ir jūsų išvardyti šeimininkai faile QUIRE_EGRESS_ALLOW_HOSTS. Užklausa į bet kokį kitą viešą šeimininką atmetama dar prieš ją išsiunčiant, atmetimas įrašomas į organizacijos audito pėdsaką kaip privacy/egress_refused, ir jis išvardijamas skiltyje Atitiktis, Duomenų rezidavimas.

JK ir JAV organizacijos nelaikomos šeimininkų sąrašu; jos išlaiko paslaugos regiono patikras. Nustatykite sąrašą darbininkui; administratoriaus puslapis jį skaito tinklo sluoksnyje, kad parodytų leidžiamų adresų sąrašą, todėl įrašykite jį į docker/.env, kurį skaito kiekviena paslauga.

Programos patikra duoda aiškią klaidą ir audito įrašą, ir tai nėra garantija: kodas gali būti klaidingas. Garantija yra tinklas. Compose to jums neįgyvendina. Regioniniam masyvui dėkite worker ir web paslaugas į internal: true tinklą, kurio vienintelis išėjimas yra išėjimo įėjimo taškas (pavyzdžiui Squid arba tinyproxy konteineris), leidžiantis tuos pačius šeimininkus kaip QUIRE_EGRESS_ALLOW_HOSTS ir jūsų sukonfigūruotų paslaugų šeimininkus, ir nustatykite HTTPS_PROXY toms paslaugoms. Rezidavimo puslapis išvardija tikslius šeimininkus, kuriuos leidžia programa, todėl tuos du sąrašus galima palyginti.

Sveikata

docker compose -f docker/compose.yaml ps rodo kiekvienos paslaugos sveikatą.

TLS

Paslauga proxy (Caddy, Apache-2.0, docker/caddy/Caddyfile) yra numatytojo masyvo dalis. Ji atsako 80 ir 443 prievaduose ir maršrutizuoja:

init-env.sh išveda QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL ir IMGPROXY_URL iš dviejų kilmės adresų, todėl jie negali išsiskirtyti. Redaguokite juos kartu, jei kilmės adresą keičiate ranka.

Liudijimai vadovaujasi QUIRE_PROXY_TLS:

• internal (pagal nutylėjimą): pati Caddy liudijimų įstaiga localhost, *.localhost ir lvh.me. Kartą pasitikėkite jos šaknimi, tada naršykite:

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

  Pridėkite quire-local-ca.crt prie sistemos arba naršyklės pasitikėjimo saugyklos. curl jį priima su --cacert.

• El. pašto adresas: automatiniai ACME liudijimai (Let’s Encrypt, tada ZeroSSL) tikriems vardams. Abiejų kilmės sričių ir kiekvieno nuomininko šeimininko DNS turi nurodyti čia, o 80 ir 443 prievadai turi būti pasiekiami iš interneto.

Nuomininkų šeimininkai išduodami pagal poreikį, pirmojo apsilankymo metu, ir tik tada, kai web patvirtina, kad vardas priklauso šiam diegimui (/tls-allowed, klausiama Compose tinkle). Nereikia nei pakaitinio liudijimo, nei DNS teikėjo įskiepio, ir svetimas žmogus, nukreipęs vardą į sistemą, negali priversti jos prašyti liudijimų. Liudijimai ir vietinė įstaiga gyvena caddy-data tome; jei naudojate internal, atsarginę kopiją darykite kartu su likusia dalimi.

Web tikima X-Forwarded-For tik iš įėjimo taško: jis turi fiksuotą adresą (QUIRE_PROXY_ADDRESS, pagal nutylėjimą 172.29.64.10) fiksuotame tinkle (QUIRE_COMPOSE_SUBNET), ir QUIRE_TRUSTED_PROXY_CIDRS įvardija tą adresą. Jei tinklas susiduria su tinklu sistemoje, pakeiskite abu ir paleiskite docker compose down prieš up.

Už savo atvirkštinio įėjimo taško

Norėdami naudoti apkrovos paskirstytuvą arba įėjimo tašką, kurį jau turite, palikite proxy už (docker compose up -d --scale proxy=0) ir nutraukite TLS priekyje web (8080), content (8081), collab (1234, websocket) ir centrifugo (8000, websocket). Nustatykite viešuosius adresus QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN ir QUIRE_COLLAB_URL (wss://), ir savo įėjimo taško adresų intervalą QUIRE_TRUSTED_PROXY_CIDRS.

Trikčių šalinimas

• init išeina su “QUIRE_DATABASE_ID is not a UUID”: nustatykite jį su uuidgen.
• web paleidžiamas iš naujo su “did not start on compose”: žurnale išvardijamas kiekvienas nustatymas, kurio jis negali įgyvendinti, ir ką vietoj jo naudoti.
• Vaidmens slaptažodžio pakeitimas faile .env po pirmojo paleidimo nieko nedaro: paleidimo skriptas veikia vieną kartą. Naudokite ALTER ROLE.
• Įkėlimai nepavyksta su klaida dėl skenavimo, kai nustatytas CLAMAV_URL: ClamAV parsisiunčia savo parašus pirmojo paleidimo metu, o tai užtrunka kelias minutes.