Instalace Quire pomocí Docker Compose

Celý produkt běží na jednom hostiteli: LMS, úlohy na pozadí, služby realtime a společných úprav i všechny volitelné služby za profily. Architektura je popsána v části 2 dokumentu docs/architecture/23-ops.md.

Další cíle: Vercel a Cloudflare Workers provozují pouze webovou vrstvu. Aktualizace popisuje upgrade.md; zálohy a zkoušku obnovy najdete v backup-restore.md.

Co budete potřebovat

• Docker Engine 27 nebo novější a plugin Compose 2.30 nebo novější.
• 4 jádra CPU a 8 GB paměti pro výchozí stack; s --profile full 8 jader a 16 GB (jen podpisy ClamAV zabírají přibližně 1,5 GB).
• DNS název pro webovou vrstvu a druhý pro nedůvěryhodný obsah. Musí jít o různé hostitele: balíčky SCORM a nahrané HTML běží z originu obsahu, takže nikdy nemohou číst soubory cookie LMS.
• Pro místní test se lvh.me a *.localhost překládají na 127.0.0.1; používá je docker/.env.example. Vlastní služba proxy ve stacku poskytuje obě adresy přes https s místní certifikační autoritou, takže není třeba nic dalšího instalovat (viz „TLS“).
• Na hostiteli musí být volné porty 80 a 443; změní je nastavení QUIRE_PROXY_HTTP_PORT a QUIRE_PROXY_HTTPS_PORT.

První spuštění

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

Skript docker/scripts/init-env.sh vytvoří soubor docker/.env podle šablony docker/.env.example s vygenerovanými tajnými údaji (hesly databáze, podpisovým a hlavním klíčem, párem klíčů pro spuštění obsahu) i podpisovým klíčem kontrolního bodu auditu v docker/secrets/audit-signing-key.pem; Compose ho připojí do workerů jako tajný údaj. Potřebuje pouze sh, awk a openssl a odmítne přepsat existující docker/.env. Oba soubory zkopírujte mimo hostitele: bez QUIRE_MASTER_KEY obnovená databáze nedokáže rozšifrovat uložené přihlašovací údaje. Chcete-li soubor vyplnit ručně, použijte cp docker/.env.example docker/.env; soubor popisuje vytvoření každého tajného údaje.

Oba originy musí používat https: služba content v produkčním prostředí odmítá prosté http a originy nesmějí sdílet registrovatelnou doménu. Služba proxy ukončuje TLS pro oba (viz „TLS“); init-env.sh odmítne origin začínající na http://.

Stack se spouští v pevně daném pořadí a každý krok počká na předchozí:

1. postgres přejde do zdravého stavu. Při úplně prvním spuštění nastaví jeho inicializační skript (docker/postgres/init/90-passwords.sh) čtyři hesla rolí.
2. migrate použije všechny migrace a připraví frontu úloh v řídicí databázi i ve všech vyhrazených databázích tenantů, ověří, že jsou ve shodě, a potom skončí (docs/ops/upgrade.md). Migrace se spouštějí při každém startu a jsou idempotentní, takže aktualizace vyžaduje nový image a restart.
3. init (apps/web/src/first-run.ts) zaznamená aplikační databázi pod QUIRE_DATABASE_ID a při nastavení QUIRE_SETUP_ADMIN_EMAIL vytvoří první organizaci a jejího administrátora. Přihlašovací adresa a vygenerované heslo se jednou vypíší v docker compose logs init.
4. Spustí se web, content, worker, scheduler, collab a centrifugo.
5. proxy začne běžet poté, co budou web a content ve zdravém stavu.

Otevřete https://demo. následované doménou aplikace (protokol init vypíše přesnou přihlašovací adresu) a přihlaste se. Při místní instalaci nejprve důvěřujte certifikační autoritě proxy (viz „TLS“). Vygenerované heslo změňte na /account/security.

Proces spuštěný bez povinného tajného údaje odmítne běžet a v protokolu pojmenuje chybějící nastavení. Nic se nespustí s neúplnou konfigurací.

Služby a profily

Profil --profile full spustí všechny volitelné služby kromě backup a h5p. Jednu službu spustíte příkazem docker compose -f docker/compose.yaml --profile scan up -d. Quire funguje i bez volitelné služby a oznámí, co chybí: bez skeneru se soubory ukládají nezkontrolované a administrátor dostane upozornění; bez Gotenbergu se soubory nabízejí ke stažení místo náhledu; bez transcoderu se video přehrává jako původní soubor.

Všechny image třetích stran a související licenční povinnosti uvádí docker/third-party-containers.yaml.

Připojení poskytovatele H5P

Quire nevkládá ani nedodává běhové prostředí H5P nebo sidecar (ADR 0019). Pokud používáte H5P, pořiďte si vlastní hostované předplatné nebo provozujte samostatně vlastní self-hosted instanci H5P. Zaregistrujte poskytovatele jako externí nástroj LTI 1.3 a přidejte jeho obsah do kurzů jako aktivity nástroje. Quire si přes LTI Assignment and Grade Services (AGS) vyměňuje známky a průběh aktivit a hodnocení. Pokud poskytovatel odesílá také xAPI statements, nakonfigurujte to samostatně pro úložiště xAPI statements v Quire; výměna známek a průběhu přes AGS xAPI statements neodesílá. Importy z Moodle označují aktivity H5P jako vyžadující připojení nástroje LTI. Za běhové prostředí H5P, tvorbu obsahu, banku obsahu a historii pokusů nadále odpovídá poskytovatel.

Chcete-li na tomto hostiteli provozovat vlastní self-hosted instanci, nastavte QUIRE_H5P_IMAGE na její image a spusťte profil h5p. Compose ji zveřejní na QUIRE_H5P_PORT (8090) a její data uchová ve svazku h5p-data; image i veškeré související povinnosti zůstávají na vás.

Nastavení

Každý proces načítá docker/.env. Šablona docker/.env.example uvádí všechna nastavení a jejich výchozí hodnoty. Skupiny:

Adresy

Tajné údaje

Kopii QUIRE_MASTER_KEY uchovávejte mimo tohoto hostitele. Databáze obnovená bez něj nedokáže rozšifrovat své přihlašovací údaje.

Databáze

Hesla rolí se použijí pouze při prvním vytvoření databázového svazku. Chcete-li je později změnit, použijte ALTER ROLE a aktualizujte odpovídající URL.

QUIRE_REPORT_DATABASE_URL se používá pro fyzickou databázi nastavenou v DATABASE_URL. U každé další registrované fyzické databáze nastavte její vlastní připojovací URL quire_report v prostředí webu i workeru a název proměnné zadejte v poli Reporting environment variable dané databáze jako env:NAME. Reference musí ukazovat na stejnou databázi jako její aplikační připojení, ideálně na její repliku pro čtení. Každý reportovací povrch přejde spolu s tenantem k reportovacímu připojení vlastní databáze: tvůrce reportů a uložené reporty, plánované doručování, exporty reportů, analytika, auditní protokol, auditní prostředky REST i auditní vyhledávání asistenta. Žádný z nich nikdy nepoužije reportovací URL jiné databáze. Pokud databáze nemá reportovací připojení, běžné reporty používají její vlastní aplikační připojení; analytika a čtení auditu se odmítnou a vysvětlí proč, protože aplikační role nemůže číst auditní stopu.

Ovladače

Pokud tato verze ovladač neobsahuje, webová vrstva ho při spuštění odmítne a pojmenuje příslušné nastavení, místo aby ho potichu nahradila výchozí hodnotou.

Obrázky

Stránky požadují obrázky ve čtyřech pevně daných velikostech přes /api/files/{id}/image/{size}. Endpoint ověří stejný přístup jako k samotnému souboru a přesměruje na obrazovou službu. Každá organizace může za hodinu požadovat QUIRE_IMAGE_SPECS_PER_HOUR (výchozí hodnota 2000) nových kombinací obrázku a velikosti; velikosti vytvořené v danou hodinu se nezapočítávají. Při více webových kontejnerech použijte valkey nebo postgres pro QUIRE_CACHE_DRIVER, aby limit platil napříč nimi.

Cloudflare Images uchovává vlastní kopii každého originálu, který poskytuje. Při smazání souboru worker nejprve odstraní tuto kopii a až potom originál.

Fronta

Úlohy na pozadí používají pg-boss ve stejné databázi Postgres, takže není potřeba provozovat ani konfigurovat samostatnou frontu. Úlohy se zařazují ve stejné transakci jako změna, která je vyvolala, takže je pád nemůže ztratit ani odeslat dvakrát. Výchozí ovladač QUIRE_QUEUE_DRIVER je zde pgboss; vercel a cloudflare přesunou pouze lehké doručování oznámení a webhooků do vlastní fronty platformy. Příručky pro Vercel a Cloudflare popisují, jak jejich webové vrstvy úlohy zařazují.

E-mail

Nastavte jednu z možností:

• QUIRE_EMAIL_PROVIDER_CONFIG: objekt JSON s názvem HTTP poskytovatele a jeho přístupovými údaji, například {"provider":"postmark","token":"..."}. Podporovány jsou Postmark, Amazon SES, Mailgun, SendGrid a Resend.
• QUIRE_SMTP_URL: smtp://user:password@host:587. Funguje pouze pro tento cíl; serverless cíle blokují SMTP.

Odesílatele určuje QUIRE_MAIL_FROM. Chcete-li Quire vyzkoušet, spusťte profil devmail, nastavte QUIRE_SMTP_URL=smtp://mailpit:1025 a poštu čtěte na http://localhost:8025.

Volitelné služby

Observabilita

OTEL_EXPORTER_OTLP_ENDPOINT určuje collector, kterému každý proces posílá trasování a metriky. S profilem observability je to http://otelcol:4318; exportér pro váš backend přidejte do docker/otel-collector.yaml. Webová vrstva, worker, scheduler, content a collab při nastavení exportují přes OTLP/HTTP rozsahy (webové požadavky, transakce databází tenantů, úlohy workeru a odchozí volání) a každou minutu metriky na stejný endpoint (OTEL_METRICS_EXPORTER=none je vypne). OTEL_TRACES_SAMPLER_ARG určuje podíl uchovávaných trasování. Protokoly se zapisují na standardní výstup s úrovní LOG_LEVEL; Compose je rotuje. Trasování nikdy neobsahuje osobní údaje.

Oblastní odchozí provoz (datová rezidence EU)

QUIRE_REGION=eu označuje, že stack obsluhuje organizace v Evropské unii. Worker pak veškerá odchozí volání pro organizaci připnutou k EU omezuje na seznam povolených hostitelů (21-compliance.md, část 8.1). Seznam tvoří hostitelé, které pro danou oblast deklarují nakonfigurované služby (endpoint úložiště, poskytovatel e-mailu a hostovaného videa, vlastní úložiště organizace, poskytovatelé AI a e-mailový účet), hostitelé služeb pod aktivní výjimkou a hostitelé uvedení v QUIRE_EGRESS_ALLOW_HOSTS. Požadavek na jakéhokoli jiného veřejného hostitele se před odesláním odmítne, odmítnutí se zapíše do auditní stopy organizace jako privacy/egress_refused a zobrazí se v části Soulad, Datová rezidence.

Organizace ve Spojeném království a USA se neomezují seznamem hostitelů; nadále se u nich kontrolují oblasti služeb. Nastavte seznam na workeru. Stránka správce ho na webové vrstvě čte a zobrazuje jako seznam povolených, proto ho uložte do docker/.env, který načítá každá služba.

Kontrola aplikace poskytuje srozumitelnou chybu a auditní záznam, ale nepředstavuje záruku: kód se může mýlit. Záruku zajišťuje síť. Compose ji za vás nevynucuje. U oblastního stacku umístěte služby worker a web do sítě internal: true, jejíž jedinou cestou ven je odchozí proxy (například Squid nebo kontejner tinyproxy), která povoluje stejné hostitele jako QUIRE_EGRESS_ALLOW_HOSTS a hostitele nakonfigurovaných služeb. Těmto službám nastavte HTTPS_PROXY. Stránka datové rezidence uvádí přesné hostitele povolené aplikací, takže můžete oba seznamy porovnat.

Zdraví služby

Příkaz docker compose -f docker/compose.yaml ps zobrazí stav každé služby.

TLS

Služba proxy (Caddy, Apache-2.0, docker/caddy/Caddyfile) je součástí výchozího stacku. Odpovídá na portech 80 a 443 a směruje:

Skript init-env.sh odvodí z obou originů hodnoty QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL a IMGPROXY_URL, aby se nemohly rozejít. Pokud origin měníte ručně, upravte odpovídající hodnoty společně.

Certifikáty se řídí nastavením QUIRE_PROXY_TLS:

• internal (výchozí): vlastní certifikační autorita Caddy pro localhost, *.localhost a lvh.me. Jednou důvěřujte jejímu kořenovému certifikátu a potom přejděte na stránku:

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

  Přidejte quire-local-ca.crt do úložiště důvěryhodných certifikátů systému nebo prohlížeče. Příkaz curl ho použije s volbou --cacert.

• E-mailová adresa: automatické certifikáty ACME (Let’s Encrypt a potom ZeroSSL) pro skutečné názvy hostitelů. DNS pro oba originy a každý hostitel tenanta musí ukazovat sem a porty 80 a 443 musí být dostupné z internetu.

Certifikáty pro hostitele tenantů se vydávají na vyžádání při první návštěvě, pouze pokud webová vrstva potvrdí, že název patří této instalaci (/tls-allowed, dotazované v síti Compose). Není potřeba wildcard certifikát ani plugin poskytovatele DNS; cizí osoba nemůže nasměrováním názvu na hostitele vynutit žádost o certifikát. Certifikáty a místní autorita jsou ve svazku caddy-data; používáte-li internal, zálohujte ho společně s ostatními.

Webová vrstva důvěřuje hlavičce X-Forwarded-For pouze od proxy: proxy má pevnou adresu (QUIRE_PROXY_ADDRESS, výchozí 172.29.64.10) na pevném podsíťovém rozsahu (QUIRE_COMPOSE_SUBNET) a QUIRE_TRUSTED_PROXY_CIDRS tuto adresu určuje. Pokud se podsíť překrývá se sítí hostitele, změňte obě nastavení a spusťte docker compose down před dalším up.

Za vlastní reverzní proxy

Chcete-li použít load balancer nebo proxy, které už provozujete, vynechte službu proxy (docker compose up -d --scale proxy=0) a ukončete TLS před službami web (8080), content (8081), collab (1234, websocket) a centrifugo (8000, websocket). Nastavte veřejné adresy v QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN a QUIRE_COLLAB_URL (wss://) a rozsah adres vaší proxy v QUIRE_TRUSTED_PROXY_CIDRS.

Řešení potíží

• init skončí s chybou „QUIRE_DATABASE_ID is not a UUID“: nastavte hodnotu příkazem uuidgen.
• web se restartuje s chybou „did not start on compose“: protokol vypíše každé nastavení, které nelze použít, a doporučenou náhradu.
• Změna hesla role v .env po prvním spuštění nic neudělá: inicializační skript běží jen jednou. Použijte ALTER ROLE.
• Nahrávání selhává kvůli skenování, přestože je nastaveno CLAMAV_URL: ClamAV při prvním spuštění stahuje podpisy, což trvá několik minut.