Installeer Quire met Docker Compose

Dit is die volledige produk op een gasheer: die LMS, sy agtergrondwerk, die intydse en samewerkende redigeerdienste en elke opsionele diens agter ’n profiel. Die ontwerp is afdeling 2 van docs/architecture/23-ops.md.

Ander teikens: Vercel en Cloudflare Workers loop net die webvlak. Opgraderings staan in upgrade.md, en rugsteun en die hersteloefening in backup-restore.md.

Wat jy nodig het

• Docker Engine 27 of later met Compose-inprop 2.30 of later.
• 4 CPU-kerne en 8 GB geheue vir die verstekstapel; 8 kerne en 16 GB met --profile full (ClamAV alleen hou ongeveer 1.5 GB handtekeninge).
• ’n DNS-naam vir die webvlak en ’n tweede vir onbetroubare inhoud. Hulle moet verskillende gashere wees: SCORM-pakkette en opgelaaide HTML loop op die inhoudsoorsprong sodat hulle nooit die LMS-koekies kan lees nie.
• Vir ’n plaaslike toets los lvh.me en *.localhost op na 127.0.0.1, soos docker/.env.example gebruik. Die stapel se eie proxy-diens bedien albei oor https met ’n plaaslike sertifikaatowerheid, dus word niks anders geïnstalleer nie (sien “TLS”).
• Poorte 80 en 443 moet op die gasheer beskikbaar wees (QUIRE_PROXY_HTTP_PORT en QUIRE_PROXY_HTTPS_PORT verskuif hulle).

Eerste aanvang

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 skryf docker/.env vanaf docker/.env.example met elke geheim gegenereer (databasiswagwoorde, ondertekenings- en hoofsleutels, inhoudbekendstellingsleutelpaar) en die ouditkontrolepunt se ondertekeningsleutel in docker/secrets/audit-signing-key.pem; Compose monteer dit in werkers as ’n geheim. Dit benodig net sh, awk en openssl, en weier om ’n bestaande docker/.env te oorskryf. Kopieer albei lêers van die gasheer af: sonder QUIRE_MASTER_KEY kan ’n herstelde databasis nie sy gestoorde aanmeldbewyse ontsyfer nie. Om die lêer eerder met die hand in te vul, voer cp docker/.env.example docker/.env uit; die lêer verduidelik hoe om elke geheim te genereer.

Albei oorspronge moet https wees: die inhouddiens weier gewone http in produksie, en hulle mag nie ’n registreerbare domein deel nie. Die proxy-diens beëindig TLS vir albei (sien “TLS”); init-env.sh weier ’n http://-oorsprong.

Die stapel begin in ’n vaste volgorde, en elke stap wag vir die vorige:

1. postgres word gesond. By die heel eerste aanvang stel sy inisialisasieskrip (docker/postgres/init/90-passwords.sh) die vier rolwagwoorde.
2. migrate pas elke migrasie toe en begin die taak-tou in die beheerdatabasis en elke toegewyde tenant-databasis, kontroleer dat almal ooreenstem en sluit dan af (docs/ops/upgrade.md). Migrasies loop met elke aanvang en is idempotent, dus is ’n opgradering ’n nuwe beeld en ’n herbegin.
3. init (apps/web/src/first-run.ts) teken die toepassingdatabasis onder QUIRE_DATABASE_ID aan en skep, wanneer QUIRE_SETUP_ADMIN_EMAIL gestel is, die eerste organisasie en administrateur. Die aanmeldadres en gegenereerde wagwoord word een keer in docker compose logs init vertoon.
4. web, content, worker, scheduler, collab en centrifugo begin.
5. proxy begin wanneer web en content gesond is.

Maak https://demo. gevolg deur jou toepassingdomein oop (die init-log druk die presiese aanmeldadres) en meld aan. Op ’n plaaslike installasie moet jy eers die proxy se sertifikaatowerheid vertrou (sien “TLS”). Verander die gegenereerde wagwoord by /account/security.

’n Proses wat sonder ’n vereiste geheim begin, weier om te begin en noem die ontbrekende instelling in sy log. Niks begin half gekonfigureer nie.

Dienste en profiele

--profile full begin elke opsionele diens behalwe backup en h5p. Begin een met docker compose -f docker/compose.yaml --profile scan up -d. Sonder ’n opsionele diens werk Quire steeds en verduidelik wat ontbreek: sonder skandeerder word oplaaie ongeskandeer gestoor en die administrateur ingelig; sonder Gotenberg bied lêers aflaai in plaas van voorskou; sonder transkodeerder speel video as oorspronklike lêer.

Elke derdepartybeeld en sy lisensieverpligtinge word in docker/third-party-containers.yaml gelys.

Koppel ’n H5P-verskaffer

Quire sluit nie ’n H5P-looptyd of sywaartse diens in nie (ADR 0019). As jy H5P gebruik, verskaf jou eie gehuisveste intekening of bedryf jou eie selfgehuisveste H5P-instansie apart van Quire. Registreer die verskaffer as ’n LTI 1.3-eksterne nutsding en voeg sy inhoud as nutsdingaktiwiteite by kursusse. Quire ruil punte en aktiwiteit-/nasienvordering uit deur LTI Assignment and Grade Services (AGS). As die verskaffer ook xAPI-stellings stuur, stel dit apart vir Quire se xAPI-stellingstoor op; AGS-uitruil stuur nie xAPI-stellings nie. Moodle-invoere meld dat H5P-aktiwiteite ’n LTI-nutsdingverbinding nodig het. Die verskaffer bly verantwoordelik vir sy H5P-looptyd, opstel, inhoudbank en pogingsgeskiedenis.

Om jou eie selfgehuisveste instansie op hierdie gasheer te loop, stel QUIRE_H5P_IMAGE op sy beeld en begin die h5p-profiel. Compose publiseer dit op QUIRE_H5P_PORT (8090) en hou sy data in die h5p-data-volume; die beeld en gepaardgaande verpligtinge bly joune.

Instellings

Elke proses lees docker/.env. Die sjabloon, docker/.env.example, lys elke instelling met sy verstekwaarde. Groepe:

Adresse

Geheime

Hou ’n kopie van QUIRE_MASTER_KEY elders as op hierdie gasheer. ’n Databasis wat daarsonder herstel word, kan die aanmeldbewyse daarin nie ontsyfer nie.

Databasis

Rolwagwoorde word net toegepas wanneer die databasisvolume die eerste keer geskep word. Om een later te verander, gebruik ALTER ROLE en werk dan die ooreenstemmende URL by.

QUIRE_REPORT_DATABASE_URL word gebruik vir die fisiese databasis wat deur DATABASE_URL gekonfigureer word. Vir enige ander geregistreerde fisiese databasis, stel sy eie quire_report-verbinding-URL in die web- en werkeromgewings en plaas dan die veranderlikenaam in daardie databasis se veld Verslagdoeningsomgewingsveranderlike as env:NAME. Die verwysing moet na dieselfde databasis as sy toepassingverbinding wys, verkieslik die leesreplika. Elke verslagoppervlak volg die tenant na sy eie databasis se verslagverbinding: verslagbouer en gestoorde verslae, geskeduleerde aflewerings, verslaguitvoere, analise, ouditlog, REST-ouditbronne en assistent se ouditsoektog. Geen van hulle leen ooit ’n ander databasis se verslag-URL nie. Wanneer ’n databasis geen verslagverbinding het nie, loop gewone verslae op daardie databasis se eie toepassingverbinding; analise en elke ouditlesing weier en verduidelik waarom, want die toepassingrol kan nie die ouditspoor lees nie.

Aandrywers

’n Aandrywerwaarde wat hierdie vrystelling nie insluit nie, word geweier wanneer die webvlak begin, met die instelling benoem, eerder as om stilweg deur die verstek vervang te word.

Beelde

Bladsye vra beelde in vier vaste groottes deur /api/files/{id}/image/{size}, wat dieselfde toegang as die lêer kontroleer en dan na die beeldediens herlei. Elke organisasie kan QUIRE_IMAGE_SPECS_PER_HOUR (verstek 2000) nuwe beeld-en-grootte-pare per uur versoek; groottes wat reeds daardie uur vervaardig is, tel nie. Gebruik valkey of postgres vir QUIRE_CACHE_DRIVER met meer as een webhouer sodat die limiet oor hulle geld.

Cloudflare Images hou sy eie kopie van elke oorspronklike wat dit bedien. Wanneer ’n lêer geskrap word, skrap die werker daardie kopie voor die oorspronklike.

Tou

Agtergrondtake gebruik pg-boss in dieselfde Postgres-databasis, dus is daar geen toudiens om te loop of op te stel nie. Take word in dieselfde transaksie geplaas as die verandering wat hulle veroorsaak het, dus kan ’n ineenstorting nie een verloor of dubbel stuur nie. QUIRE_QUEUE_DRIVER is hier pgboss, sy verstek; vercel en cloudflare skuif net ligte kennisgewings- en webhook-aflewerings na platform se eie tou, soos in die Vercel- en Cloudflare-gidse beskryf word, insluitend hoe hul webvlakke hulle in die tou plaas.

E-pos

Stel een van die volgende:

• QUIRE_EMAIL_PROVIDER_CONFIG: ’n JSON-objek wat ’n HTTP-verskaffer en aanmeldbewyse benoem, soos {"provider":"postmark","token":"..."}. Postmark, Amazon SES, Mailgun, SendGrid en Resend word ondersteun.
• QUIRE_SMTP_URL: smtp://user:password@host:587. Net hierdie teiken; bedienerlose teikens blokkeer SMTP.

QUIRE_MAIL_FROM is die sender. Om Quire te probeer, begin die devmail-profiel, stel QUIRE_SMTP_URL=smtp://mailpit:1025 en lees e-pos by http://localhost:8025.

Opsionele dienste

Waarneembaarheid

OTEL_EXPORTER_OTLP_ENDPOINT benoem die versamelaar waarheen elke proses nasporingsdata en maatstawwe stuur; met observability-profiel is dit http://otelcol:4318, en docker/otel-collector.yaml is waar jy uitvoerder vir jou agterkant byvoeg. Webvlak-, werker-, skeduleerder-, inhoud- en collab-prosesse voer afdelings oor OTLP/HTTP uit (webversoeke, tenant-databasistransaksies, werktake en uitgaande oproepe) wanneer dit gestel is, en maatstawwe elke minuut na dieselfde eindpunt (OTEL_METRICS_EXPORTER=none skakel hulle af). OTEL_TRACES_SAMPLER_ARG stel die deel van nasporings wat behou word. Logboeke gaan na standaardafvoer by LOG_LEVEL, en Compose roteer hulle. Nasporings bevat nooit persoonlike data nie.

Streeksuitgaande verkeer (EU-dataverblyf)

QUIRE_REGION=eu sê die stapel bedien Europese Unie-organisasies. Die werker beperk dan elke uitgaande versoek namens ’n organisasie wat aan die EU gepen is tot ’n toelaatlys (21-compliance.md afdeling 8.1). Die toelaatlys bestaan uit gashere wat gekonfigureerde dienste vir die streek verklaar (bergingseindpunt, e-posverskaffer, gehuisveste videoverskaffer, organisasie se eie bergingsteikens, KI-verskaffers en e-posrekening), gashere van enige diens onder ’n geldige afwyking en gashere wat jy in QUIRE_EGRESS_ALLOW_HOSTS lys. ’n Versoek aan enige ander openbare gasheer word geweier voordat dit gestuur word; die weiering word in die organisasie se ouditspoor aangeteken as privacy/egress_refused en onder Nakoming, Dataverblyf gelys.

VK- en VSA-organisasies word nie tot ’n gasheerlys beperk nie; hulle behou diensstreekkontroles. Stel die lys op die werker; die administrasiebladsy lees dit op webvlak om die toelaatlys te wys, dus plaas dit in docker/.env, wat elke diens lees.

Toepassingkontrole gee ’n duidelike fout en ouditinskrywing, maar dit is nie die waarborg nie: kode kan verkeerd wees. Die waarborg is die netwerk. Compose dwing dit nie vir jou af nie. Plaas die worker- en web-dienste vir ’n streekstapel op ’n internal: true-netwerk waarvan die enigste uitgaande roete ’n egress-instaanbediener is (soos Squid of ’n klein tinyproxy-houer) wat dieselfde gashere as QUIRE_EGRESS_ALLOW_HOSTS plus jou gekonfigureerde diensgashere toelaat, en stel HTTPS_PROXY vir daardie dienste. Die verblyfbladsy lys presies die gashere wat die toepassing toelaat, sodat die twee lyste vergelyk kan word.

Gesondheid

docker compose -f docker/compose.yaml ps wys die gesondheid van elke diens.

TLS

Die proxy-diens (Caddy, Apache-2.0, docker/caddy/Caddyfile) is deel van die verstekstapel. Dit antwoord op poorte 80 en 443 en roeteer:

init-env.sh lei QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL en IMGPROXY_URL uit die twee oorspronge af, dus kan hulle nie uit pas raak nie. Wysig hulle saam as jy ’n oorsprong met die hand verander.

Sertifikate volg QUIRE_PROXY_TLS:

• internal (verstek): Caddy se eie sertifikaatowerheid vir localhost, *.localhost en lvh.me. Vertrou sy wortel een keer en blaai dan:

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

  Voeg quire-local-ca.crt by die stelsel- of blaaiervertrouewinkel. curl gebruik dit met --cacert.

• ’n E-posadres: outomatiese ACME-sertifikate (Let’s Encrypt, dan ZeroSSL) vir regte gasheername. DNS vir albei oorspronge en elke tenant-gasheer moet hierheen wys; poorte 80 en 443 moet vanaf die internet bereikbaar wees.

Tenant-gashere kry sertifikate op aanvraag by eerste besoek, en net wanneer web bevestig dat die naam aan hierdie installasie behoort (/tls-allowed, aangevra oor die Compose-netwerk). Geen jokertekensertifikaat of DNS-verskafferinprop is nodig nie, en ’n vreemdeling wat ’n naam na die gasheer laat wys, kan nie sertifikate daarvoor laat aanvra nie. Sertifikate en plaaslike owerheid woon in caddy-data-volume; rugsteun dit saam met die res as jy internal gebruik.

Web vertrou X-Forwarded-For net vanaf die instaanbediener: die instaanbediener het ’n vaste adres (QUIRE_PROXY_ADDRESS, verstek 172.29.64.10) op ’n vaste subnet (QUIRE_COMPOSE_SUBNET), en QUIRE_TRUSTED_PROXY_CIDRS benoem daardie adres. As die subnet met ’n netwerk op die gasheer bots, verander albei en voer docker compose down uit voordat jy up uitvoer.

Agter jou eie omgekeerde instaanbediener

Om eerder ’n bestaande lasbalanseerder of instaanbediener te gebruik, laat proxy weg (docker compose up -d --scale proxy=0) en beëindig TLS voor web (8080), content (8081), collab (1234, websocket) en centrifugo (8000, websocket). Stel openbare adresse in QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN en QUIRE_COLLAB_URL (wss://), en jou instaanbediener se adresreeks in QUIRE_TRUSTED_PROXY_CIDRS.

Probleemoplossing

• init sluit af met “QUIRE_DATABASE_ID is not a UUID”: stel dit met uuidgen.
• web herbegin met “did not start on compose”: die log lys elke instelling wat dit nie kan eerbiedig nie en wat eerder gebruik moet word.
• Om ’n rolwagwoord in .env ná eerste aanvang te verander, doen niks: die inisialisasieskrip loop net een keer. Gebruik ALTER ROLE.
• Oplaaie misluk met ’n skandeerfout terwyl CLAMAV_URL gestel is: ClamAV laai sy handtekeninge by eerste aanvang af, wat ’n paar minute duur.