A Quire telepítése Docker Compose használatával

Ez a teljes termék egyetlen hoston: az LMS, a háttérben végzett munka, a realtime és közös szerkesztési szolgáltatások, valamint a profilok mögött működő opcionális szolgáltatások. A kialakítást a docs/architecture/23-ops.md 2. szakasza ismerteti.

További célkörnyezetek: a Vercel és a Cloudflare Workers csak a webes réteget futtatják. A frissítéseket az upgrade.md, a mentéseket és a visszaállítási próbát a backup-restore.md ismerteti.

Amire szüksége lesz

• Docker Engine 27 vagy újabb, legalább 2.30-as Compose pluginnel.
• 4 CPU-mag és 8 GB memória az alapértelmezett stackhez; 8 mag és 16 GB a --profile full profilhoz (a ClamAV aláírásai önmagukban körülbelül 1,5 GB memóriát foglalnak).
• DNS-név a webes réteghez, és egy második a nem megbízható tartalomhoz. Külön hostnévnek kell lenniük: a SCORM-csomagok és feltöltött HTML-fájlok a tartalomoriginen futnak, hogy soha ne olvashassák az LMS sütijeit.
• Helyi teszthez az lvh.me és *.localhost név feloldása 127.0.0.1 címre; a docker/.env.example ezeket használja. A stack saját proxy szolgáltatása helyi hitelesítésszolgáltatóval, HTTPS-en szolgálja ki mindkettőt, ezért mást nem kell telepíteni (lásd a „TLS” részt).
• A hoston a 80-as és 443-as port legyen szabad (QUIRE_PROXY_HTTP_PORT és QUIRE_PROXY_HTTPS_PORT módosítja őket).

Első indítás

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

A docker/scripts/init-env.sh a docker/.env fájlt a docker/.env.example sablonból készíti el, és minden titkot létrehoz (adatbázisjelszavak, aláíró- és master kulcsok, tartalomindítási kulcspár), valamint az audit-ellenőrzőpont aláírókulcsát a docker/secrets/audit-signing-key.pem fájlba, amelyet a Compose titokként csatol a workerekhez. Csak sh, awk és openssl szükséges hozzá, és nem ír felül meglévő docker/.env fájlt. Mindkét fájlról készítsen másolatot a hoston kívül: QUIRE_MASTER_KEY nélkül a visszaállított adatbázis nem tudja visszafejteni a tárolt hitelesítő adatokat. Ha kézzel szeretné kitölteni a fájlt, futtassa a cp docker/.env.example docker/.env parancsot; a fájl leírja, hogyan kell előállítani az egyes titkokat.

Mindkét originnak https-nek kell lennie: éles környezetben a tartalomszolgáltatás nem fogad sima http-t, és nem osztozhatnak ugyanazon regisztrálható tartományon. A proxy szolgáltatás fejezi be a TLS-kapcsolatot mindkettőhöz (lásd a „TLS” részt); az init-env.sh elutasítja a http:// origint.

A stack kötött sorrendben indul, és minden lépés megvárja az előzőt:

1. A postgres egészséges állapotba kerül. Első indításkor az init szkript (docker/postgres/init/90-passwords.sh) beállítja a négy szerepkör jelszavát.
2. A migrate alkalmazza az összes migrációt, és előkészíti a feladatsort a vezérlőadatbázisban és minden dedikált tenant-adatbázisban, ellenőrzi, hogy megegyeznek-e, majd kilép (lásd docs/ops/upgrade.md). A migrációk minden indításkor lefutnak és idempotensek, ezért frissítéshez új lemezkép és újraindítás kell.
3. Az init (apps/web/src/first-run.ts) bejegyzi az alkalmazás adatbázisát a QUIRE_DATABASE_ID alatt; ha a QUIRE_SETUP_ADMIN_EMAIL be van állítva, létrehozza az első szervezetet és rendszergazdáját is. A bejelentkezési címet és a létrehozott jelszót egyszer írja ki a docker compose logs init naplóba.
4. Elindul a web, content, worker, scheduler, collab és centrifugo.
5. A proxy akkor indul, amikor a web és content egészséges.

Nyissa meg az alkalmazás domainjéhez hozzáfűzött https://demo. címet (az init napló kiírja a pontos bejelentkezési címet), majd jelentkezzen be. Helyi telepítésnél előbb bízzon meg a proxy hitelesítésszolgáltatójában (lásd „TLS”). Módosítsa a létrehozott jelszót a /account/security oldalon.

A szükséges titok nélkül induló folyamat nem indul el, és a naplóban megnevezi a hiányzó beállítást. A rendszer nem indul el félig konfigurált állapotban.

Szolgáltatások és profilok

A --profile full minden opcionális szolgáltatást elindít, kivéve a backup és h5p profilokat. Egy profil indítása: docker compose -f docker/compose.yaml --profile scan up -d. Opcionális szolgáltatások nélkül is működik a Quire, és jelzi, mi hiányzik: scanner nélkül a feltöltések ellenőrzés nélkül kerülnek tárolásra, és erről értesíti a rendszergazdát; Gotenberg nélkül a fájlok előnézet helyett letölthetők; transcoder nélkül a videó az eredeti fájlként játszódik le.

A külső lemezképek és licenckötelezettségeik a docker/third-party-containers.yaml fájlban szerepelnek.

H5P-szolgáltató csatlakoztatása

A Quire nem ágyaz be és nem szállít H5P-futtatókörnyezetet vagy sidecart (ADR 0019). H5P használatához biztosítson saját hosztolt előfizetést vagy külön üzemeltetett H5P-példányt. Regisztrálja a szolgáltatót külső LTI 1.3-eszközként, és adja hozzá a tartalmait a kurzusokhoz eszköztevékenységként. A Quire LTI Assignment and Grade Services (AGS) használatával cserél jegyeket és tevékenység-/értékelési haladást. Ha a szolgáltató xAPI-állításokat is küld, azt külön állítsa be a Quire xAPI állítástárához; az AGS jegy-/haladáscsere nem küld xAPI-állításokat. A H5P-tevékenységeket tartalmazó Moodle-importok jelzik, hogy LTI-eszközkapcsolat szükséges. A H5P-futtatókörnyezet, -szerkesztés, -tartalomtár és próbálkozási előzmények továbbra is a szolgáltató felelőssége.

Ha saját, önállóan üzemeltetett példányt futtat ezen a hoston, állítsa a QUIRE_H5P_IMAGE értékét annak lemezképére, majd indítsa el a h5p profilt. A Compose közzéteszi a QUIRE_H5P_PORT porton (8090), és a h5p-data kötetben tartja az adatokat; a lemezkép és a hozzá kapcsolódó kötelezettségek az Ön felelősségei maradnak.

Beállítások

Minden folyamat a docker/.env fájlt olvassa. A sablon, docker/.env.example, minden beállítást és alapértékét felsorol. A csoportok:

Címek

Titkok

A QUIRE_MASTER_KEY másolatát a hoston kívül őrizze. Nélküle a visszaállított adatbázis nem tudja visszafejteni a benne lévő hitelesítő adatokat.

Adatbázis

A szerepkörjelszavakat csak az adatbáziskötet első létrehozásakor alkalmazzuk. Későbbi cseréjükhöz használja az ALTER ROLE utasítást, majd módosítsa a hozzá tartozó URL-t.

Ha egy fizikai adatbázishoz másik, regisztrált fizikai adatbázist használ, állítsa be annak saját QUIRE_REPORT_DATABASE_URL és DATABASE_URL-hez tartozó quire_report URL-jét a webes és worker-környezetben, majd az adatbázis Jelentési környezeti változó mezőjében adja meg a környezeti változó nevét env:NAME alakban. Ennek ugyanarra az adatbázisra kell mutatnia, mint az alkalmazáskapcsolatnak; lehetőleg olvasási replikára. Minden jelentési felület a tenant saját adatbázisának jelentési URL-jét használja: a jelentéskészítő és a mentett jelentések, az ütemezett kézbesítések, a jelentések exportjai, az analitika, az auditnapló, a REST audit-erőforrásai és az asszisztens auditkeresése. Egyik sem használja egy másik adatbázis URL-jét. Ha nincs jelentési URL, a szokásos jelentések az adott adatbázis alkalmazás-URL-jét használják; az analitika és az auditolvasás megtagadja a hozzáférést, mert az alkalmazásszerepkör nem olvashatja az auditnaplót.

Illesztőprogramok

Az ebben a kiadásban nem szereplő illesztőprogram-érték esetén a webes szolgáltatás induláskor elutasítja a beállítást, és megnevezi azt ahelyett, hogy alapértelmezettet választana.

Képek

A képeket rögzített méretben kérheti a /api/files/{id}/image/{size} útvonalon. A rendszer ugyanazt a hozzáférést ellenőrzi, majd átirányít. A szervezet óránként legfeljebb QUIRE_IMAGE_SPECS_PER_HOUR (alapértelmezés szerint 2000) új kép/méret pár feldolgozását kérheti; a már elkészültek nem számítanak bele. Egynél több webkonténer esetén használja a valkey vagy postgres lehetőséget, és állítsa be ennek megfelelően a QUIRE_CACHE_DRIVER értékét a gyorsítótár megosztásához.

A Cloudflare Images saját másolatot tárol; a worker az eredeti törlése előtt ezt a másolatot is törli.

Feladatsor

A háttérfeladatok a pg-boss szolgáltatást használják ugyanazon a Postgres-adatbázison; nincs szükség külön feladatsor-szolgáltatásra vagy annak beállítására. A feladat ugyanabban a tranzakcióban kerül sorba, mint az azt kiváltó módosítás, így összeomláskor nem vész el és nem duplázódik meg. A QUIRE_QUEUE_DRIVER esetén a pgboss az alapértelmezett. A vercel és cloudflare értékek csak a könnyű értesítési és webhook-kézbesítéseket helyezik át a platform feladatsorába. A Vercelről és a Cloudflare-ről szóló útmutató ismerteti ezeket, illetve azt, hogyan kerülnek sorba a feladatok.

E-mail

Állítsa be az alábbiak egyikét:

• QUIRE_EMAIL_PROVIDER_CONFIG: JSON-objektum, amely megadja a HTTP-szolgáltatót és a hitelesítő adatokat, például {"provider":"postmark","token":"..."}. Támogatott szolgáltatók: Postmark, Amazon SES, Mailgun, SendGrid és Resend.
• QUIRE_SMTP_URL: például smtp://user:password@host:587; ez a célkörnyezet azonban SMTP-t blokkoló kiszolgáló nélküli platform.

A feladó címét a QUIRE_MAIL_FROM beállítással adja meg. Teszteléshez indítsa el a devmail profilt, állítsa be a QUIRE_SMTP_URL=smtp://mailpit:1025 értéket, és a leveleket a http://localhost:8025 címen olvassa el.

Nem kötelező szolgáltatások

Megfigyelhetőség

Az OTEL_EXPORTER_OTLP_ENDPOINT a nyomkövetéseket és metrikákat fogadó gyűjtőt nevezi meg. A observability profillal ez a http://otelcol:4318; a docker/otel-collector.yaml fájlban adjon hozzá háttérrendszer-exportert. Beállítása esetén a web, a worker, az ütemező, a tartalomszolgáltatás és a közös szerkesztés OTLP/HTTP-n küld szakaszokat (webes kérések, tenant-adatbázis tranzakciói, worker-feladatok és kimenő hívások), valamint percenként metrikákat. A metrikák letiltásához állítsa az OTEL_METRICS_EXPORTER=none értéket. Az OTEL_TRACES_SAMPLER_ARG adja meg a nyomkövetések mintavételezési arányát. A naplók a szabványos kimenetre kerülnek a LOG_LEVEL szinttel, a Compose pedig forgatja őket. A nyomkövetések nem tartalmaznak személyes adatokat.

Regionális kimenő forgalom (EU-adattárolás)

A QUIRE_REGION=eu azt jelzi, hogy a stack EU-s szervezeteket szolgál ki. Az EU-régióhoz rögzített szervezeteknél a worker a kimenő kéréseket az engedélyezőlistára korlátozza (21-compliance.md, 8.1. szakasz). Az engedélyezőlista a régióban konfigurált szolgáltatások által megadott hosztokat tartalmazza: tárolási végpontok, e-mail-szolgáltató, hosztolt videó, szervezeti tárolási célpontok, AI-szolgáltatók és e-mail-fiók, aktív eltéréssel működő szolgáltatások, valamint a QUIRE_EGRESS_ALLOW_HOSTS értékei. A többi nyilvános hosztra irányuló kérést küldés előtt elutasítja, és az elutasítást a privacy/egress_refused eseménynél naplózza; az engedélyezett hosztok a Megfelelőség, Adattárolás részen láthatók.

Az Egyesült Királyság és az Egyesült Államok régiói nem tartoznak a hosztlistás korlátozás alá, de a szolgáltatások régióellenőrzését ott is tartsa be. Állítsa be ezt a worker számára; a rendszergazdai felület a webes rétegtől olvassa az értéket. Helyezze a docker/.env fájlba, hogy minden szolgáltatás olvashassa.

Az alkalmazás ellenőrzése világos hibát és auditbejegyzést ad, de nem jelent garanciát: a kód hibás lehet. A hálózati korlátozás nyújt garanciát. A Compose ezt önmagában nem kényszeríti ki. Regionális stack esetén tegye a worker és web szolgáltatást internal: true hálózatra, amelynek egyetlen kifelé vezető útvonala az olyan hosztokat engedélyező kimenő proxy, amelyeket a QUIRE_EGRESS_ALLOW_HOSTS és a konfigurált szolgáltatások felsorolnak (például Squid vagy tinyproxy). Állítsa be a HTTPS_PROXY értékét. Az Adattárolás oldal felsorolja az engedélyezett hosztokat, így összevetheti őket.

Állapotellenőrzés

A docker compose -f docker/compose.yaml ps paranccsal megtekintheti az állapotot.

TLS

Az alapértelmezett stack proxy szolgáltatása a Caddy (docker/caddy/Caddyfile, Apache-2.0 licenc). A 80-as és 443-as porton figyel, és az alábbi útvonalakat irányítja:

Az init-env.sh az originek alapján vezeti le a QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL és IMGPROXY_URL értékét, hogy azok ne térhessenek el egymástól. Módosításkor hangolja össze őket.

A tanúsítványokat a QUIRE_PROXY_TLS beállítás határozza meg:

• internal (alapértelmezett): a Caddy helyi hitelesítésszolgáltatót használ a localhost, a *.localhost és az lvh.me esetében. Egyszer bízzon meg benne, majd futtassa ezt:

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

  Adja hozzá a quire-local-ca.crt tanúsítványt a rendszer vagy a böngésző megbízható tanúsítványaihoz; a curl esetében használja a --cacert kapcsolót.

• E-mail-cím: automatikus ACME-tanúsítványok (először Let’s Encrypt, majd ZeroSSL) valódi hosztnevekhez. Az originek és a tenant-hosztok DNS-rekordjai erre a hostra mutassanak, a portok pedig legyenek elérhetők.

A tenant-hoszt tanúsítványát igény szerint, az első látogatáskor állítja ki a rendszer, de csak akkor, ha a webes szolgáltatás a Compose-hálózaton keresztüli /tls-allowed végponton engedélyezi. Nincs wildcard vagy DNS-bővítmény; véletlenszerű hosztra mutatással nem lehet tanúsítványt kérni. A tanúsítványok és a hitelesítésszolgáltató adatai a caddy-data kötetben vannak; internal használat esetén ezt is mentse a többi adattal együtt.

A webes szolgáltatás csak a proxytól bízik meg az X-Forwarded-For fejlécben: a rögzített QUIRE_PROXY_ADDRESS alapértéke 172.29.64.10, a rögzített QUIRE_COMPOSE_SUBNET hálózaton; a QUIRE_TRUSTED_PROXY_CIDRS ezt nevezi meg. Ha a hálózati tartomány ütközik, módosítsa mindkettőt, majd futtassa a docker compose down parancsot az up előtt.

Saját fordított proxy mögött

Saját terheléselosztó vagy proxy használatához hagyja ki a proxy szolgáltatást a docker compose up -d --scale proxy=0 paranccsal, és a TLS-t a web (8080), content (8081), collab (1234, websocket) és centrifugo (8000, websocket) előtt fejezze be. Állítsa be a QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN és QUIRE_COLLAB_URL (wss:// értékkel) nyilvános címeit, valamint a proxy címtartományát a QUIRE_TRUSTED_PROXY_CIDRS értékeként.

Hibaelhárítás

• Az init ezzel lép ki: „QUIRE_DATABASE_ID is not a UUID”: állítsa be uuidgen segítségével.
• A web újraindul, és ezt írja: „did not start on compose”: a napló felsorolja a nem kezelhető beállításokat és a helyettesítőiket.
• A .env fájlban megváltoztatott szerepkörjelszó az első indítás után nem hat: az init csak egyszer fut le; használja az ALTER ROLE utasítást.
• A feltöltés vizsgálata hibát jelez a CLAMAV_URL használatakor: a ClamAV az első induláskor tölti le az aláírásokat, ami több percig tarthat.