Pag-instalar sa Quire gamit ang Docker Compose

Ang tibuok produkto modagan sa usa ka host: ang LMS, mga buluhaton niini sa background, mga serbisyo sa realtime ug hiniusang pag-edit, ug ang tanang opsyonal nga serbisyo nga anaa luyo sa profile. Gihulagway ang disenyo sa seksiyon 2 sa docs/architecture/23-ops.md.

Ang ubang target: web tier ra ang gipadagan sa Vercel ug Cloudflare Workers. Ania sa upgrade.md ang pag-upgrade, ug ania sa backup-restore.md ang backup ug restore drill.

Mga kinahanglan

• Docker Engine 27 o mas bag-o ug Compose plugin 2.30 o mas bag-o.
• 4 ka CPU core ug 8 GB nga memorya para sa default stack; 8 ka core ug 16 GB kon gamiton ang --profile full (mga 1.5 GB nga signature ra ang gikuha sa ClamAV).
• Usa ka DNS name para sa web tier ug ikaduha para sa untrusted content. Kinahanglan lahi ang host niini: modagan ang SCORM package ug gi-upload nga HTML sa content origin aron dili gayod nila mabasa ang cookie sa LMS.
• Para sa lokal nga pagsulay, ang lvh.me ug *.localhost motudlo sa 127.0.0.1, nga mao ang gigamit sa docker/.env.example. Giserbisyo sa kaugalingong proxy service sa stack ang duha pinaagi sa https ug lokal nga certificate authority, busa walay laing kinahanglan i-install (tan-awa ang “TLS”).
• Libre ang port 80 ug 443 sa host (QUIRE_PROXY_HTTP_PORT ug QUIRE_PROXY_HTTPS_PORT ang makapausab niini).

Unang pagdagan

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

Mohimo sa docker/scripts/init-env.sh ang docker/.env gikan sa docker/.env.example, ug sulod niini ang matag nahimong sekreto (mga password sa database, signing key ug master key, pares sa content launch key) ug audit checkpoint signing key sa docker/secrets/audit-signing-key.pem, nga ikabitan sa Compose sa mga worker isip sekreto. sh, awk ug openssl ra ang gikinahanglan niini, ug dili niini tugotan nga patungan ang kasamtangang docker/.env. Kopyaha sa gawas sa host kining duha ka file: kon walay QUIRE_MASTER_KEY, dili ma-decrypt sa gi-restore nga database ang tinipig nga credential niini. Kon mano-mano nimong sulatan ang file, gamita hinuon ang cp docker/.env.example docker/.env; gisulti sa file kon unsaon paghimo sa matag sekreto.

Kinahanglan https ang duha ka origin: dili dawaton sa content service ang plain http sa production, ug dili puwedeng managsama ang registrable domain niini. Tapuson sa proxy service ang TLS para sa duha (tan-awa ang “TLS”); dili dawaton sa init-env.sh ang origin nga http://.

Magsugod ang stack sa tinong han-ay, ug maghulat ang matag lakang nga mahuman ang nauna:

1. Mahimong himsog ang postgres. Sa unang pagsugod gayod, itakda sa init script niini (docker/postgres/init/90-passwords.sh) ang upat ka role password.
2. Ipatuman sa migrate ang matag migration ug i-bootstrap ang job queue sa control database ug sa matag kaugalingong tenant database, susihon nga nagkauyon silang tanan, unya mohunong (docs/ops/upgrade.md). Modagan ang migration sa matag pagsugod ug idempotent kini, busa bag-ong image ug restart ra ang gikinahanglan sa upgrade.
3. Irekord sa init (apps/web/src/first-run.ts) ang application database ubos sa QUIRE_DATABASE_ID ug, kon itakda ang QUIRE_SETUP_ADMIN_EMAIL, himoon niini ang unang organisasyon ug administrador niini. Iimprinta kausa ang sign-in address ug hinimo nga password sa docker compose logs init.
4. Magsugod ang web, content, worker, scheduler, collab ug centrifugo.
5. Magsugod ang proxy kon himsog na ang web ug content.

Ablihi ang https://demo. nga gisundan sa domain sa imong aplikasyon (ipakita sa init log ang eksaktong sign-in address), ug sign in. Sa lokal nga instalasyon, saligi una ang certificate authority sa proxy (tan-awa ang “TLS”). Usba ang gihimo nga password sa /account/security.

Dili mosugod ang prosesong walay gikinahanglang sekreto ug nganlan niini sa log ang kulang nga setting. Dili gayod mosugod ang stack nga kulang ang configuration.

Mga serbisyo ug profile

Sugdan sa --profile full ang matag opsyonal nga serbisyo gawas sa backup ug h5p. Sugdi ang usa pinaagi sa docker compose -f docker/compose.yaml --profile scan up -d. Molihok gihapon ang Quire kon walay opsyonal nga serbisyo ug ipahibalo niini kon unsay kulang: kon walay scanner, tipigan ang mga upload nga walay scan ug pahibaloon ang administrador; kon walay Gotenberg, i-download hinuon ang file imbis nga magpakita og preview; kon walay transcoder, ipatugtog ang video isip orihinal nga file.

Gilista sa docker/third-party-containers.yaml ang matag third-party image ug obligasyon niini sa lisensiya.

Pagkonektar og H5P provider

Dili i-embed o iapil sa Quire ang H5P runtime o sidecar (ADR 0019). Kon mogamit ka og H5P, pagkuha sa kaugalingon nimong hosted subscription o paandara ang kaugalingon nimong self-hosted nga H5P instance nga bulag sa Quire. Irehistro kana nga provider isip LTI 1.3 external tool ug idugang ang sulod niini sa mga kurso isip tool activity. Magbaylo ang Quire og grado ug kausaban sa activity/grading pinaagi sa LTI Assignment and Grade Services (AGS). Kon magpadala usab ang provider og xAPI statement, i-configure kini nga bulag alang sa xAPI statement store sa Quire; dili ipadala sa pagbaylo sa grado/progress sa AGS ang xAPI statement. Ireport sa Moodle import nga nagkinahanglan og koneksiyon sa LTI tool ang mga H5P activity. Responsibilidad gihapon sa provider ang H5P runtime, paghimo sa sulod, content bank ug kasaysayan sa mga attempt niini.

Aron ipadagan ang kaugalingon nimong self-hosted nga instance niining host, itudlo ang QUIRE_H5P_IMAGE sa image niini ug sugdi ang h5p profile. I-publish kini sa Compose sa QUIRE_H5P_PORT (8090) ug ibutang ang datos niini sa h5p-data volume; imo gihapon ang image ug mga obligasyon niini.

Mga setting

Basahon sa matag proseso ang docker/.env. Gilista sa template nga docker/.env.example ang matag setting ug default niini. Mao kini ang mga grupo:

Mga address

Mga sekreto

Tipigi sa laing dapit gawas niini nga host ang kopya sa QUIRE_MASTER_KEY. Dili ma-decrypt sa database nga gi-restore nga walay yawe niini ang credential nga anaa niini.

Database

Itakda ang password sa role sa unang paghimo lang sa database volume. Aron usbon kini unya, gamita ang ALTER ROLE ug i-update dayon ang katugbang nga URL.

Gigamit ang QUIRE_REPORT_DATABASE_URL para sa pisikal nga database nga gi-configure sa DATABASE_URL. Para sa laing narehistrong pisikal nga database, itakda ang kaugalingong quire_report connection URL niini sa palibot sa web ug worker, unya ibutang ang ngalan sa variable sa field nga Reporting environment variable sa maong database isip env:NAME. Kinahanglan magtudlo ang reference sa samang database sa app connection niini, mas maayo kon read replica. Sundon sa matag report surface ang tenant ngadto sa report connection sa kaugalingong database niini: report builder ug gitipig nga report, gieskedyul nga delivery, report export, analytics, audit log, REST audit resource ug audit search sa assistant. Dili gayod manghulam ang bisan hain niini sa report URL sa laing database. Kon walay report connection ang database, modagan ang ordinaryong report sa kaugalingong application connection niini, apan isalikway ang analytics ug matag audit read ug ipahibalo ang hinungdan, kay dili makabasa sa audit trail ang application role.

Mga driver

Kon wala maglakip ang release niining bili sa driver, isalikway kini sa pagsugod sa web tier ug nganlan ang setting, imbis nga ilisan lang sa default nga walay pahibalo.

Mga image

Mangayo ang mga panid og image sa upat ka fixed nga gidak-on pinaagi sa /api/files/{id}/image/{size}; susihon niini ang samang access sa file mismo unya i-redirect ngadto sa image service. Mahimong mangayo ang matag organisasyon og QUIRE_IMAGE_SPECS_PER_HOUR (default 2000) ka bag-ong pares sa image ug gidak-on kada oras; dili iapil ang gidak-on nga nahimo na niadtong orasa. Kon daghan og usa ka web container, gamita ang valkey o postgres para sa QUIRE_CACHE_DRIVER aron magamit ang limit sa matag container.

Magtipig ang Cloudflare Images og kaugalingong kopya sa matag orihinal nga i-serve niini. Kon tangtangon ang file, tangtangon una sa worker kana nga kopya sa dili pa ang orihinal.

Queue

Gigamit sa background job ang pg-boss sa samang Postgres database, busa walay queue service nga ipadagan o i-configure. I-enqueue ang job sa samang transaction sa kausaban nga maoy hinungdan niini, busa dili kini mawala o madoble tungod sa crash. Default ang QUIRE_QUEUE_DRIVER nga pgboss dinhi; ibalhin sa vercel ug cloudflare ang gaan nga notification ug webhook delivery ngadto sa kaugalingong queue sa platform, ug gihulagway sa mga giya sa Vercel ug Cloudflare kini ug paagi sa pag-enqueue niini sa ilang web tier.

Email

Pilia ang usa niini:

• QUIRE_EMAIL_PROVIDER_CONFIG: JSON object nga nagngalan sa HTTP provider ug credential niini, sama sa {"provider":"postmark","token":"..."}. Gisuportahan ang Postmark, Amazon SES, Mailgun, SendGrid ug Resend.
• QUIRE_SMTP_URL: smtp://user:password@host:587. Niining target ra kini magamit; gibabagan sa serverless target ang SMTP.

Ang QUIRE_MAIL_FROM mao ang nagpadala. Aron sulayan ang Quire, sugdi ang devmail profile, itakda ang QUIRE_SMTP_URL=smtp://mailpit:1025, ug tan-awa ang mail sa http://localhost:8025.

Opsyonal nga serbisyo

Observability

Nagtudlo ang OTEL_EXPORTER_OTLP_ENDPOINT sa collector nga padad-an sa matag proseso og trace ug metric; kon gamiton ang observability profile, mao kini ang http://otelcol:4318, ug dugangan didto sa docker/otel-collector.yaml ang exporter para sa imong backend. I-export sa web tier, worker, scheduler, content ug collab ang span pinaagi sa OTLP/HTTP (web request, tenant database transaction, worker job ug outgoing call) kon itakda kini; ipadala usab matag minuto ang metric ngadto sa samang endpoint (OTEL_METRICS_EXPORTER=none ang mopalong niini). Itakda sa OTEL_TRACES_SAMPLER_ARG ang proporsiyon sa trace nga tipigan. Ipadala ang log sa standard output sa LOG_LEVEL, ug i-rotate kini sa Compose. Dili gayod adunay personal nga datos ang trace.

Regional egress (pagpabilin sa datos sa EU)

Nagpasabot ang QUIRE_REGION=eu nga ang mga organisasyon sa European Union ang serbisyohan sa stack. Ibutang unya sa worker sa allowlist ang matag outgoing request para sa organisasyong naka-pin sa EU (21-compliance.md seksiyon 8.1). Naglangkob ang allowlist sa mga host nga gideklara sa mga na-configure nga serbisyo para sa maong rehiyon (endpoint sa storage, email provider, hosted video provider, kaugalingong storage target sa organisasyon, AI provider ug email account), mga host sa bisan unsang serbisyo nga ubos sa aktibong derogation, ug mga host nga gilista sa QUIRE_EGRESS_ALLOW_HOSTS. Isalikway sa dili pa ipadala ang request sa bisan unsang laing public host, isulat sa audit trail sa organisasyon ang pagdumili isip privacy/egress_refused, ug ilista kini ubos sa Compliance, Data residency.

Dili ibutang sa host list ang mga organisasyon sa UK ug US; ipadayon hinuon ang pagsusi sa rehiyon sa serbisyo. Itakda ang listahan sa worker; basahon kini sa panid sa admin sa web tier aron ipakita ang allowlist, busa ibutang kini sa docker/.env nga basahon sa matag serbisyo.

Maghatag og klarong sayop ug audit entry ang pagsusi sa aplikasyon, apan dili kini ang garantiya: mahimong masayop ang code. Ang garantiya anaa sa network. Dili kini ipatuman sa Compose para kanimo. Para sa regional stack, ibutang ang serbisyo nga worker ug web sa network nga internal: true ug himoa nga ang bugtong ruta paingon sa gawas mao ang egress proxy (pananglitan Squid o gamay nga tinyproxy container) nga motugot sa samang mga host sa QUIRE_EGRESS_ALLOW_HOSTS dugang sa mga host sa na-configure nga serbisyo; itakda ang HTTPS_PROXY niini nga mga serbisyo. Gilista sa panid sa residency ang eksaktong mga host nga gitugotan sa aplikasyon aron matandi ang duha ka listahan.

Kahimsog

Ipakita sa docker compose -f docker/compose.yaml ps ang kahimsog sa matag serbisyo.

TLS

Kabahin sa default stack ang serbisyo nga proxy (Caddy, Apache-2.0, docker/caddy/Caddyfile). Motubag kini sa port 80 ug 443 ug mag-route sa mosunod:

Makuha sa init-env.sh ang QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL ug IMGPROXY_URL gikan sa duha ka origin aron dili magkalahi ang mga bili niini. Usba silang tanan kon mano-mano nimong usbon ang usa ka origin.

Sundon sa certificate ang QUIRE_PROXY_TLS:

• internal (default): kaugalingong certificate authority sa Caddy para sa localhost, *.localhost ug lvh.me. Saligi kausa ang root niini, unya ablihi:

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

  Idugang ang quire-local-ca.crt sa trust store sa sistema o browser. Gamiton kini sa curl pinaagi sa --cacert.

• Email address: awtomatikong ACME certificate (Let’s Encrypt, unya ZeroSSL) para sa tinuod nga hostname. Kinahanglang magtudlo dinhi ang DNS sa duha ka origin ug matag tenant host, ug maabot gikan sa internet ang port 80 ug 443.

Iisyu ang mga tenant host kon unang bisitahon ug kon kumpirmahon lang sa web nga iya niining instalasyon ang ngalan (/tls-allowed, pangutan-on kini sa Compose network). Dili kinahanglan ang wildcard certificate o DNS provider plugin, ug dili makapahimo og certificate request ang estranghero nga nagtudlo lang og ngalan ngadto sa host. Anaa sa caddy-data volume ang certificate ug lokal nga authority; i-backup kini uban sa uban kon gamiton nimo ang internal.

Mosalig lang ang web sa X-Forwarded-For gikan sa proxy: pirmi ang address sa proxy (QUIRE_PROXY_ADDRESS, default 172.29.64.10) sa pirmi usab nga subnet (QUIRE_COMPOSE_SUBNET), ug nagtudlo sa maong address ang QUIRE_TRUSTED_PROXY_CIDRS. Kon nagbangga ang subnet sa network sa host, usba silang duha ug padagana ang docker compose down sa dili pa ang up.

Luyo sa kaugalingon nimong reverse proxy

Aron gamiton hinuon ang load balancer o proxy nga gipadagan na nimo, ayaw iapil ang proxy (docker compose up -d --scale proxy=0) ug tapusa ang TLS atubangan sa web (8080), content (8081), collab (1234, websocket) ug centrifugo (8000, websocket). Itakda ang publikong address sa QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN ug QUIRE_COLLAB_URL (wss://), ug ang address range sa proxy sa QUIRE_TRUSTED_PROXY_CIDRS.

Pagsulbad sa problema

• Mogawas ang init nga adunay “QUIRE_DATABASE_ID is not a UUID”: itakda kini gamit ang uuidgen.
• Mag-restart ang web nga adunay “did not start on compose”: ilista sa log ang matag setting nga dili niini matuman ug ang kapuli nga gamiton.
• Walay epekto ang pag-usab sa password sa role sa .env human sa unang pagsugod: kausa ra modagan ang init script. Gamita ang ALTER ROLE.
• Mapakyas ang upload tungod sa sayop sa scan samtang gitakda ang CLAMAV_URL: kuhaon sa ClamAV ang signature niini sa unang pagsugod, nga molungtad og pipila ka minuto.