Hoʻouka iā Quire me Docker Compose

ʻO kēia ka huahana piha ma hoʻokahi host: ka LMS, kāna mau hana hope, nā lawelawe manawa maoli a hoʻoponopono hui, a me kēlā me kēia lawelawe koho ma lalo o profile. Aia ka hoʻolālā ma ka māhele 2 o docs/architecture/23-ops.md.

Nā pahuhopu ʻē aʻe: holo wale ʻo Vercel a me Cloudflare Workers i ka papa pūnaewele. Aia nā hōʻano hou ma upgrade.md, a me nā papaʻa a me ka hoʻāʻo hoʻihoʻi ma backup-restore.md.

Nā mea e pono ai

• Docker Engine 27 a ʻoi aku me ka plugin Compose 2.30 a ʻoi aku.
• 4 mau kumu CPU a me 8 GB hoʻomanaʻo no ka stack paʻamau; 8 kumu a me 16 GB me --profile full (paʻa ʻo ClamAV hoʻokahi i kahi o 1.5 GB o nā pūlima).
• He inoa DNS no ka papa pūnaewele a he inoa lua no ka ʻike hilinaʻi ʻole. Pono lākou he host ʻokoʻa: holo nā pūʻolo SCORM a me ka HTML i hoʻouka ʻia ma ka origin ʻike, no laila ʻaʻole loa lākou e heluhelu i nā kuki LMS.
• No ka hoʻāʻo kūloko, hoʻonā ʻia ʻo lvh.me a me *.localhost i 127.0.0.1, e like me ka hoʻonohonoho a docker/.env.example. Lawelawe ka proxy ponoʻī o ka stack iā lāua ma https me ka mana hōʻoia kūloko, no laila ʻaʻohe mea ʻē aʻe e hoʻouka ai (e nānā iā «TLS»).
• E hoʻokuʻu i nā awa 80 a me 443 ma ka host (QUIRE_PROXY_HTTP_PORT a me QUIRE_PROXY_HTTPS_PORT e hoʻoneʻe iā lākou).

Hoʻomaka mua

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

Kākau ʻo docker/scripts/init-env.sh iā docker/.env mai docker/.env.example me ka hana ʻana i nā ʻōlelo huna malu a pau (nā ʻōlelo huna waihona ʻikepili, nā kī pūlima a haku, nā kī pālua hoʻomaka ʻike) a me ke kī pūlima māka hōʻoia ma docker/secrets/audit-signing-key.pem, a kau ʻo Compose ia i loko o nā worker ma ke ʻano he ʻōlelo huna malu. Pono wale iā sh, awk, a me openssl, ʻaʻole hoʻi e kākau ma luna o docker/.env e kū nei. E kope i nā faila ʻelua ma waho o ka host: me ka ʻole o QUIRE_MASTER_KEY, ʻaʻole hiki i ka waihona ʻikepili i hoʻihoʻi ʻia ke wehe i nā palapala hōʻoia i mālama ʻia. No ka hoʻopiha lima ʻana i ka faila, e hoʻohana iā cp docker/.env.example docker/.env; hōʻike ka faila i ka hana ʻana i kēlā me kēia ʻōlelo huna malu.

Pono nā origin ʻelua he https: hōʻole ka lawelawe ʻike i ka http maʻalahi i ka hana, ʻaʻole hoʻi e kaʻana i ka domain registrable hoʻokahi. Hoʻopau ka lawelawe proxy i ka TLS no lāua (e nānā iā «TLS»); hōʻole ʻo init-env.sh i origin http://.

Hoʻomaka ka stack ma ke kaʻina paʻa, a kali kēlā me kēia ʻanuʻu i ka mea ma mua:

1. Ola ʻo postgres. Ma ka hoʻomaka mua loa, hoʻonoho kāna script hoʻomaka (docker/postgres/init/90-passwords.sh) i nā ʻōlelo huna kuleana ʻehā.
2. Hoʻohana ʻo migrate i kēlā me kēia neʻe a hoʻomaka i ka queue hana ma ka waihona ʻikepili hoʻomalu a me kēlā me kēia waihona tenant hoʻolaʻa; nānā i ko lākou kūlike, a puka (docs/ops/upgrade.md). Holo nā neʻe i kēlā me kēia hoʻomaka a hana hoʻokahi wale nō, no laila he kiʻi hou a hoʻomaka hou ka hōʻano hou.
3. Hoʻopaʻa ʻo init (apps/web/src/first-run.ts) i ka waihona ʻikepili polokalamu ma lalo o QUIRE_DATABASE_ID; a ke hoʻonoho ʻia ʻo QUIRE_SETUP_ADMIN_EMAIL, hana i hui mua a me kona luna hoʻomalu. Paʻi ʻia hoʻokahi manawa ka helu wahi komo a me ka ʻōlelo huna i hana ʻia, ma docker compose logs init.
4. Hoʻomaka ʻo web, content, worker, scheduler, collab, a me centrifugo.
5. Hoʻomaka ʻo proxy ke ola ʻo web a me content.

E wehe iā https://demo. a ukali ʻia e kāu domain polokalamu (paʻi ka moʻolelo init i ka helu wahi komo pololei), a komo. Ma kahi hoʻouka kūloko, hilinaʻi mua i ka mana hōʻoia a ka proxy (e nānā iā «TLS»). E hoʻololi i ka ʻōlelo huna i hana ʻia ma /account/security.

Hōʻole kekahi kaʻina i hoʻomaka me ka ʻōlelo huna malu pono ʻole e hoʻomaka, a kapa i ka hoʻonohonoho i nele ma kāna moʻolelo. ʻAʻohe mea e hoʻomaka me ka hoʻonohonoho hapa.

Nā lawelawe a me nā profile

Hoʻomaka ʻo --profile full i kēlā me kēia lawelawe koho koe ʻo backup a me h5p. Hoʻomaka i hoʻokahi me docker compose -f docker/compose.yaml --profile scan up -d. Holo nō ʻo Quire me ka ʻole o kekahi lawelawe koho a hōʻike i ka mea e nele ana: me ka scanner ʻole, mālama ʻia nā hoʻouka me ka nānā ʻole a hoʻomaopopo ʻia ka luna hoʻomalu; me ka ʻole o Gotenberg, hāʻawi ʻia ka hoʻoiho faila ma kahi o ka nānā mua; me ka ʻole o ka transcoder, pāʻani ʻia ka wikiō e like me ka faila kumu.

Papa inoa ʻo docker/third-party-containers.yaml i kēlā me kēia kiʻi ʻaoʻao ʻekolu a me kona mau kuleana laikini.

Hoʻohui i mea hoʻolako H5P

ʻAʻole hoʻokomo a hoʻouna ʻo Quire i ʻenekini holo H5P a i ʻole sidecar (ADR 0019). Inā hoʻohana ʻoe iā H5P, hoʻolako i kāu kau inoa hoʻokipa ponoʻī a mālama paha i kāu laʻana H5P ponoʻī i hoʻokaʻawale ʻia mai Quire. E hoʻopaʻa inoa i ia mea hoʻolako ma ke ʻano he lako waho LTI 1.3 a hoʻohui i kona ʻike i nā papa ma ke ʻano he hana lako. Hoʻololi ʻo Quire i nā māka a me ka holomua hana/helu ma o LTI Assignment and Grade Services (AGS). Inā hoʻouna pū ka mea hoʻolako i nā ʻōlelo xAPI, hoʻonohonoho kaʻawale i ia mea no ka waihona ʻōlelo xAPI a Quire; ʻaʻole hoʻouna ka hoʻololi māka/holomua AGS i nā ʻōlelo xAPI. Hōʻike nā hoʻokomo Moodle i nā hana H5P e pono ai ka pilina lako LTI. Na ka mea hoʻolako e mālama i kāna ʻenekini H5P, kākau ʻike, waihona ʻikepili, a me ka mōʻaukala hoʻāʻo.

No ka holo ʻana i kāu laʻana mālama ponoʻī ma kēia host, hoʻonoho iā QUIRE_H5P_IMAGE i kona kiʻi a hoʻomaka i ka profile h5p. Hoʻolaha ʻo Compose iā ia ma QUIRE_H5P_PORT (8090) a mālama i kona ʻikepili ma ka volume h5p-data; nou ke kiʻi a me nā kuleana e pili ana iā ia.

Nā hoʻonohonoho

Heluhelu kēlā me kēia kaʻina iā docker/.env. Papa inoa ka ʻōkuhi docker/.env.example i nā hoʻonohonoho a pau me kā lākou paʻamau. Eia nā pūʻulu:

Nā helu wahi

Nā ʻōlelo huna malu

E mālama i kope o QUIRE_MASTER_KEY ma kahi ʻē aʻe, ʻaʻole ma kēia host. ʻAʻole hiki i ka waihona ʻikepili i hoʻihoʻi ʻia me ka ʻole ona ke wehe i nā palapala hōʻoia.

Waihona ʻikepili

Hoʻohana ʻia nā ʻōlelo huna kuleana i ka wā i hana mua ʻia ai ka volume waihona ʻikepili wale nō. No ka hoʻololi ʻana ma hope, hoʻohana iā ALTER ROLE a hōʻano hou i ka URL kūlike.

Hoʻohana ʻia QUIRE_REPORT_DATABASE_URL no ka waihona ʻikepili kino i hoʻonohonoho ʻia e DATABASE_URL. No kekahi waihona ʻikepili kino i hoʻopaʻa inoa ʻia, hoʻonoho i kona URL pilina quire_report ponoʻī ma nā kaiapuni web a worker, a laila hoʻokomo i ka inoa loli i ke kahua Loli kaiapuni hōʻike o ia waihona ma ke ʻano he env:NAME. Pono ke kuhikuhi e kuhikuhi i ka waihona ʻikepili like me ka pilina polokalamu, ʻoi aku ka maikaʻi i kāna replica heluhelu. Hahai nā wahi hōʻike a pau i ka tenant a i ka pilina hōʻike o kona waihona ponoʻī: ka mea kūkulu hōʻike a me nā hōʻike i mālama ʻia, nā hoʻouna manawa, nā hoʻokuʻu hōʻike, ka helu ʻikepili, ka moʻolelo hōʻoia, nā kumuwaiwai hōʻoia REST, a me ka huli hōʻoia a ke kōkua. ʻAʻole loa kekahi o lākou e ʻaiʻē i ka URL hōʻike o kekahi waihona ʻē aʻe. Inā ʻaʻohe pilina hōʻike o kahi waihona, holo nā hōʻike maʻamau ma kona pilina polokalamu ponoʻī; hōʻole ka helu ʻikepili a me kēlā me kēia heluhelu hōʻoia a wehewehe i ke kumu, no ka mea ʻaʻole hiki i ke kuleana polokalamu ke heluhelu i ka moʻolelo hōʻoia.

Nā mea hoʻokele

Hōʻole ʻia kekahi waiwai mea hoʻokele i loaʻa ʻole ma kēia mana i ka hoʻomaka ʻana o ka papa pūnaewele me ka inoa o ka hoʻonohonoho, ʻaʻole pani mālie ʻia e ka paʻamau.

Nā kiʻi

Noi nā ʻaoʻao i nā kiʻi ma nā nui paʻa ʻehā ma o /api/files/{id}/image/{size}, nānā kēia i ka ʻae like me ka faila ponoʻī, a laila hoʻohuli i ka lawelawe kiʻi. Hiki i kēlā me kēia hui ke noi i QUIRE_IMAGE_SPECS_PER_HOUR (2000 ma ke ʻano paʻamau) pālua kiʻi a nui hou i kēlā me kēia hola; ʻaʻole helu ʻia nā nui i hana mua ʻia i ia hola. E hoʻohana iā valkey a i ʻole postgres no QUIRE_CACHE_DRIVER me nā ipu web he nui, i pili ai ka palena iā lākou a pau.

Mālama ʻo Cloudflare Images i kope ponoʻī o kēlā me kēia kiʻi kumu āna e hāʻawi ai. Ke holoi ʻia kekahi faila, holoi ka worker i kēlā kope ma mua o ke kumu.

Queue

Hoʻohana nā hana hope iā pg-boss ma ka waihona Postgres like, no laila ʻaʻohe lawelawe queue e holo a hoʻonohonoho ai. Hoʻokomo ʻia nā hana ma ka hana ʻikepili like me ka hoʻololi nāna lākou i hoʻomaka, no laila ʻaʻole hiki i ka hāʻule ke nalowale a hoʻouna pālua paha. Paʻamau ʻo QUIRE_QUEUE_DRIVER ma kēia pahuhopu i pgboss; hoʻoneʻe ʻo vercel a me cloudflare i nā hoʻomaopopo māmā a me nā hoʻouna webhook wale nō i ka queue ponoʻī o ka paepae, a wehewehe nā alakaʻi Vercel a Cloudflare iā lākou a me ka hoʻokomo ʻana a kā lākou mau papa pūnaewele.

Leka uila

E hoʻonoho i kekahi o kēia:

• QUIRE_EMAIL_PROVIDER_CONFIG: mea JSON e kapa ana i mea hoʻolako HTTP a me kona mau palapala hōʻoia, e like me {"provider":"postmark","token":"..."}. Kākoʻo ʻia ʻo Postmark, Amazon SES, Mailgun, SendGrid, a me Resend.
• QUIRE_SMTP_URL: smtp://user:password@host:587. No kēia pahuhopu wale nō; pāpā nā pahuhopu serverless iā SMTP.

ʻO QUIRE_MAIL_FROM ka mea hoʻouna. No ka hoʻāʻo ʻana iā Quire, hoʻomaka i ka profile devmail, hoʻonoho iā QUIRE_SMTP_URL=smtp://mailpit:1025, a heluhelu i ka leka ma http://localhost:8025.

Nā lawelawe koho

Nānā ʻōnaehana

Kapa ʻo OTEL_EXPORTER_OTLP_ENDPOINT i ka mea hōʻiliʻili a nā kaʻina a pau e hoʻouna ai i nā kaha a me nā ana; me ka profile observability, ʻo ia ʻo http://otelcol:4318, a ma docker/otel-collector.yaml ʻoe e hoʻohui ai i ka exporter backend. Hoʻouna nā kaʻina web, worker, scheduler, content, a me collab i nā spans ma OTLP/HTTP (nā noi pūnaewele, nā hana waihona ʻikepili tenant, nā hana worker, a me nā kāhea puka) ke hoʻonoho ʻia, a me nā ana i kēlā me kēia minuke i ka endpoint like (OTEL_METRICS_EXPORTER=none e hoʻopau iā lākou). Hoʻonoho ʻo OTEL_TRACES_SAMPLER_ARG i ka mahele o nā kaha e mālama ʻia. Hele nā moʻolelo i ka puka maʻamau ma ka pae LOG_LEVEL, a hoʻololi ʻo Compose iā lākou. ʻAʻohe ʻike pilikino i loko o nā kaha.

Puka ʻāpana (noho ʻikepili EU)

Hōʻike ʻo QUIRE_REGION=eu i ka lawelawe ʻana o ka stack i nā hui ʻEulopa. Hoʻopaʻa ka worker i kēlā me kēia noi puka no kahi hui i hoʻopaʻa ʻia i ka EU i papa inoa ʻae ʻia (māhele 8.1 o 21-compliance.md). ʻO nā host ma ka papa inoa nā mea a nā lawelawe i hoʻonohonoho ʻia e hoʻolaha ai no ka ʻāpana (endpoint waihona, mea hoʻolako leka uila, mea hoʻolako wikiō hoʻokipa, nā pahuhopu waihona ponoʻī o ka hui, nā mea hoʻolako AI a me ka moʻokāki leka uila), nā host o nā lawelawe ma lalo o ʻae kūikawā hana, a me nā host āu e papa inoa ai ma QUIRE_EGRESS_ALLOW_HOSTS. Hōʻole ʻia kekahi noi i host lehulehu ʻē aʻe ma mua o ka hoʻouna ʻana; kākau ʻia ka hōʻole ma ke kaulahao hōʻoia hui ma ke ʻano he privacy/egress_refused, a helu ʻia ma Ka mālama ʻana, Noho ʻikepili.

ʻAʻole hoʻopaʻa ʻia nā hui UK a me US i ka papa inoa host; mālama lākou i nā nānā ʻāpana lawelawe. E hoʻonoho i ka papa inoa ma ka worker; heluhelu ka ʻaoʻao admin iā ia ma ka papa pūnaewele e hōʻike i ka papa inoa ʻae ʻia, no laila e hoʻokomo i docker/.env i heluhelu ʻia e kēlā me kēia lawelawe.

Hāʻawi ka nānā polokalamu i hewa maopopo a me komo hōʻoia, akā ʻaʻole ia ka palekana paʻa: hiki ke hewa ke code. ʻO ka pūnaewele ka palekana. ʻAʻole hoʻokō ʻo Compose iā ia no ʻoe. No ka stack ʻāpana, e kau i nā lawelawe worker a me web ma kahi pūnaewele internal: true nona ke ala puka hoʻokahi ma o proxy puka (e laʻa me Squid a i ʻole ipu tinyproxy) e ʻae ana i nā host like me QUIRE_EGRESS_ALLOW_HOSTS a me nā host o kāu mau lawelawe i hoʻonohonoho ʻia; hoʻonoho iā HTTPS_PROXY no ia mau lawelawe. Papa inoa ka ʻaoʻao noho i nā host pololei a ka polokalamu e ʻae ai, i hiki ke hoʻohālikelike i nā papa inoa ʻelua.

Ola

Hōʻike ʻo docker compose -f docker/compose.yaml ps i ke kūlana olakino o kēlā me kēia lawelawe.

TLS

He māhele ka lawelawe proxy (Caddy, Apache-2.0, docker/caddy/Caddyfile) o ka stack paʻamau. Pane ia ma nā awa 80 a me 443 a hoʻouna:

Loaʻa iā init-env.sh nā waiwai QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL, a me IMGPROXY_URL mai nā origin ʻelua, no laila ʻaʻole hiki ke kaʻawale ko lākou mau waiwai. Hoʻoponopono pū iā lākou ke hoʻololi lima ʻoe i origin.

Pili nā palapala hōʻoia iā QUIRE_PROXY_TLS:

• internal (paʻamau): ka mana hōʻoia ponoʻī a Caddy, no localhost, *.localhost, a me lvh.me. Hilinaʻi i kona kumu hoʻokahi manawa, a laila wehe:

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

  Hoʻohui iā quire-local-ca.crt i ka waihona hilinaʻi ʻōnaehana a i ʻole polokalamu kele pūnaewele. Lawe ʻo curl iā ia ma o --cacert.

• He helu leka uila: palapala hōʻoia ACME ʻakomi (Let’s Encrypt, a laila ZeroSSL) no nā inoa host maoli. Pono e kuhikuhi nā DNS o nā origin ʻelua a me kēlā me kēia host tenant i ʻaneʻi; pono nā awa 80 a me 443 e hiki ke kiʻi mai ka pūnaewele puni honua.

Hāʻawi ʻia nā host tenant ma ke koi i ka kipa mua wale nō ke hōʻoia ka web no kēia hoʻouka ʻana ka inoa (/tls-allowed, i nīnau ʻia ma ka pūnaewele Compose). ʻAʻole pono palapala hōʻoia wildcard a plugin mea hoʻolako DNS paha; ʻaʻole hiki i kekahi malihini ke kuhikuhi i inoa i ka host a koi i nā palapala hōʻoia. Noho nā palapala hōʻoia a me ka mana kūloko ma ka volume caddy-data; e hana i papaʻa pū me ke koena inā hoʻohana ʻoe iā internal.

Hilinaʻi ka web i X-Forwarded-For mai ka proxy wale nō: he helu paʻa ko ka proxy (QUIRE_PROXY_ADDRESS, paʻamau 172.29.64.10) ma kahi subnet paʻa (QUIRE_COMPOSE_SUBNET), a kapa ʻo QUIRE_TRUSTED_PROXY_CIDRS i kēlā helu. Inā kūʻē ka subnet i kekahi pūnaewele host, hoʻololi i nā mea ʻelua a holo iā docker compose down ma mua o up.

Ma hope o kāu proxy hoʻohuli ponoʻī

No ka hoʻohana ʻana i kāu mea kaulike ukana a proxy paha, waiho i proxy ma waho (docker compose up -d --scale proxy=0) a hoʻopau TLS ma mua o web (8080), content (8081), collab (1234, websocket), a me centrifugo (8000, websocket). E hoʻonoho i nā helu lehulehu ma QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN, a me QUIRE_COLLAB_URL (wss://); a me ka pae helu wahi proxy ma QUIRE_TRUSTED_PROXY_CIDRS.

Hoʻoponopono pilikia

• Puka ʻo init me «QUIRE_DATABASE_ID is not a UUID»: hoʻonoho me uuidgen.
• Hoʻomaka hou ʻo web me «did not start on compose»: papa inoa ka moʻolelo i kēlā me kēia hoʻonohonoho hiki ʻole ke hoʻokō a me ka mea e hoʻohana ai.
• ʻAʻohe hopena o ka hoʻololi ʻōlelo huna kuleana ma .env ma hope o ka hoʻomaka mua: holo hoʻokahi wale nō ka script hoʻomaka. E hoʻohana iā ALTER ROLE.
• Hāʻule nā hoʻouka me ka hewa nānā ke hoʻonoho ʻia ʻo CLAMAV_URL: hoʻoiho ʻo ClamAV i nā pūlima i ka hoʻomaka mua, he mau minuke paha kēlā.