---
title: "Pag-instalar sa Quire gamit ang Docker Compose"
description: "I-install ang Quire sa kaugalingon nimong imprastraktura gamit ang Docker Compose."
image: "https://docs.quirelms.com/og.png"
---

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

# Pag-instalar sa Quire gamit ang Docker Compose

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

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](/ceb/ops/vercel/) ug [Cloudflare Workers](/ceb/ops/cloudflare/). Ania sa [upgrade.md](/ceb/ops/upgrade/) ang pag-upgrade, ug ania sa [backup-restore.md](/ceb/ops/backup-restore/) ang backup ug restore drill.

## Mga kinahanglan <!--quire:what-you-need-->

- 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: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
```

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

| Serbisyo | Profile | Buluhaton |
| --- | --- | --- |
| postgres | always | Database (PostgreSQL 18 nga may pgvector, gitukod gikan sa `docker/postgres.Dockerfile`), gi-archive ang WAL sukad sa unang pagsugod |
| migrate, init | always | Kausa ra: migration, dayon unang pagdagan |
| web | always | LMS, sa `QUIRE_HTTP_PORT` (8080) |
| content | always | Origin sa untrusted content, sa `QUIRE_CONTENT_PORT` (8081) |
| worker | always | Mga buluhaton sa background: email, report, pagproseso sa file, webhook |
| scheduler | always | Mga balikbalik nga buluhaton: irehistro ang 64 ka runtime schedule ug ipasa sa worker; usa ra ka lider matag higayon |
| collab | always | Websocket para sa hiniusang pag-edit, sa `QUIRE_COLLAB_HTTP_PORT` (1234) |
| centrifugo | always | Realtime fan-out, sa `QUIRE_REALTIME_PORT` (8000) |
| proxy | always | Caddy, atubangang TLS sa port 80 ug 443 (tan-awa ang "TLS") |
| valkey | `cache` | Cache ug rate limit |
| clamav | `scan` | Pag-scan sa malware sa mga upload |
| gotenberg | `preview` | Preview sa Office ngadto sa PDF, pag-render sa certificate |
| imgproxy | `images` | Pag-usab sa gidak-on ug format sa image |
| transcoder | `video` | Worker image nga adunay LGPL-only ffmpeg, para sa pag-convert sa video |
| seaweedfs | `storage` | S3-compatible nga object storage niining host |
| otelcol | `observability` | OpenTelemetry collector |
| mailpit | `devmail` | Modakop sa tanang mogawas nga mail, para sulayan ang Quire |
| backup | `backup` | Kausa ra nga base backup; tan-awa ang backup-restore.md |
| backup-scheduler, backup-offsite | `backup` | Base backup matag `QUIRE_BACKUP_INTERVAL_HOURS`, ug naka-encrypt nga kopya sa gawas sa host nga susihon kada semana pinaagi sa verification drill |
| h5p | `h5p` | H5P LTI 1.3 tool image nga imong ihatag sa `QUIRE_H5P_IMAGE`, sa `QUIRE_H5P_PORT` (8090); tan-awa ang "Pagkonektar og H5P provider" |

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

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

| Setting | Kahulogan |
| --- | --- |
| `QUIRE_APP_ORIGIN` | Publikong address sa LMS, sama sa `https://learn.example.com` |
| `QUIRE_CONTENT_ORIGIN` | Content origin, lahi nga host |
| `QUIRE_PLATFORM_DOMAINS` | Mga domain diin anaa ang mga organisasyon, gibulag sa comma |
| `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` dinhi. Tan-awa ang ubang giya para sa `vercel` ug `cloudflare` |
| `QUIRE_TRUSTED_PROXY_CIDRS` | Mga proxy diin gisaligan ang `X-Forwarded-For` |

### Mga sekreto <!--quire:secrets-->

| Setting | Kahulogan |
| --- | --- |
| `QUIRE_SECRET_KEY` | Mopirma sa mga session ug token. 64 ka hex character |
| `QUIRE_MASTER_KEY` | Moputos sa tinipig nga credential sama sa SSO ug webhook secret. 32 bytes, base64. Kinahanglan parehas ang bili niini sa web tier ug worker. Pagtuyok: [key-rotation.md](/ceb/ops/key-rotation/) |
| `QUIRE_MASTER_KEY_VERSION` | Label sa bersiyon sa master key, `v1` kon walay setting. Dugangi kini kon tuyokon ang yawe |
| `QUIRE_MASTER_KEY_RETIRED` | Mga daang master key nga gikinahanglan gihapon sa pagbasa sa giputos niini, isip `v1=<base64>`. Kuhaa kon mahuman ang pagtuyok nga walay wala masulbad |
| `QUIRE_COLLAB_SIGNING_KEY` | Gipaambitan sa web ug collab sa pagpirma sa editing token |
| `QUIRE_BACKUP_SIGNING_KEY` | Mopirma sa backup sa kurso (opsyonal) |

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

| Setting | Kahulogan |
| --- | --- |
| `POSTGRES_PASSWORD` | Superuser, gamiton sa container ug backup |
| `QUIRE_DB_APP_PASSWORD`, `QUIRE_DB_MIGRATOR_PASSWORD`, `QUIRE_DB_REPORT_PASSWORD`, `QUIRE_DB_AUDIT_PASSWORD` | Mga password sa role, itakda sa unang pagsugod |
| `DATABASE_URL` | Application role. Ipatuman ang row-level security sa matag query niini |
| `DATABASE_MIGRATOR_URL`, `QUIRE_MIGRATION_URL` | Migrator role, para sa `migrate` ug `init` |
| `QUIRE_SUPERUSER_URL` | Gamiton lang sa unang pagdagan |
| `QUIRE_REPORT_DATABASE_URL` | Read-only report role, para sa report ug report builder |
| `QUIRE_AUDIT_DATABASE_URL` | Audit role, para sa audit console ug SIEM export |
| `QUIRE_DATABASE_ID` | Bisan unsang UUID, dili mausab sa tibuok kinabuhi sa instalasyon |

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

| Setting | Niining release | Mga pahimangno |
| --- | --- | --- |
| `QUIRE_STORAGE_DRIVER` | `local` (default), `s3` o `azure` | Gitipigan sa `local` ang mga file sulod sa volume nga `files`. Naglangkob ang `s3` sa AWS S3, R2, GCS interoperability ug ubang S3-compatible store, nga may resumable multipart upload |
| `QUIRE_REALTIME_DRIVER` | `inprocess` (default), `sse`, `centrifugo` o `durable_objects` | Haom ang `inprocess` sa usa ka web container; gamita ang `centrifugo` o `sse` kon daghan sila |
| `QUIRE_CACHE_DRIVER` | `memory` (default), `postgres` o `valkey` | Para sa usa ka proseso ang `memory`; gamita ang `valkey` o `postgres` aron magpabilin ang rate limit tali sa mga container |
| `QUIRE_VIDEO_DRIVER` | `ffmpeg` (default) o `progressive_mp4` | O hosted provider: Cloudflare Stream, Mux o Bunny, gamit ang ilang key |
| `QUIRE_IMAGE_DRIVER` | `noop` (default), `imgproxy` o `cloudflare` | Iserbisyo sa `noop` ang tanang image sa orihinal nga gidak-on. Nagkinahanglan ang `imgproxy` sa `images` profile ug mga setting sa ubos; mogamit ang `cloudflare` sa Cloudflare Images |
| `QUIRE_MEETING_PROVIDER` | `bbb`, `zoom`, `teams`, `meet`, `jitsi` o `in_process` | Default provider sa platform para sa live session. Kon wala itakda, ipahibalo nga wala pa ma-configure ang live session hangtod makonektar ang organisasyon sa kaugalingong account niini sa Integrations, Live session provider. Kanunayng pilion ang kaugalingong account sa organisasyon imbis sa bili dinhi. Basahon lang ang setting sa matag provider (`BBB_URL` ug `BBB_SECRET`, ang mga variable nga `ZOOM_*`, `TEAMS_*`, `GOOGLE_MEET_*` ug `JITSI_*`) para sa provider nga ginganlan dinhi |
| `QUIRE_MEETING_REGIONS` | Listahan sa `eu`, `uk`, `us` nga gibulag sa comma | Asa iproseso ang mga meeting sa default nga provider sa platform. Kon wala itakda, dili susihon kini batok sa organisasyong naka-pin sa usa ka rehiyon, sama kaniadto. Isulat sa kaugalingong account sa organisasyon ang mga rehiyon niini sa panid niini |

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

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.

| Setting | Driver | Mga pahimangno |
| --- | --- | --- |
| `IMGPROXY_URL` | `imgproxy` | Address nga maabot sa browser sa imgproxy, pananglitan `https://images.example.org`. I-publish kini sa `images` profile sa `QUIRE_IMAGES_PORT` (8082) |
| `IMGPROXY_KEY`, `IMGPROXY_SALT` | `imgproxy` | Hex string nga parehas sa pagsugod sa imgproxy. Himoa ang matag usa gamit ang `openssl rand -hex 32`. Pirmahan niini sa Quire ang matag image address, busa walay i-render ang imgproxy nga wala gipangayo sa Quire |
| `QUIRE_IMAGE_SOURCE_ORIGIN` | `imgproxy` nga lokal ang storage | Diin kuhaon sa imgproxy ang orihinal. Itakda kini sa Compose isip `http://web:3000`. Kon `s3` o `azure` ang storage, kuhaon sa imgproxy gikan sa bucket ug dili kini gamiton |
| `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_IMAGES_TOKEN`, `CLOUDFLARE_IMAGES_ACCOUNT_HASH` | `cloudflare` | API token nga adunay permiso sa pag-edit sa Images, ug account hash gikan sa Images, Developer resources. I-enable ang flexible variant para sa account |
| `CLOUDFLARE_IMAGES_SIGNING_KEY` | `cloudflare` | Opsyonal. Kon itakda, pribado ang image ug pirmahan ug butangan og expiration ang matag address. Kon wala kini, publiko ang image sa address nga makuha gikan sa `QUIRE_SECRET_KEY` nga dili matag-an ni bisan kinsa |

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

| Setting | Uban sa 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` o `QUIRE_MEILISEARCH_URL` | Eksternal nga search; gamiton hinuon ang full text sa Postgres |
| `QUIRE_BREACH_CHECK_PROVIDER=off`, `QUIRE_BREACH_CHECK_URL` | Pagsusi sa nakompromisong password. Naka-on kini sa default ug mosusi sa `api.pwnedpasswords.com` (unang lima lang ka karakter sa hash ang ipadala); i-disable kini sa `off`, ug itudlo sa URL ang range API nga imong gi-host |

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

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.

| Setting | Mga bili | Epekto |
| --- | --- | --- |
| `QUIRE_EGRESS_ALLOW_HOSTS` | Mga hostname nga gibulag sa comma, o `*.example.org` para sa matag subdomain | Dugang nga host nga maabot sa organisasyon sa EU. Dinhi ibutang ang webhook, xAPI ug SIEM endpoint, blog feed ug Amazon SES host, kay kaugalingong gipili kini sa organisasyon ug walay serbisyo nga nagdeklarar niini. Imong kaugalingong network ang loopback, private address ug mga ngalan nga usa ra ka label sama sa `web` o `clamav`; dili gayod kini susihon |

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

| Endpoint | Kahulogan |
| --- | --- |
| `/healthz` | Liveness: motubag ang proseso. Gigamit kini sa health check sa Compose |
| `/readyz` | Readiness: maabot ang mga dependency ug ireport kon na-configure ba ang matag opsyonal nga serbisyo. Itudlo dinhi ang load balancer |

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

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

| Host o path | Paingon sa |
| --- | --- |
| `QUIRE_PROXY_CONTENT_HOST` | `content` |
| `QUIRE_PROXY_APP_HOST`, matag tenant subdomain ug custom domain | `web` |
| `/_collab/` niini nga mga host | `collab` (websocket, `QUIRE_COLLAB_URL`) |
| `/_realtime/connection/` niini nga mga host | Client websocket sa `centrifugo`; dili gayod ipadayag ang server API niini |
| `/_images/` niini nga mga host | `imgproxy`, uban sa `images` profile (`IMGPROXY_URL`) |

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:

  ```sh
  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 <!--quire:behind-your-own-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 <!--quire:troubleshooting-->

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

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