---
title: "Gosod Quire gyda Docker Compose"
description: "Gosod Quire ar eich seilwaith eich hun gyda Docker Compose."
image: "https://docs.quirelms.com/og.png"
---

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

# Gosod Quire gyda Docker Compose

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

Dyma'r cynnyrch llawn ar un host: y LMS, ei waith cefndir, y gwasanaethau amser real
a golygu cydweithredol, a phob gwasanaeth dewisol y tu ôl i broffil. Mae'r dyluniad yn adran 2 o `docs/architecture/23-ops.md`.

Targedau eraill: dim ond haen we mae [Vercel](/cy/ops/vercel/) a [Cloudflare Workers](/cy/ops/cloudflare/) yn ei rhedeg. Mae uwchraddio yn [upgrade.md](/cy/ops/upgrade/), a chopïau wrth gefn a'r prawf adfer yn
[backup-restore.md](/cy/ops/backup-restore/).

## Beth sydd ei angen <!--quire:what-you-need-->

- Docker Engine 27 neu'n ddiweddarach gyda'r ategyn Compose 2.30 neu'n ddiweddarach.
- 4 craidd CPU ac 8 GB o gof ar gyfer y stack diofyn; 8 craidd ac 16 GB
  gyda `--profile full` (mae ClamAV yn unig yn dal tua 1.5 GB o lofnodion).
- Enw DNS ar gyfer yr haen we ac un arall ar gyfer cynnwys nad yw'n ddibynadwy. Rhaid iddynt fod yn hostiaid gwahanol: mae pecynnau SCORM a HTML a lwythir i fyny yn rhedeg o'r tarddiad cynnwys
  fel na allant byth ddarllen cwcis y LMS.
- Ar gyfer prawf lleol, mae `lvh.me` a `*.localhost` yn datrys i 127.0.0.1, sef
  yr hyn y mae `docker/.env.example` yn ei ddefnyddio. Mae gwasanaeth `proxy` y stack ei hun yn gwasanaethu'r
  ddau dros https gydag awdurdod tystysgrif lleol, felly nid oes angen gosod dim arall (gweler “TLS”).
- Porthladdoedd 80 a 443 yn rhydd ar y host (`QUIRE_PROXY_HTTP_PORT` a
  `QUIRE_PROXY_HTTPS_PORT` sy'n eu symud).

## Rhediad cyntaf <!--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
```

Mae `docker/scripts/init-env.sh` yn ysgrifennu `docker/.env` o `docker/.env.example`
gyda phob cyfrinach wedi'i chynhyrchu (cyfrineiriau cronfa ddata, yr allweddi llofnodi a meistr,
pâr allweddi lansio cynnwys) ac allwedd llofnodi pwynt archwilio yn
`docker/secrets/audit-signing-key.pem`, y mae Compose yn ei mowntio i'r gweithwyr
fel cyfrinach. Dim ond `sh`, `awk` ac `openssl` sydd eu hangen arno, ac mae'n gwrthod
ailysgrifennu `docker/.env` sy'n bodoli eisoes. Copïwch y ddwy ffeil oddi ar y host: heb
`QUIRE_MASTER_KEY` ni all cronfa ddata a adferwyd ddadgryptio ei manylion mewngofnodi sydd wedi'u storio.
I lenwi'r ffeil â llaw yn lle hynny, `cp docker/.env.example docker/.env`; mae'r
ffeil yn dweud sut i gynhyrchu pob cyfrinach.

Rhaid i'r ddau darddiad fod yn `https`: mae'r gwasanaeth cynnwys yn gwrthod http plaen mewn
cynhyrchu, ac ni ddylent rannu parth cofrestradwy. Mae'r gwasanaeth `proxy`
yn terfynu TLS ar gyfer y ddau (gweler “TLS”); mae `init-env.sh` yn gwrthod
 tarddiad `http://`.

Mae'r stack yn cychwyn mewn trefn sefydlog, ac mae pob cam yn aros am y cam o'i flaen:

1. Daw `postgres` yn iach. Ar y cychwyn cyntaf mae ei sgript cychwyn
   (`docker/postgres/init/90-passwords.sh`) yn gosod pedwar cyfrinair rôl.
2. Mae `migrate` yn cymhwyso pob mudo ac yn cychwyn ciw'r swyddi yn y
gronfa ddata reoli ac ym mhob cronfa ddata tenant benodedig, yn gwirio eu bod i gyd
   eu bod i gyd yn cytuno, ac yna'n gadael (docs/ops/upgrade.md).
   Mae mudo'n rhedeg ar bob cychwyn ac yn idempotent, felly delwedd newydd ac ailgychwyn yw uwchraddiad.
3. Mae `init` (`apps/web/src/first-run.ts`) yn cofnodi cronfa ddata'r rhaglen o dan
   `QUIRE_DATABASE_ID` a, phan osodir `QUIRE_SETUP_ADMIN_EMAIL`, yn creu'r
   sefydliad cyntaf a'i weinyddwr. Caiff cyfeiriad mewngofnodi a chyfrinair
   a gynhyrchwyd eu hargraffu unwaith yn `docker compose logs init`.
4. Mae `web`, `content`, `worker`, `scheduler`, `collab` a `centrifugo` yn cychwyn.
5. Mae `proxy` yn cychwyn unwaith y bydd `web` a `content` yn iach.

Agorwch `https://demo.` ac yna barth eich rhaglen (mae'r cofnod `init`
yn argraffu'r union gyfeiriad mewngofnodi), a mewngofnodwch. Ar osodiad lleol, ymddiriedwch yn
awdurdod tystysgrif y proxy yn gyntaf (gweler “TLS”). Newidiwch y cyfrinair a gynhyrchwyd yn `/account/security`.

Mae proses a gychwynnwyd heb gyfrinach ofynnol yn gwrthod cychwyn ac yn enwi'r
 gosodiad coll yn ei chofnod. Ni fydd dim yn cychwyn wedi'i ffurfweddu'n rhannol.

## Gwasanaethau a phroffiliau <!--quire:services-and-profiles-->

| Gwasanaeth | Proffil | Beth mae'n ei wneud |
| --- | --- | --- |
| postgres | bob amser | Y gronfa ddata (PostgreSQL 18 gyda pgvector, wedi'i adeiladu o `docker/postgres.Dockerfile`), gyda WAL wedi'i archifo o'r cychwyn cyntaf |
| migrate, init | bob amser | Unwaith: mudo, yna'r rhediad cyntaf |
| web | bob amser | Y LMS, ar `QUIRE_HTTP_PORT` (8080) |
| content | bob amser | Tarddiad cynnwys nad yw'n ddibynadwy, ar `QUIRE_CONTENT_PORT` (8081) |
| worker | bob amser | Swyddi cefndir: e-bost, adroddiadau, prosesu ffeiliau, webhooks |
| scheduler | bob amser | Swyddi rheolaidd: cofrestru 64 amserlen amser rhedeg a'u trosglwyddo i'r worker; un arweinydd ar y tro |
| collab | bob amser | Websocket golygu cydweithredol, ar `QUIRE_COLLAB_HTTP_PORT` (1234) |
| centrifugo | bob amser | Dosbarthu amser real, ar `QUIRE_REALTIME_PORT` (8000) |
| proxy | bob amser | Caddy, y drws TLS blaen ar borthladdoedd 80 a 443 (gweler “TLS”) |
| valkey | `cache` | Storfa dros dro a therfynau cyfradd |
| clamav | `scan` | Sganio meddalwedd faleisus mewn llwythiadau |
| gotenberg | `preview` | Rhagolygon Office i PDF, rendro tystysgrifau |
| imgproxy | `images` | Ailfeintio a throsi delweddau |
| transcoder | `video` | Delwedd worker gyda ffmpeg LGPL yn unig, ar gyfer fersiynau fideo wedi'u rendro |
| seaweedfs | `storage` | Storfa gwrthrychau sy'n gydnaws â S3 ar y host hwn |
| otelcol | `observability` | Casglwr OpenTelemetry |
| mailpit | `devmail` | Dal yr holl bost sy'n mynd allan, i roi cynnig ar Quire |
| backup | `backup` | Copi wrth gefn sylfaenol unwaith; gweler backup-restore.md |
| backup-scheduler, backup-offsite | `backup` | Copi wrth gefn sylfaenol bob `QUIRE_BACKUP_INTERVAL_HOURS`, a chopïau wedi'u hamgryptio oddi ar y host gyda phrawf gwirio wythnosol |
| h5p | `h5p` | Delwedd offeryn H5P LTI 1.3 a ddarperir gennych yn `QUIRE_H5P_IMAGE`, ar `QUIRE_H5P_PORT` (8090); gweler “Cysylltu darparwr H5P” |

Mae `--profile full` yn cychwyn pob gwasanaeth dewisol heblaw `backup` a `h5p`.
Dechreuwch un gyda `docker compose -f docker/compose.yaml --profile scan up -d`.
Heb wasanaeth dewisol, mae Quire yn dal i weithio ac yn dweud beth sydd ar goll: heb
sganiwr cedwir llwythiadau heb eu sganio a rhoddir gwybod i'r gweinyddwr; heb Gotenberg, cynigir lawrlwytho ffeiliau yn lle rhagolwg; heb drawsnewidydd, caiff fideo ei chwarae fel y ffeil wreiddiol.

Rhestrir pob delwedd trydydd parti a'i rhwymedigaethau trwydded yn
`docker/third-party-containers.yaml`.

### Cysylltu darparwr H5P <!--quire:connecting-an-h5p-provider-->

Nid yw Quire yn mewnosod nac yn cludo runtime neu sidecar H5P (ADR 0019). Os ydych yn defnyddio
H5P, darparwch eich tanysgrifiad lletyol eich hun neu weithredwch eich instans H5P hunangynhaliol eich hun ar wahân i Quire. Cofrestrwch y darparwr hwnnw fel offeryn allanol LTI 1.3
ac ychwanegwch ei gynnwys at gyrsiau fel gweithgareddau offeryn. Mae Quire yn cyfnewid graddau
a chynnydd gweithgaredd/marcio drwy LTI Assignment and Grade Services (AGS).
Os bydd y darparwr hefyd yn anfon datganiadau xAPI, ffurfweddwch hynny ar wahân ar gyfer
storfa datganiadau xAPI Quire; nid yw cyfnewid graddau/cynnydd AGS yn anfon datganiadau xAPI.
Mae mewnforion Moodle yn adrodd bod angen cysylltiad offeryn LTI ar weithgareddau H5P.
Mae'r darparwr yn parhau'n gyfrifol am ei runtime H5P, ei awduro,
 ei fanc cynnwys a'i hanes ymdrechion.

I redeg eich instans hunangynhaliol eich hun ar y host hwn, gosodwch `QUIRE_H5P_IMAGE` i'w
ddelwedd a dechreuwch broffil `h5p`. Mae Compose yn ei gyhoeddi ar `QUIRE_H5P_PORT`
(8090) ac yn cadw ei ddata yng nghyfrol `h5p-data`; eich cyfrifoldeb chi yw'r ddelwedd a'r
rhwymedigaethau sy'n dod gyda hi.

## Gosodiadau <!--quire:settings-->

Mae pob proses yn darllen `docker/.env`. Mae'r templed, `docker/.env.example`, yn rhestru
pob gosodiad a'i ragosodiad. Y grwpiau:

### Cyfeiriadau <!--quire:addresses-->

| Gosodiad | Ystyr |
| --- | --- |
| `QUIRE_APP_ORIGIN` | Cyfeiriad cyhoeddus y LMS, megis `https://learn.example.com` |
| `QUIRE_CONTENT_ORIGIN` | Tarddiad cynnwys, host gwahanol |
| `QUIRE_PLATFORM_DOMAINS` | Parthau y mae sefydliadau'n byw oddi tanynt, wedi'u gwahanu gan goma |
| `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` yma. Gweler y canllawiau eraill am `vercel` a `cloudflare` |
| `QUIRE_TRUSTED_PROXY_CIDRS` | Proxy y credir eu `X-Forwarded-For` |

### Cyfrinachau <!--quire:secrets-->

| Gosodiad | Ystyr |
| --- | --- |
| `QUIRE_SECRET_KEY` | Llofnodi sesiynau a thocynnau. 64 nod hecsadegol |
| `QUIRE_MASTER_KEY` | Lapio manylion mewngofnodi sydd wedi'u storio fel cyfrinachau SSO a webhook. 32 beit, base64. Mae angen yr un gwerth ar yr haen we a'r worker. Newid: [key-rotation.md](/cy/ops/key-rotation/) |
| `QUIRE_MASTER_KEY_VERSION` | Label fersiwn yr allwedd feistr, `v1` os nad yw wedi'i gosod. Codwch hi wrth newid yr allwedd |
| `QUIRE_MASTER_KEY_RETIRED` | Allweddi meistr cynharach sydd eu hangen o hyd i ddarllen yr hyn a seliwyd ganddynt, fel `v1=<base64>`. Tynnwch ar ôl i newid orffen heb ddim heb ei ddatrys |
| `QUIRE_COLLAB_SIGNING_KEY` | Wedi'i rhannu gan web a collab i lofnodi tocynnau golygu |
| `QUIRE_BACKUP_SIGNING_KEY` | Llofnodi copïau wrth gefn cwrs (dewisol) |

Cadwch gopi o `QUIRE_MASTER_KEY` rywle heblaw'r host hwn. Ni all cronfa ddata
 a adferwyd hebddi ddadgryptio'r manylion mewngofnodi sydd ynddi.

### Cronfa ddata <!--quire:database-->

| Gosodiad | Ystyr |
| --- | --- |
| `POSTGRES_PASSWORD` | Y superuser, a ddefnyddir gan y cynhwysydd a'r copïau wrth gefn |
| `QUIRE_DB_APP_PASSWORD`, `QUIRE_DB_MIGRATOR_PASSWORD`, `QUIRE_DB_REPORT_PASSWORD`, `QUIRE_DB_AUDIT_PASSWORD` | Cyfrineiriau rôl, wedi'u gosod ar y cychwyn cyntaf |
| `DATABASE_URL` | Rôl y rhaglen. Mae diogelwch ar lefel rhes yn berthnasol i bob ymholiad y mae'n ei wneud |
| `DATABASE_MIGRATOR_URL`, `QUIRE_MIGRATION_URL` | Rôl mudo, ar gyfer `migrate` a `init` |
| `QUIRE_SUPERUSER_URL` | Defnyddir ar gyfer y rhediad cyntaf yn unig |
| `QUIRE_REPORT_DATABASE_URL` | Rôl adrodd darllen-yn-unig, ar gyfer adroddiadau a'r adeiladydd adroddiadau |
| `QUIRE_AUDIT_DATABASE_URL` | Rôl archwilio, ar gyfer y consol archwilio ac allforio SIEM |
| `QUIRE_DATABASE_ID` | Unrhyw UUID, yn sefydlog am oes y gosodiad |

Dim ond pan gaiff cyfrol y gronfa ddata ei chreu am y tro cyntaf y cymhwysir cyfrineiriau rôl.
I newid un yn ddiweddarach, defnyddiwch `ALTER ROLE` ac yna diweddarwch yr URL cyfatebol.

Defnyddir `QUIRE_REPORT_DATABASE_URL` ar gyfer y gronfa ddata ffisegol a ffurfweddwyd gan
`DATABASE_URL`. Ar gyfer unrhyw gronfa ddata ffisegol gofrestredig arall, gosodwch ei URL cysylltiad
`quire_report` ei hun yn amgylcheddau'r we a'r worker, yna rhowch
enw'r newidyn yng maes **Newidyn amgylchedd adrodd** y gronfa ddata honno
fel `env:NAME`. Rhaid i'r cyfeirnod bwyntio at yr un gronfa ddata â chysylltiad yr ap,
sef ei replica darllen yn ddelfrydol. Mae pob rhyngwyneb adrodd yn dilyn y
tenant i gysylltiad adrodd ei gronfa ddata ei hun: yr adeiladydd adroddiadau a'r
adroddiadau a gadwyd, dosbarthiadau wedi'u trefnu, allforion adroddiadau, dadansoddeg,
cofnod archwilio, adnoddau archwilio REST a chwiliad archwilio'r cynorthwyydd. Nid oes
un ohonynt byth yn benthyg URL adrodd cronfa ddata arall. Pan nad oes gan gronfa ddata
gysylltiad adrodd, mae adroddiadau arferol yn rhedeg ar ei chysylltiad rhaglen ei hun,
tra bo dadansoddeg a phob darlleniad archwilio'n gwrthod ac yn dweud hynny, oherwydd
na all rôl y rhaglen ddarllen y cofnod archwilio.

### Gyrwyr <!--quire:drivers-->

| Gosodiad | Y datganiad hwn | Nodiadau |
| --- | --- | --- |
| `QUIRE_STORAGE_DRIVER` | `local` (diofyn), `s3` neu `azure` | Mae `local` yn cadw ffeiliau yn y gyfrol `files`. Mae `s3` yn cynnwys AWS S3, cydnawsedd R2 a GCS, a storfeydd eraill sy'n gydnaws â S3, gyda llwythiadau aml-ran y gellir eu hailddechrau |
| `QUIRE_REALTIME_DRIVER` | `inprocess` (diofyn), `sse`, `centrifugo` neu `durable_objects` | Mae `inprocess` yn briodol ar gyfer un cynhwysydd web; defnyddiwch `centrifugo` neu `sse` os oes sawl un |
| `QUIRE_CACHE_DRIVER` | `memory` (diofyn), `postgres` neu `valkey` | Mae `memory` fesul proses; defnyddiwch `valkey` neu `postgres` fel bod terfynau cyfradd yn gyson ar draws cynwysyddion |
| `QUIRE_VIDEO_DRIVER` | `ffmpeg` (diofyn) neu `progressive_mp4` | Neu ddarparwr lletyol: Cloudflare Stream, Mux neu Bunny, drwy eu hallweddi |
| `QUIRE_IMAGE_DRIVER` | `noop` (diofyn), `imgproxy` neu `cloudflare` | Mae `noop` yn gwasanaethu pob delwedd ar ei maint gwreiddiol. Mae angen i `imgproxy` gael proffil `images` a'r gosodiadau isod; mae `cloudflare` yn defnyddio Cloudflare Images |
| `QUIRE_MEETING_PROVIDER` | `bbb`, `zoom`, `teams`, `meet`, `jitsi` neu `in_process` | Darparwr diofyn y platfform ar gyfer sesiynau byw. Os na chaiff ei osod, dywed sesiynau byw nad ydynt wedi'u ffurfweddu nes bod sefydliad yn cysylltu ei gyfrif ei hun o dan Integreiddiadau, Darparwr sesiynau byw. Mae cyfrif sefydliad ei hun bob amser yn cael blaenoriaeth dros y gwerth hwn. Dim ond ar gyfer y darparwr a enwir yma y darllenir gosodiadau pob darparwr (`BBB_URL` a `BBB_SECRET`, y newidynnau `ZOOM_*`, `TEAMS_*`, `GOOGLE_MEET_*` a `JITSI_*`) |
| `QUIRE_MEETING_REGIONS` | Rhestr wedi'i gwahanu gan goma o `eu`, `uk`, `us` | Lle mae darparwr diofyn y platfform yn prosesu cyfarfodydd. Os heb ei osod, ni chaiff ei wirio yn erbyn sefydliad wedi'i binio i ranbarth, fel o'r blaen. Mae cyfrif sefydliad ei hun yn datgan ei ranbarthau ar ei dudalen |

Gwrthodir gwerth gyrrwr nad yw'r datganiad hwn yn ei gynnwys pan fydd yr haen we'n cychwyn,
gan enwi'r gosodiad, yn hytrach na'i ddisodli'n dawel â'r
rhagosodiad.

### Delweddau <!--quire:images-->

Mae tudalennau'n gofyn am ddelweddau mewn pedwar maint sefydlog drwy
`/api/files/{id}/image/{size}`, sy'n gwirio'r un mynediad â'r ffeil ei
hun ac yna'n ailgyfeirio at wasanaeth y ddelwedd. Gall pob sefydliad ofyn am
`QUIRE_IMAGE_SPECS_PER_HOUR` (diofyn 2000) parau delwedd a maint newydd yr
awr; nid yw meintiau a gynhyrchwyd eisoes yr awr honno'n cyfrif. Defnyddiwch `valkey` neu
`postgres` ar gyfer `QUIRE_CACHE_DRIVER` gyda mwy nag un cynhwysydd web fel bod y
terfyn yn berthnasol iddynt i gyd.

| Gosodiad | Gyrrwr | Nodiadau |
| --- | --- | --- |
| `IMGPROXY_URL` | `imgproxy` | Y cyfeiriad y mae porwyr yn cyrraedd imgproxy ynddo, er enghraifft `https://images.example.org`. Mae proffil `images` yn ei gyhoeddi ar `QUIRE_IMAGES_PORT` (8082) |
| `IMGPROXY_KEY`, `IMGPROXY_SALT` | `imgproxy` | Llinynnau hecsadegol, yr un gwerthoedd ag y cychwynnir imgproxy gyda nhw. Cynhyrchwch bob un gyda `openssl rand -hex 32`. Mae Quire yn llofnodi pob cyfeiriad delwedd â nhw, felly nid yw imgproxy'n rendro dim na ofynnodd Quire amdano |
| `QUIRE_IMAGE_SOURCE_ORIGIN` | `imgproxy` gyda storfa leol | O ble mae imgproxy'n nôl y rhai gwreiddiol. Mae Compose yn gosod `http://web:3000`. Gyda storfa `s3` neu `azure`, mae imgproxy'n nôl o'r bwced ac ni ddefnyddir hwn |
| `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_IMAGES_TOKEN`, `CLOUDFLARE_IMAGES_ACCOUNT_HASH` | `cloudflare` | Tocyn API gyda chaniatâd golygu Images, a hash y cyfrif o Images, adnoddau datblygwr. Trowch amrywiadau hyblyg ymlaen ar gyfer y cyfrif |
| `CLOUDFLARE_IMAGES_SIGNING_KEY` | `cloudflare` | Dewisol. Pan fydd wedi'i osod, mae delweddau'n breifat a chaiff pob cyfeiriad ei lofnodi ac mae'n dod i ben. Hebddo, mae delweddau'n gyhoeddus mewn cyfeiriadau sy'n deillio o `QUIRE_SECRET_KEY` ac na all neb eu dyfalu |

Mae Cloudflare Images yn cadw ei gopi ei hun o bob gwreiddiol mae'n ei wasanaethu. Pan gaiff
ffeil ei dileu, mae'r worker yn dileu'r copi hwnnw cyn y gwreiddiol.

### Ciw <!--quire:queue-->

Mae swyddi cefndir yn defnyddio pg-boss yn yr un gronfa ddata Postgres, felly nid oes
angen rhedeg gwasanaeth ciw na ffurfweddu dim. Caiff swyddi eu ciwio yn yr un
trafodiad â'r newid a'u hachosodd, felly ni all damwain golli un na'i
hanfon ddwywaith. `QUIRE_QUEUE_DRIVER` yw `pgboss` yma, ei ragosodiad;
mae `vercel` a `cloudflare` yn symud hysbysiadau ysgafn a dosbarthiadau webhook yn unig i giw
 y platfform ei hun; mae canllawiau Vercel a Cloudflare yn eu disgrifio a sut mae eu haenau gwe'n eu ciwio.

### E-bost <!--quire:email-->

Gosodwch un o'r rhain:

- `QUIRE_EMAIL_PROVIDER_CONFIG`: gwrthrych JSON sy'n enwi darparwr HTTP a'i
  fanylion mewngofnodi, megis `{"provider":"postmark","token":"..."}`. Cefnogir Postmark,
  Amazon SES, Mailgun, SendGrid a Resend.
- `QUIRE_SMTP_URL`: `smtp://user:password@host:587`. Ar y targed hwn yn unig; mae
  targedau heb weinydd yn rhwystro SMTP.

`QUIRE_MAIL_FROM` yw'r anfonwr. I roi cynnig ar Quire, dechreuwch broffil `devmail`,
gosodwch `QUIRE_SMTP_URL=smtp://mailpit:1025`, a darllenwch bost yn
`http://localhost:8025`.

### Gwasanaethau dewisol <!--quire:optional-services-->

| Gosodiad | Gyda phroffil |
| --- | --- |
| `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` neu `QUIRE_MEILISEARCH_URL` | Chwilio allanol; fel arall chwilio testun llawn Postgres |
| `QUIRE_BREACH_CHECK_PROVIDER=off`, `QUIRE_BREACH_CHECK_URL` | Gwirio cyfrineiriau a ddatgelwyd. Ymlaen yn ddiofyn drwy `api.pwnedpasswords.com` (dim ond rhagddodiad hash pum nod a anfonir); mae `off` yn ei ddiffodd, ac mae'r URL yn pwyntio at API ystod rydych yn ei gynnal |

### Arsylwadwyedd <!--quire:observability-->

Mae `OTEL_EXPORTER_OTLP_ENDPOINT` yn enwi'r casglwr y mae pob proses yn anfon
olion a metrigau ato; gyda phroffil `observability` mae'n
`http://otelcol:4318`, ac `docker/otel-collector.yaml` yw lle i ychwanegu'r
allforiwr ar gyfer eich ôl-wyneb. Mae prosesau web, worker, scheduler, content a collab yn allforio bylchau dros OTLP/HTTP (ceisiadau web, trafodion cronfeydd data tenant,
swyddi worker a galwadau allan) pan fydd wedi'i osod, a metrigau i'r un endpoint bob munud (`OTEL_METRICS_EXPORTER=none` sy'n eu diffodd).
Mae `OTEL_TRACES_SAMPLER_ARG` yn gosod cyfran yr olion a gedwir. Mae logiau'n mynd i
allbwn safonol ar `LOG_LEVEL`, ac mae Compose yn eu cylchdroi. Nid yw olion byth yn cario data personol.

### Egress rhanbarthol (preswyliaeth data'r UE) <!--quire:regional-egress-eu-data-residency-->

Mae `QUIRE_REGION=eu` yn datgan bod y stack yn gwasanaethu sefydliadau'r Undeb Ewropeaidd. Mae'r
worker wedyn yn dal pob cais allanol a wneir ar ran sefydliad wedi'i binio i'r UE at restr ganiatáu (adran 8.1 yn 21-compliance.md). Y rhestr ganiatáu yw'r
hostiaid y mae gwasanaethau wedi'u ffurfweddu'n eu datgan ar gyfer y rhanbarth (endpoint y storfa,
darparwr e-bost, darparwr fideo lletyol, targedau storio'r sefydliad ei hun,
darparwyr AI a chyfrif e-bost), hostiaid unrhyw wasanaeth sydd dan eithriad gweithredol, a'r hostiaid rydych yn eu rhestru yn
`QUIRE_EGRESS_ALLOW_HOSTS`. Gwrthodir cais at unrhyw host cyhoeddus arall
cyn ei anfon, ysgrifennir y gwrthodiad yng nghofnod archwilio'r sefydliad fel
`privacy/egress_refused`, ac fe'i rhestrir o dan Cydymffurfiaeth, Preswyliaeth data.

| Gosodiad | Gwerthoedd | Effaith |
| --- | --- | --- |
| `QUIRE_EGRESS_ALLOW_HOSTS` | Rhestr o enwau host wedi'u gwahanu gan goma, neu `*.example.org` ar gyfer pob is-barth | Hostiaid ychwanegol y gall sefydliad UE eu cyrraedd. Mae endpointau webhook, xAPI a SIEM, ffrydiau blog a hostiaid Amazon SES yn perthyn yma, oherwydd dewis y sefydliad ei hun ydynt ac nid oes gwasanaeth yn eu datgan. Eich rhwydwaith eich hun yw loopback, cyfeiriadau preifat ac enwau un label megis `web` neu `clamav`, ac ni chânt eu gwirio byth |

Nid yw sefydliadau'r DU a'r Unol Daleithiau wedi'u cyfyngu i restr host; maent yn cadw gwiriadau rhanbarth gwasanaeth. Gosodwch y rhestr ar y worker; mae'r dudalen weinyddol yn ei darllen ar yr haen we
i ddangos y rhestr ganiatáu, felly rhowch hi yn `docker/.env`, a ddarllenir gan bob gwasanaeth.

Mae gwiriad y rhaglen yn rhoi gwall clir a chofnod archwilio, ond nid dyma'r warant: gall cod fod yn anghywir. Y rhwydwaith yw'r warant. Nid yw Compose yn ei gorfodi drosoch. Ar gyfer stack rhanbarthol, rhowch wasanaethau `worker` a `web`
ar rwydwaith `internal: true` a'i unig lwybr allan yw
proxy egress (er enghraifft cynhwysydd Squid neu tinyproxy) sy'n caniatáu'r un hostiaid
â `QUIRE_EGRESS_ALLOW_HOSTS` ynghyd â hostiaid eich gwasanaethau ffurfweddu, a
gosodwch `HTTPS_PROXY` ar gyfer y gwasanaethau hynny. Mae'r dudalen preswyliaeth yn rhestru'r hostiaid union
 y mae'r rhaglen yn eu caniatáu, felly gellir cymharu'r ddwy restr.

## Iechyd <!--quire:health-->

| Endpoint | Ystyr |
| --- | --- |
| `/healthz` | Bywiogrwydd: mae'r broses yn ateb. Mae gwiriadau iechyd Compose yn defnyddio hwn |
| `/readyz` | Parodrwydd: dibyniaethau ar gael, a phob gwasanaeth dewisol wedi'i adrodd fel wedi'i ffurfweddu neu beidio. Pwyntiwch eich cydbwysydd llwyth yma |

Mae `docker compose -f docker/compose.yaml ps` yn dangos iechyd pob gwasanaeth.

## TLS <!--quire:tls-->

Mae gwasanaeth `proxy` (Caddy, Apache-2.0, `docker/caddy/Caddyfile`) yn rhan o'r
stack diofyn. Mae'n ateb ar borthladdoedd 80 a 443 ac yn llwybro:

| Host neu lwybr | Yn mynd at |
| --- | --- |
| `QUIRE_PROXY_CONTENT_HOST` | `content` |
| `QUIRE_PROXY_APP_HOST`, pob is-barth tenant a pharth personol | `web` |
| `/_collab/` ar y hostiaid hynny | `collab` (websocket, `QUIRE_COLLAB_URL`) |
| `/_realtime/connection/` ar y hostiaid hynny | Websocket cleient `centrifugo`; ni ddatgelir ei API gweinydd |
| `/_images/` ar y hostiaid hynny | `imgproxy`, gyda phroffil `images` (`IMGPROXY_URL`) |

Mae `init-env.sh` yn deillio `QUIRE_PROXY_APP_HOST`, `QUIRE_PROXY_CONTENT_HOST`,
`QUIRE_PROXY_HTTPS_PORT`, `QUIRE_COLLAB_URL` ac `IMGPROXY_URL` o'r ddau
darddiad, felly ni allant wyro oddi wrth ei gilydd. Golygwch nhw gyda'i gilydd os newidiwch
 darddiad â llaw.

Mae tystysgrifau'n dilyn `QUIRE_PROXY_TLS`:

- `internal` (diofyn): awdurdod tystysgrif Caddy ei hun, ar gyfer
  `localhost`, `*.localhost` a `lvh.me`. Ymddiriedwch yn ei wraidd unwaith, yna porwch:

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

  Ychwanegwch `quire-local-ca.crt` at storfa ymddiriedaeth y system neu'r porwr. Mae `curl`
  yn ei dderbyn drwy `--cacert`.
- Cyfeiriad e-bost: tystysgrifau ACME awtomatig (Let's Encrypt, yna
  ZeroSSL) ar gyfer enwau host go iawn. Rhaid i DNS y ddau darddiad a phob host tenant
  bwyntio yma, a rhaid bod modd cyrraedd porthladdoedd 80 a 443 o'r rhyngrwyd.

Rhoddir hostiaid tenant ar alw, ar yr ymweliad cyntaf, a dim ond pan fydd web yn
cadarnhau bod yr enw'n perthyn i'r gosodiad hwn (`/tls-allowed`, a ofynnir ar
rwydwaith Compose). Nid oes angen tystysgrif wildcard nac ategyn darparwr DNS,
ac ni all dieithryn sy'n pwyntio enw at y host beri iddo ofyn am
 dystysgrifau. Mae tystysgrifau a'r awdurdod lleol yng nghyfrol
`caddy-data`; gwnewch gopi wrth gefn gyda'r gweddill os defnyddiwch `internal`.

Mae Web yn ymddiried yn `X-Forwarded-For` o'r proxy yn unig: mae gan y proxy gyfeiriad
sefydlog (`QUIRE_PROXY_ADDRESS`, diofyn `172.29.64.10`) ar is-rwydwaith sefydlog
(`QUIRE_COMPOSE_SUBNET`), ac mae `QUIRE_TRUSTED_PROXY_CIDRS` yn enwi'r cyfeiriad hwnnw.
Os bydd yr is-rwydwaith yn gwrthdaro â rhwydwaith ar y host, newidiwch y ddau a rhedwch
`docker compose down` cyn `up`.

## Y tu ôl i'ch proxy gwrthdro eich hun <!--quire:behind-your-own-reverse-proxy-->

I ddefnyddio cydbwysydd llwyth neu proxy rydych eisoes yn ei redeg yn lle hynny, peidiwch â chynnwys
`proxy` (`docker compose up -d --scale proxy=0`) a therfynwch TLS o flaen `web`
(8080), `content` (8081), `collab` (1234, websocket) a `centrifugo` (8000,
websocket). Gosodwch y cyfeiriadau cyhoeddus yn `QUIRE_APP_ORIGIN`,
`QUIRE_CONTENT_ORIGIN` a `QUIRE_COLLAB_URL` (`wss://`), ac ystod cyfeiriadau eich proxy
yn `QUIRE_TRUSTED_PROXY_CIDRS`.

## Datrys problemau <!--quire:troubleshooting-->

- Mae `init` yn gadael gyda “QUIRE_DATABASE_ID is not a UUID”: gosodwch ef gyda `uuidgen`.
- Mae `web` yn ailgychwyn gyda “did not start on compose”: mae'r log yn rhestru pob gosodiad
  na all ei barchu a beth i'w ddefnyddio yn ei le.
- Nid yw newid cyfrinair rôl yn `.env` ar ôl y cychwyn cyntaf yn gwneud dim: dim ond unwaith mae'r
  sgript cychwyn yn rhedeg. Defnyddiwch `ALTER ROLE`.
- Mae llwythiadau'n methu â gwall sgan tra bo `CLAMAV_URL` wedi'i osod: mae ClamAV yn lawrlwytho
  ei lofnodion ar y cychwyn cyntaf, sy'n cymryd ychydig funudau.

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