---
title: "Hoʻouka iā Quire me Docker Compose"
description: "Hoʻouka iā Quire ma kāu ʻōnaehana ponoʻī me Docker Compose."
image: "https://docs.quirelms.com/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.quirelms.com/haw/llms.txt
> Use this file to discover all available pages before exploring further.

# Hoʻouka iā Quire me Docker Compose

<span id="installing-quire-with-docker-compose"></span>

ʻ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](/haw/ops/vercel/) a me [Cloudflare Workers](/haw/ops/cloudflare/) i ka papa pūnaewele. Aia nā hōʻano hou ma [upgrade.md](/haw/ops/upgrade/), a me nā papaʻa a me ka hoʻāʻo hoʻihoʻi ma [backup-restore.md](/haw/ops/backup-restore/).

## Nā mea e pono ai <!--quire:what-you-need-->

- 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:first-run-->

```sh
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 <!--quire:services-and-profiles-->

| Lawelawe | Profile | Hana |
| --- | --- | --- |
| postgres | mau | Ka waihona ʻikepili (PostgreSQL 18 me pgvector, i kūkulu ʻia mai `docker/postgres.Dockerfile`), me ka waihona WAL mai ka hoʻomaka mua |
| migrate, init | mau | Hana hoʻokahi: neʻe ʻikepili, a laila hoʻomaka mua |
| web | mau | LMS, ma `QUIRE_HTTP_PORT` (8080) |
| content | mau | Origin ʻike hilinaʻi ʻole, ma `QUIRE_CONTENT_PORT` (8081) |
| worker | mau | Nā hana hope: leka uila, hōʻike, hoʻoponopono faila, a me nā webhook |
| scheduler | mau | Nā hana hoʻihoʻi: hoʻopaʻa i nā papa manawa holo 64 a hāʻawi i nā worker; hoʻokahi alakaʻi i ka manawa |
| collab | mau | Websocket hoʻoponopono hui, ma `QUIRE_COLLAB_HTTP_PORT` (1234) |
| centrifugo | mau | Hoʻolaha manawa maoli, ma `QUIRE_REALTIME_PORT` (8000) |
| proxy | mau | Caddy, ka puka mua TLS ma nā awa 80 a me 443 (e nānā iā «TLS») |
| valkey | `cache` | Cache a me nā palena kāhea |
| clamav | `scan` | Nānā malware i nā mea hoʻouka |
| gotenberg | `preview` | Nānā mua Office ma PDF, unuhi palapala hōʻoia |
| imgproxy | `images` | Hoʻololi nui a ʻano kiʻi |
| transcoder | `video` | Kiʻi worker me ffmpeg LGPL wale nō no nā ʻano wikiō |
| seaweedfs | `storage` | Waihona mea kūlike S3 ma kēia host |
| otelcol | `observability` | Mea hōʻiliʻili OpenTelemetry |
| mailpit | `devmail` | Hopu i nā leka puka a pau no ka hoʻāʻo iā Quire |
| backup | `backup` | Papaʻa kumu hana hoʻokahi; e nānā iā backup-restore.md |
| backup-scheduler, backup-offsite | `backup` | Papaʻa kumu i kēlā me kēia `QUIRE_BACKUP_INTERVAL_HOURS`, a me nā kope hoʻopāʻālua waho me ka hoʻāʻo hōʻoia pule |
| h5p | `h5p` | Kiʻi lako H5P LTI 1.3 āu e hoʻolako ai ma `QUIRE_H5P_IMAGE`, ma `QUIRE_H5P_PORT` (8090); e nānā iā «Hoʻohui i mea hoʻolako H5P» |

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 <!--quire:connecting-an-h5p-provider-->

ʻ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 <!--quire:settings-->

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 <!--quire:addresses-->

| Hoʻonohonoho | Manaʻo |
| --- | --- |
| `QUIRE_APP_ORIGIN` | Helu wahi lehulehu o ka LMS, e like me `https://learn.example.com` |
| `QUIRE_CONTENT_ORIGIN` | Origin ʻike, he host ʻokoʻa |
| `QUIRE_PLATFORM_DOMAINS` | Nā domain e noho ai nā hui, i hoʻokaʻawale ʻia me nā koma |
| `QUIRE_MARKETING_ORIGIN` | Optional. The marketing site, default `https://quirelms.com`. The only origin the waitlist form (`POST /api/waitlist`, `POST /waitlist`) accepts and redirects to. Comma separated; a `www.` variant is allowed only if listed |
| `QUIRE_DEPLOY_TARGET` | `compose` ma ʻaneʻi. E nānā i nā alakaʻi ʻē aʻe no `vercel` a me `cloudflare` |
| `QUIRE_TRUSTED_PROXY_CIDRS` | Nā proxy i hilinaʻi ʻia ai ko lākou `X-Forwarded-For` |

### Nā ʻōlelo huna malu <!--quire:secrets-->

| Hoʻonohonoho | Manaʻo |
| --- | --- |
| `QUIRE_SECRET_KEY` | Pūlima i nā kau komo a me nā token. 64 huapalapala hex |
| `QUIRE_MASTER_KEY` | Hoʻopili i nā palapala hōʻoia mālama ʻia e like me SSO a me nā ʻōlelo huna webhook. 32 byte, base64. Pono ka waiwai like i ka papa pūnaewele a me ka worker. Hoʻololi: [key-rotation.md](/haw/ops/key-rotation/) |
| `QUIRE_MASTER_KEY_VERSION` | Lepili mana o ke kī haku, `v1` ke ʻole i hoʻonohonoho ʻia. Hoʻonui i ka hoʻololi ʻana |
| `QUIRE_MASTER_KEY_RETIRED` | Nā kī haku ma mua e pono mau ana e heluhelu i nā mea a lākou i hoʻopaʻa ai, ma ke ʻano `v1=<base64>`. Wehe ma hope o ka pau ʻana o ka hoʻololi me ka ʻole o kekahi mea i koe |
| `QUIRE_COLLAB_SIGNING_KEY` | Kaʻana ʻia e web a me collab e pūlima i nā token hoʻoponopono |
| `QUIRE_BACKUP_SIGNING_KEY` | Pūlima i nā papaʻa papa (koho) |

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 <!--quire:database-->

| Hoʻonohonoho | Manaʻo |
| --- | --- |
| `POSTGRES_PASSWORD` | Superuser, hoʻohana ʻia e ke ipu a me nā papaʻa |
| `QUIRE_DB_APP_PASSWORD`, `QUIRE_DB_MIGRATOR_PASSWORD`, `QUIRE_DB_REPORT_PASSWORD`, `QUIRE_DB_AUDIT_PASSWORD` | Nā ʻōlelo huna kuleana, hoʻonoho ʻia i ka hoʻomaka mua |
| `DATABASE_URL` | Kuleana polokalamu. Pili ka palekana pae-lālani i kēlā me kēia nīnau āna e hana ai |
| `DATABASE_MIGRATOR_URL`, `QUIRE_MIGRATION_URL` | Kuleana neʻe ʻikepili no `migrate` a me `init` |
| `QUIRE_SUPERUSER_URL` | Hoʻohana wale ʻia i ka hoʻomaka mua |
| `QUIRE_REPORT_DATABASE_URL` | Kuleana hōʻike heluhelu wale nō no nā hōʻike a me ka mea kūkulu hōʻike |
| `QUIRE_AUDIT_DATABASE_URL` | Kuleana hōʻoia no ka console hōʻoia a me ka hoʻokuʻu SIEM |
| `QUIRE_DATABASE_ID` | Kekahi UUID, paʻa no ke ola holoʻokoʻa o ka hoʻouka ʻana |

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 <!--quire:drivers-->

| Hoʻonohonoho | Nā koho o kēia mana | Nā memo |
| --- | --- | --- |
| `QUIRE_STORAGE_DRIVER` | `local` (paʻamau), `s3`, a i ʻole `azure` | Mālama ʻo `local` i nā faila ma ka volume `files`. Uhi ʻo `s3` iā AWS S3, kūlike R2 a me GCS, a me nā waihona ʻē aʻe kūlike S3, me nā hoʻouka multipart hiki ke hoʻomau |
| `QUIRE_REALTIME_DRIVER` | `inprocess` (paʻamau), `sse`, `centrifugo`, a i ʻole `durable_objects` | Kūpono ʻo `inprocess` no hoʻokahi ipu web; hoʻohana iā `centrifugo` a i ʻole `sse` ke nui nā ipu |
| `QUIRE_CACHE_DRIVER` | `memory` (paʻamau), `postgres`, a i ʻole `valkey` | No kēlā me kēia kaʻina ʻo `memory`; hoʻohana iā `valkey` a i ʻole `postgres` i paʻa nā palena kāhea ma waena o nā ipu |
| `QUIRE_VIDEO_DRIVER` | `ffmpeg` (paʻamau) a i ʻole `progressive_mp4` | A i ʻole mea hoʻolako hoʻokipa: Cloudflare Stream, Mux, a i ʻole Bunny ma o kā lākou mau kī |
| `QUIRE_IMAGE_DRIVER` | `noop` (paʻamau), `imgproxy`, a i ʻole `cloudflare` | Hāʻawi ʻo `noop` i kēlā me kēia kiʻi ma kona nui kumu. Pono ʻo `imgproxy` i ka profile `images` a me nā hoʻonohonoho ma lalo; hoʻohana ʻo `cloudflare` iā Cloudflare Images |
| `QUIRE_MEETING_PROVIDER` | `bbb`, `zoom`, `teams`, `meet`, `jitsi`, a i ʻole `in_process` | Mea hoʻolako paʻamau paepae no nā hālāwai ola. Inā waiho hakahaka ʻia, hōʻike nā hālāwai ola ʻaʻole i hoʻonohonoho ʻia a hoʻohui ka hui i kona moʻokāki ma Nā hoʻohui, Mea hoʻolako hālāwai ola. Lanakila mau ka moʻokāki ponoʻī o ka hui ma luna o kēia waiwai. Heluhelu ʻia nā hoʻonohonoho ponoʻī o ka mea hoʻolako (`BBB_URL` a me `BBB_SECRET`, nā loli `ZOOM_*`, `TEAMS_*`, `GOOGLE_MEET_*`, a me `JITSI_*`) no ka mea hoʻolako i kapa ʻia ma ʻaneʻi wale nō |
| `QUIRE_MEETING_REGIONS` | Papa koma o `eu`, `uk`, `us` | Nā wahi e hana ai ka mea hoʻolako paʻamau paepae i nā hālāwai. Inā waiho hakahaka ʻia, ʻaʻole nānā ʻia e kūʻē i ka hui i hoʻopaʻa ʻia i ʻāpana, e like me ma mua. Hōʻike ka ʻaoʻao o ka moʻokāki ponoʻī i nā wahi o ka hui |

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 <!--quire:images-->

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.

| Hoʻonohonoho | Mea hoʻokele | Nā memo |
| --- | --- | --- |
| `IMGPROXY_URL` | `imgproxy` | Helu wahi e hiki ai nā polokalamu kele pūnaewele iā imgproxy, e laʻa me `https://images.example.org`. Hoʻolaha ka profile `images` iā ia ma `QUIRE_IMAGES_PORT` (8082) |
| `IMGPROXY_KEY`, `IMGPROXY_SALT` | `imgproxy` | Nā kaula hex, nā waiwai like a imgproxy i hoʻomaka ai. Hana i kēlā me kēia me `openssl rand -hex 32`. Pūlima ʻo Quire i kēlā me kēia helu wahi kiʻi me lāua, no laila ʻaʻole hāʻawi ʻo imgproxy i kiʻi a Quire i noi ʻole ai |
| `QUIRE_IMAGE_SOURCE_ORIGIN` | `imgproxy` me ka waihona kūloko | Kahi e kiʻi ai ʻo imgproxy i nā kumu kiʻi. Hoʻonoho ʻo Compose iā `http://web:3000`. Me ka waihona `s3` a i ʻole `azure`, kiʻi ʻo imgproxy mai ka bucket a ʻaʻole hoʻohana ʻia kēia |
| `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_IMAGES_TOKEN`, `CLOUDFLARE_IMAGES_ACCOUNT_HASH` | `cloudflare` | Token API me ka ʻae hoʻoponopono Images, a me ka hash moʻokāki mai Images, Developer resources. E hoʻā i nā ʻano loli maʻalahi no ka moʻokāki |
| `CLOUDFLARE_IMAGES_SIGNING_KEY` | `cloudflare` | Koho. Ke hoʻonoho ʻia, pilikino nā kiʻi a pūlima ʻia a pau nā helu wahi. Me ka ʻole ona, lehulehu nā kiʻi ma nā helu wahi i loaʻa mai `QUIRE_SECRET_KEY` ʻaʻole hiki i kekahi ke kuhi |

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 <!--quire: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 <!--quire:email-->

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 <!--quire:optional-services-->

| Hoʻonohonoho | Me ka profile |
| --- | --- |
| `CLAMAV_URL=tcp://clamav:3310` | `scan` |
| `GOTENBERG_URL=http://gotenberg:3000` | `preview` |
| `IMGPROXY_KEY`, `IMGPROXY_SALT` | `images` |
| `VALKEY_URL=redis://valkey:6379` | `cache` |
| `QUIRE_OPENSEARCH_URL` a i ʻole `QUIRE_MEILISEARCH_URL` | Huli waho; i ʻole, kikokikona piha Postgres |
| `QUIRE_BREACH_CHECK_PROVIDER=off`, `QUIRE_BREACH_CHECK_URL` | Nānā ʻōlelo huna haki. Hoʻā paʻamau ʻia ma `api.pwnedpasswords.com` (hoʻouna ʻia ka prefix hash ʻelima huapalapala wale nō); hoʻopau ʻo `off` iā ia, a kuhikuhi ka URL i API range āu e mālama ai |

### Nānā ʻōnaehana <!--quire:observability-->

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) <!--quire:regional-egress-eu-data-residency-->

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.

| Hoʻonohonoho | Waiwai | Hopena |
| --- | --- | --- |
| `QUIRE_EGRESS_ALLOW_HOSTS` | Papa koma inoa host, a i ʻole `*.example.org` no kēlā me kēia subdomain | Nā host hou hiki i hui EU ke kiʻi. Aia nā endpoint webhook, xAPI, a SIEM, nā hānai blog, a me nā host Amazon SES ma ʻaneʻi, no ka mea na ka hui lākou i koho ai a ʻaʻole i hoʻolaha ʻia e kekahi lawelawe. ʻAʻole nānā ʻia ka loopback, nā helu kūloko pilikino, a me nā inoa lepili hoʻokahi e like me `web` a i ʻole `clamav`, no ka mea no kāu pūnaewele ponoʻī lākou |

ʻ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 <!--quire:health-->

| Endpoint | Manaʻo |
| --- | --- |
| `/healthz` | Ola: pane ke kaʻina. Hoʻohana nā nānā ola Compose iā ia |
| `/readyz` | Mākaukau: hiki ke kiʻi i nā hilinaʻi a hōʻike kēlā me kēia lawelawe koho inā ua hoʻonohonoho ʻia. Kuhikuhi i kāu mea kaulike ukana iā ia |

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

## TLS <!--quire: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:

| Host a ala paha | Hoʻouna i |
| --- | --- |
| `QUIRE_PROXY_CONTENT_HOST` | `content` |
| `QUIRE_PROXY_APP_HOST`, kēlā me kēia subdomain tenant a me domain maʻamau | `web` |
| `/_collab/` ma ia mau host | `collab` (websocket, `QUIRE_COLLAB_URL`) |
| `/_realtime/connection/` ma ia mau host | websocket client a `centrifugo`; ʻaʻole loa e hōʻike ʻia kona API kikowaena |
| `/_images/` ma ia mau host | `imgproxy`, me ka profile `images` (`IMGPROXY_URL`) |

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:

  ```sh
  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ʻī <!--quire:behind-your-own-reverse-proxy-->

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 <!--quire:troubleshooting-->

- 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ā.

Source: https://docs.quirelms.com/haw/ops/install/index.mdx