Quire Docker Compose bidez instalatzea

Ostalari bakarrean produktu osoa instalatzeko aukera da hau: LMSa, atzeko planoko lana, denbora errealeko eta lankidetzako edizio-zerbitzuak, baita profil baten bidez aktiba daitezkeen aukerako zerbitzu guztiak ere. Diseinua docs/architecture/23-ops.md ataleko 2. atalean dago.

Beste helburu batzuk: Vercel eta Cloudflare Workers aukerek web-maila baino ez dute exekutatzen. Bertsio-berritzeak upgrade.md gidan daude; babeskopiak eta leheneratze-proba, berriz, backup-restore.md gidan.

Behar duzuna

• Docker Engine 27 edo berriagoa, Compose 2.30 pluginarekin edo berriagoarekin.
• 4 CPU nukleo eta 8 GB memoria pila lehenetsirako; 8 nukleo eta 16 GB --profile full erabiltzeko (ClamAVek bakarrik 1,5 GB inguru hartzen ditu sinadurak gordetzeko).
• Web-mailarako DNS izen bat eta eduki ez-fidagarrietarako beste bat. Ostalari desberdinak izan behar dute: SCORM paketeak eta igotako HTMLa eduki-jatorrian exekutatzen dira, LMSaren cookieak inoiz irakurri ezin ditzaten.
• Tokiko proba baterako, lvh.me eta *.localhost helbideek 127.0.0.1 helbidera ebazten dute; hori erabiltzen du docker/.env.example fitxategiak. Pilako proxy zerbitzuak biak https bidez zerbitzatzen ditu ziurtagiri-autoritate lokal batekin, eta, beraz, ez da beste ezer instalatu behar (ikus “TLS”).
• Ostalariko 80 eta 443 portuek libre egon behar dute (QUIRE_PROXY_HTTP_PORT eta QUIRE_PROXY_HTTPS_PORT erabiliz alda daitezke).

Lehen exekuzioa

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 scriptak docker/.env sortzen du docker/.env.example fitxategitik, sekretu guztiak sortuta (datu-baseko pasahitzak, sinadura- eta gako nagusiak, edukiak abiarazteko gako-parea), baita docker/secrets/audit-signing-key.pem fitxategiko auditoretza-kontrol-puntuaren sinadura-gakoa ere. Composek worker-etan muntatzen du sekretu gisa. sh, awk eta openssl baino ez ditu behar, eta ez du lehendik dagoen docker/.env fitxategia gainidazten. Kopiatu bi fitxategiak ostalaritik kanpo: QUIRE_MASTER_KEY gabe, leheneratutako datu-base batek ezin ditu gordetako kredentzialak deszifratu. Fitxategia eskuz bete nahi baduzu, exekutatu cp docker/.env.example docker/.env; fitxategian sekretu bakoitza sortzeko argibideak daude.

Bi jatorriek https erabili behar dute: eduki-zerbitzuak ez du http arrunta onartzen produkzioan, eta biek ezin dute erregistratu daitekeen domeinu bera partekatu. proxy zerbitzuak TLS amaitzen du bietan (ikus “TLS”); init-env.sh scriptak http:// jatorririk ez du onartzen.

Pila ordena finko batean abiarazten da, eta urrats bakoitzak aurrekoa amaitu arte itxaroten du:

1. postgres osasuntsu jartzen da. Lehen abiaraztean, hasieratze-scriptak (docker/postgres/init/90-passwords.sh) lau rolen pasahitzak ezartzen ditu.
2. migrate zerbitzuak migrazio guztiak aplikatzen ditu, eta lan-ilara abiarazten du kontrol-datu-basean eta maizter bakoitzaren datu-base bereizian. Denak bat datozela egiaztatu ondoren amaitzen da (docs/ops/upgrade.md). Migrazioak abiarazte bakoitzean exekutatzen dira eta idempotenteak dira; beraz, bertsio-berritzeko irudi berria eta berrabiaraztea besterik ez da behar.
3. init zerbitzuak (apps/web/src/first-run.ts) aplikazioaren datu-basea erregistratzen du QUIRE_DATABASE_ID aldagaian eta, QUIRE_SETUP_ADMIN_EMAIL ezarrita badago, lehen erakundea eta administratzailea sortzen ditu. Saioa hasteko helbidea eta sortutako pasahitza behin bakarrik inprimatzen dira docker compose logs init emaitzan.
4. web, content, worker, scheduler, collab eta centrifugo abiarazten dira.
5. proxy abiarazten da web eta content zerbitzuak osasuntsu daudenean.

Ireki https://demo. eta jarraian aplikazioaren domeinua (saioa hasteko helbide zehatza init erregistroan dago), eta hasi saioa. Tokiko instalazioan, fidatu lehenik proxyaren ziurtagiri-autoritateaz (ikus “TLS”). Aldatu sortutako pasahitza /account/security helbidean.

Beharrezko sekreturik gabe abiarazten den prozesu batek ez du abiatzea onartzen, eta falta den ezarpena adierazten du erregistroan. Ez da ezer erdi-konfiguratuta abiarazten.

Zerbitzuak eta profilak

--profile full komandoak aukerako zerbitzu guztiak abiarazten ditu, backup eta h5p izan ezik. Abiarazi zerbitzu bat docker compose -f docker/compose.yaml --profile scan up -d erabiliz. Aukerako zerbitzurik gabe ere Quirek funtzionatzen du eta falta dena adierazten du: eskannerik ez badago, fitxategiak eskaneatu gabe gordetzen dira eta administratzaileari jakinarazten zaio; Gotenbergik ez badago, fitxategiak aurrebista gisa erakutsi ordez deskargatzeko eskaintzen dira; transkodetzailerik ez badago, bideoa jatorrizko fitxategi gisa erreproduzitzen da.

Hirugarrenen irudi guztiak eta haien lizentzia-betebeharrak docker/third-party-containers.yaml fitxategian zerrendatzen dira.

H5P hornitzaile bat konektatzea

Quirek ez du H5P exekuzio-ingurunerik edo alboko zerbitzurik barneratzen edo banatzen (ADR 0019). H5P erabiltzen baduzu, kontratatu zure ostatatutako harpidetza edo kudeatu Quiretik aparteko H5P instantzia auto-ostatua. Erregistratu hornitzaile hori LTI 1.3 kanpoko tresna gisa, eta gehitu haren edukia ikastaroetan tresna-jarduera gisa. Quirek kalifikazioak eta jardueraren/kalifikazioaren aurrerapena trukatzen ditu LTI Assignment and Grade Services (AGS) bidez. Hornitzaileak xAPI instrukzioak ere bidaltzen baditu, konfiguratu hori bereizita Quireren xAPI instrukzioen biltegirako; AGS bidezko kalifikazio/aurrerapen trukeak ez du xAPI instrukziorik bidaltzen. Moodle inportazioek H5P jarduerak LTI tresnaren konexioa behar dutela adierazten dute. Hornitzailearen ardura dira H5P exekuzio-ingurunea, edukiak sortzea, eduki-bankua eta saiakeren historia.

Zure auto-ostatutako instantzia ostalari honetan exekutatzeko, ezarri QUIRE_H5P_IMAGE haren irudi gisa eta abiarazi h5p profila. Composek QUIRE_H5P_PORT atakan argitaratzen du (8090), eta datuak h5p-data bolumenean gordetzen ditu; irudia eta hari dagozkion betebeharrak zure ardurapean daude.

Ezarpenak

Prozesu guztiek docker/.env fitxategia irakurtzen dute. Txantiloiak, docker/.env.example fitxategiak, ezarpen bakoitza eta haren lehenetsitako balioa zerrendatzen ditu. Taldeak:

Helbideak

Sekretuak

Gorde QUIRE_MASTER_KEY ostalari honetatik aparte. Hura gabe leheneratutako datu-base batek ezin ditu gordetako kredentzialak deszifratu.

Datu-basea

Rol-pasahitzak datu-baseko bolumena lehen aldiz sortzean soilik aplikatzen dira. Geroago aldatzeko, erabili ALTER ROLE eta eguneratu dagokion URLa.

QUIRE_REPORT_DATABASE_URL DATABASE_URL bidez konfiguratutako datu-base fisikorako erabiltzen da. Erregistratutako beste edozein datu-base fisikorako, ezarri haren quire_report konexio-URLa webaren eta worker-aren inguruneetan; ondoren, jarri aldagaiaren izena datu-base horren Txostenen ingurune-aldagaia eremuan, env:NAME formatuan. Erreferentziak aplikazio-konexioaren datu-base berera jo behar du, ahal dela haren irakurketa-erreplikara. Txostenen interfaze guztiek maizterrari jarraitzen diote, haren datu-baseko txosten-konexiora: txosten-sortzailea eta gordetako txostenak, programatutako bidalketak, txosten-esportazioak, analitikak, auditoretza-erregistroa, REST auditoretza-baliabideak eta laguntzailearen auditoretza-bilaketa. Inork ez du beste datu-base baten txosten-URLarik erabiltzen. Datu-base batek txosten-konexiorik ez duenean, ohiko txostenak datu-base horren aplikazio-konexio propioan exekutatzen dira; analitikak eta auditoretza-irakurketa guztiak, ordea, ukatu egiten dira eta horren berri ematen dute, aplikazio-rolak ezin baitu auditoretza-arrastoa irakurri.

Driver-ak

Bertsio honek barne hartzen ez duen driver-balio batek web-maila abiaraztea eragozten du, dagokion ezarpena adieraziz, lehenetsitako balioarekin isilean ordezkatu ordez.

Irudiak

Orrialdeek lau tamaina finkotako irudiak eskatzen dituzte /api/files/{id}/image/{size} bidez; horrek fitxategiaren sarbide-baimen berak egiaztatzen ditu, eta ondoren irudi-zerbitzura birbideratzen du. Erakunde bakoitzak orduko QUIRE_IMAGE_SPECS_PER_HOUR (lehenetsia 2000) irudi eta tamaina bikote berri eska ditzake; ordu horretan sortutako tamainak ez dira kontatzen. Erabili valkey edo postgres QUIRE_CACHE_DRIVER gisa web-edukiontzi bat baino gehiago baduzu, muga guztietan aplika dadin.

Cloudflare Imagesek zerbitzatzen duen jatorrizko fitxategi bakoitzaren kopia propioa gordetzen du. Fitxategi bat ezabatzean, worker-ak kopia hori ezabatzen du jatorrizkoa baino lehen.

Ilara

Atzeko planoko lanek pg-boss erabiltzen dute Postgres datu-base berean; beraz, ez dago ilara-zerbitzurik exekutatu edo konfiguratu beharrik. Lanak abiarazi dituen aldaketaren transakzio berean ilaran jartzen dira; hortaz, kraskatze batek ezin ditu galdu edo bi aldiz bidali. QUIRE_QUEUE_DRIVER hemen pgboss da, lehenetsitako balioa; vercel eta cloudflare aukerek jakinarazpen- eta webhook-bidalketa arinak baino ez dituzte eramaten plataformako ilara propiora. Vercel eta Cloudflare gidetan ageri dira horiek eta web-mailek ilaran nola jartzen dituzten.

Posta elektronikoa

Ezarri hauetako bat:

• QUIRE_EMAIL_PROVIDER_CONFIG: HTTP hornitzaile bat eta haren kredentzialak izendatzen dituen JSON objektua, hala nola {"provider":"postmark","token":"..."}. Postmark, Amazon SES, Mailgun, SendGrid eta Resend onartzen dira.
• QUIRE_SMTP_URL: smtp://user:password@host:587. Helburu honetan soilik; zerbitzaririk gabeko helburuek SMTP blokeatzen dute.

QUIRE_MAIL_FROM da bidaltzailearen helbidea. Quire probatzeko, abiarazi devmail profila, ezarri QUIRE_SMTP_URL=smtp://mailpit:1025 eta irakurri posta http://localhost:8025 helbidean.

Aukerako zerbitzuak

Behagarritasuna

OTEL_EXPORTER_OTLP_ENDPOINT aldagaiak prozesu guztiek aztarnak eta metrikak bidaltzen dituzten biltzailea izendatzen du; observability profilarekin http://otelcol:4318 da, eta docker/otel-collector.yaml da zure backend-erako esportatzailea gehitzeko fitxategia. Web-mailak, worker-ak, scheduler-ak, content-ek eta collab prozesuek OTLP/HTTP bidez esportatzen dituzte tarteak (web-eskaerak, maizterraren datu-baseko transakzioak, worker-en lanak eta irteerako deiak) ezarrita dagoenean, eta minuturo metrikak helbide berera (OTEL_METRICS_EXPORTER=none ezarriz gero desaktibatzen dira). OTEL_TRACES_SAMPLER_ARG aldagaiak gordeko diren aztarnen proportzioa ezartzen du. Erregistroak irteera estandarrera bidaltzen dira LOG_LEVEL mailan, eta Composek biratu egiten ditu. Aztarnek ez dute datu pertsonalik eramaten.

Eskualdeko irteera (EBko datu-egoitza)

QUIRE_REGION=eu aldagaiak adierazten du pilak Europar Batasuneko erakundeak zerbitzatzen dituela. Orduan, worker-ak EBko eskualdean finkatuta dagoen erakunde baten alde egindako irteerako eskaera guztiak baimen-zerrenda baten arabera mugatzen ditu (21-compliance.md ataleko 8.1 puntua). Baimen-zerrendak eskualderako konfiguratutako zerbitzuek deklaratutako ostalariak biltzen ditu (biltegiratze-amaiera, posta-hornitzailea, ostatatutako bideo-hornitzailea, erakundearen berezko biltegiratze-helburuak, AI hornitzaileak eta posta-kontua), salbuespen aktibo baten pean dagoen edozein zerbitzuren ostalariak, eta QUIRE_EGRESS_ALLOW_HOSTS aldagaian zerrendatutako ostalariak. Beste edozein ostalari publikora egindako eskaera ukatu egiten da bidali aurretik; ukapena erakundearen auditoretza-erregistroan idazten da privacy/egress_refused gisa, eta Betetzea, Datu-egoitza atalean zerrendatzen da.

Erresuma Batuko eta AEBetako erakundeek ez dute ostalari-zerrendaren mugarik; zerbitzuen eskualde-egiaztapenei eusten diete. Ezarri zerrenda worker-ean; administrazio-orriak web-mailan irakurtzen du baimen-zerrenda erakusteko, beraz jarri docker/.env fitxategian, zerbitzu guztiek irakurtzen baitute.

Aplikazio-egiaztapenak errore argia eta auditoretza-sarrera sortzen ditu, baina ez da bermea: kodea oker egon daiteke. Bermea sarea da. Composek ez du hori automatikoki betearazten. Eskualdeko pila baterako, jarri worker eta web zerbitzuak internal: true sare batean, eta utzi irteerarako bide bakar gisa egress proxy bat (adibidez, Squid edo tinyproxy edukiontzi bat), QUIRE_EGRESS_ALLOW_HOSTS zerrendako ostalari berak eta konfiguratutako zerbitzuen ostalariak onartzen dituena; ezarri HTTPS_PROXY zerbitzu horientzat. Egoitza-orriak aplikazioak baimentzen dituen ostalari zehatzak zerrendatzen ditu, zerrendarekin alderatu ahal izateko.

Osasuna

docker compose -f docker/compose.yaml ps komandoak zerbitzu bakoitzaren osasun-egoera erakusten du.

TLS

proxy zerbitzua (Caddy, Apache-2.0, docker/caddy/Caddyfile) pila lehenetsiaren barruan dago. 80 eta 443 portuetan erantzuten du eta honela bideratzen du:

init-env.sh scriptak QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL eta IMGPROXY_URL aldagaiak bi jatorrietatik eratorriko ditu, elkarrengandik aldendu ez daitezen. Aldatu elkarrekin jatorri bat eskuz aldatzen baduzu.

Ziurtagirien konfigurazioa QUIRE_PROXY_TLS aldagaiaren araberakoa da:

• internal (lehenetsia): Caddyren ziurtagiri-autoritate propioa, localhost, *.localhost eta lvh.me domeinuetarako. Fidatu behin haren erro-ziurtagiriaz, eta nabigatu:

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

  Gehitu quire-local-ca.crt sistemaren edo nabigatzailearen fidagarritasun-biltegian. curl komandoarekin, eman fitxategia --cacert aukeraren bidez.

• Posta-helbide bat: ostalari-izen errealetarako ACME ziurtagiri automatikoak (Let’s Encrypt, ondoren ZeroSSL). DNSak bi jatorrietarako eta maizterren ostalari guztietarako hona bideratu behar du; 80 eta 443 portuek Internetetik irisgarri egon behar dute.

Maizterren ostalarientzako ziurtagiriak eskaeraren arabera igortzen dira lehen bisitan soilik, eta webak egiaztatzen duenean izena instalazio honi dagokiola (/tls-allowed, Compose sarean galdetuta). Ez da wildcard ziurtagiririk edo DNS hornitzailearen pluginik behar, eta izen bat ostalari honetara bideratzen duen ezezagun batek ezin du ziurtagiri-eskaerarik eragin. Ziurtagiriak eta autoritate lokala caddy-data bolumenean gordetzen dira; egin horien babeskopia gainerakoekin batera internal erabiltzen baduzu.

Webak X-Forwarded-For goiburua proxyarengandik soilik hartzen du fidagarritzat: proxyak helbide finkoa du (QUIRE_PROXY_ADDRESS, lehenetsia 172.29.64.10) sare finko batean (QUIRE_COMPOSE_SUBNET), eta QUIRE_TRUSTED_PROXY_CIDRS aldagaiak helbide hori izendatzen du. Azpisarea ostalariko sare batekin bat badator, aldatu biak eta exekutatu docker compose down up egin aurretik.

Zure alderantzizko proxyaren atzean

Horren ordez lehendik darabilzun karga-orekatzailea edo proxy-a erabiltzeko, utzi proxy zerbitzua abiarazi gabe (docker compose up -d --scale proxy=0) eta amaitu TLS web (8080), content (8081), collab (1234, websocketa) eta centrifugo (8000, websocketa) zerbitzuen aurrean. Ezarri helbide publikoak QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN eta QUIRE_COLLAB_URL (wss://) aldagaien bidez, eta proxyaren helbide-barrutia QUIRE_TRUSTED_PROXY_CIDRS aldagaian.

Arazoak konpontzea

• init zerbitzua “QUIRE_DATABASE_ID is not a UUID” mezuarekin amaitzen da: ezarri UUIDa uuidgen erabiliz.
• web zerbitzua berrabiarazi egiten da “did not start on compose” mezuarekin: erregistroak bete ezin dituen ezarpen guztiak eta horien ordez zer erabili zerrendatzen ditu.
• .env fitxategian rol-pasahitza aldatzeak lehen abiaraztearen ondoren ez du eraginik: hasieratze-scripta behin bakarrik exekutatzen da. Erabili ALTER ROLE.
• Igoerek eskaneatze-errorea ematen dute CLAMAV_URL ezarrita dagoela: ClamAVek sinadurak deskargatzen ditu lehen abiaraztean, eta horrek minutu batzuk behar ditu.