---
title: "Installazzjoni ta' Quire b'Docker Compose"
description: "Installa Quire fuq l-infrastruttura tiegħek b'Docker Compose."
image: "https://docs.quirelms.com/og.png"
---

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

# Installazzjoni ta' Quire b'Docker Compose

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

Dan huwa l-prodott sħiħ fuq host wieħed: l-LMS, ix-xogħol fl-isfond tiegħu, is-
servizzi realtime u tal-editjar kollaborattiv, u kull servizz fakultattiv
wara profil. Id-disinn jinsab f'`docs/architecture/23-ops.md` sezzjoni 2.

Miri oħra: [Vercel](/mt/ops/vercel/) u [Cloudflare Workers](/mt/ops/cloudflare/) imexxu
l-livell web biss. L-aġġornamenti jinsabu f'[upgrade.md](/mt/ops/upgrade/), u l-backups u
d-drill tar-restore f'[backup-restore.md](/mt/ops/backup-restore/).

## X'għandek bżonn <!--quire:what-you-need-->

- Docker Engine 27 jew aktar ġdid bil-plugin Compose 2.30 jew aktar ġdid.
- 4 cores tas-CPU u 8 GB memorja għall-istack default; 8 cores u 16 GB
  b'`--profile full` (ClamAV waħdu jżomm madwar 1.5 GB ta' signatures).
- Isem DNS għal-livell web u ieħor għall-kontenut mhux fdat. Iridu
  jkunu hosts differenti: pakketti SCORM u HTML imtella' jaħdmu fuq l-oriġini tal-kontenut
  biex qatt ma jistgħu jaqraw il-cookies tal-LMS.
- Għal test lokali, `lvh.me` u `*.localhost` isolvu għal 127.0.0.1, li
  huwa dak li juża `docker/.env.example`. Is-servizz `proxy` tal-istack iservi
  lit-tnejn fuq https b'awtorità taċ-ċertifikati lokali, biex xejn ieħor ma huwa
  installat (ara "TLS").
- Ports 80 u 443 ħielsa fuq il-host (`QUIRE_PROXY_HTTP_PORT` u
  `QUIRE_PROXY_HTTPS_PORT` iċaqalquhom).

## L-ewwel tħaddim <!--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
```

`docker/scripts/init-env.sh` jikteb `docker/.env` minn `docker/.env.example`
b'kull sigriet iġġenerat (passwords tad-database, iċ-ċwievet tal-iffirmar u master,
il-par taċ-ċwievet tat-tnedija tal-kontenut) u ċ-ċavetta tal-iffirmar tal-checkpoint tal-verifika f'
`docker/secrets/audit-signing-key.pem`, li Compose jmountja fil-workers
bħala sigriet. Jeħtieġ biss `sh`, `awk` u `openssl`, u jirrifjuta li
jissostitwixxi `docker/.env` eżistenti. Ikkopja ż-żewġ fajls barra l-host: mingħajr
`QUIRE_MASTER_KEY` database rrestawrata ma tistax tiddekripta l-kredenzjali maħżuna tagħha.
Biex timla l-fajl bl-idejn minflok, `cp docker/.env.example docker/.env`; il-
fajl jgħid kif tiġġenera kull sigriet.

Iż-żewġ oriġini jridu jkunu `https`: is-servizz tal-kontenut jirrifjuta http sempliċi fi
produzzjoni, u ma jridux jaqsmu dominju reġistrabbli. Is-servizz `proxy`
itemm TLS għat-tnejn (ara "TLS"); `init-env.sh` jirrifjuta oriġini
`http://`.

L-istack jibda f'ordni fissa, u kull pass jistenna lil ta' qablu:

1. `postgres` isir b'saħħtu. Fl-ewwel bidu nett l-iskript init tiegħu
   (`docker/postgres/init/90-passwords.sh`) jissettja l-erba' passwords tar-rwoli.
2. `migrate` japplika kull migrazzjoni u jibbutstrapja l-queue tax-xogħol fid-
   database tal-kontroll u f'kull database dedikata tat-tenant, jiċċekkja li huma
   kollha jaqblu, imbagħad joħroġ (docs/ops/upgrade.md).
   Il-migrazzjonijiet jaħdmu f'kull bidu u huma idempotenti, biex aġġornament huwa immaġni
   ġdida u restart.
3. `init` (`apps/web/src/first-run.ts`) jirreġistra d-database tal-applikazzjoni taħt
   `QUIRE_DATABASE_ID` u, meta `QUIRE_SETUP_ADMIN_EMAIL` huwa ssettjat, joħloq l-
   ewwel organizzazzjoni u l-amministratur tagħha. L-indirizz tad-dħul u
   password iġġenerata jiġu stampati darba, f'`docker compose logs init`.
4. `web`, `content`, `worker`, `scheduler`, `collab` u `centrifugo` jibdew.
5. `proxy` jibda ladarba `web` u `content` ikunu b'saħħithom.

Iftaħ `https://demo.` segwit mid-dominju tal-applikazzjoni tiegħek (il-log `init`
jistampa l-indirizz eżatt tad-dħul), u idħol. Fuq installazzjoni lokali, afda
l-awtorità taċ-ċertifikati tal-proxy l-ewwel (ara "TLS"). Biddel il-password iġġenerata f'`/account/security`.

Proċess mibdi mingħajr sigriet meħtieġ jirrifjuta li jibda u jsemmi s-
setting nieqes fil-log tiegħu. Xejn ma jibda kkonfigurat nofsu.

## Servizzi u profili <!--quire:services-and-profiles-->

| Service | Profile | What it does |
| --- | --- | --- |
| postgres | always | Id-database (PostgreSQL 18 b'pgvector, mibnija minn `docker/postgres.Dockerfile`), b'WAL arkivjat mill-ewwel boot |
| migrate, init | always | One-shot: migrazzjonijiet, imbagħad l-ewwel tħaddim |
| web | always | L-LMS, fuq `QUIRE_HTTP_PORT` (8080) |
| content | always | L-oriġini tal-kontenut mhux fdat, fuq `QUIRE_CONTENT_PORT` (8081) |
| worker | always | Xogħol fl-isfond: email, rapporti, ipproċessar ta' fajls, webhooks |
| scheduler | always | Xogħol rikorrenti: jirreġistra l-64 skeda ta' runtime u jgħaddihom lill-worker; mexxej wieħed kull darba |
| collab | always | Websocket tal-editjar kollaborattiv, fuq `QUIRE_COLLAB_HTTP_PORT` (1234) |
| centrifugo | always | Fan-out realtime, fuq `QUIRE_REALTIME_PORT` (8000) |
| proxy | always | Caddy, il-bieb ta' quddiem TLS fuq ports 80 u 443 (ara "TLS") |
| valkey | `cache` | Cache u limiti tar-rata |
| clamav | `scan` | Skennjar ta' malware tal-uploads |
| gotenberg | `preview` | Previews minn Office għal PDF, rendering taċ-ċertifikati |
| imgproxy | `images` | Immaġnijiet imdaqqsa u kkonvertiti |
| transcoder | `video` | L-immaġni tal-worker b'ffmpeg LGPL biss, għal verżjonijiet tal-vidjo |
| seaweedfs | `storage` | Ħażna ta' oġġetti kompatibbli ma' S3 fuq dan il-host |
| otelcol | `observability` | Kollettur OpenTelemetry |
| mailpit | `devmail` | Jaqbad il-posta ħierġa kollha, biex tipprova Quire |
| backup | `backup` | Backup bażi one-shot; ara backup-restore.md |
| backup-scheduler, backup-offsite | `backup` | Backup bażi kull `QUIRE_BACKUP_INTERVAL_HOURS`, u kopji encrypted barra l-host b'drill ta' verifika kull ġimgħa |
| h5p | `h5p` | L-immaġni tal-għodda H5P LTI 1.3 li tipprovdi int f'`QUIRE_H5P_IMAGE`, fuq `QUIRE_H5P_PORT` (8090); ara "Connecting an H5P provider" |

`--profile full` jibda kull servizz fakultattiv ħlief `backup` u `h5p`.
Ibda wieħed b'`docker compose -f docker/compose.yaml --profile scan up -d`.
Mingħajr servizz fakultattiv Quire xorta taħdem u tgħid x'huwa nieqes: l-ebda
skenner ifisser uploads jinħażnu mhux skennjati u l-amministratur jingħad; l-ebda
Gotenberg ifisser fajls joffru download minflok preview; l-ebda transcoder ifisser
vidjo jindaqq bħala l-fajl oriġinali.

Kull immaġni ta' parti terza u l-obbligi tal-liċenzja tagħha huma elenkati f'
`docker/third-party-containers.yaml`.

### Konnessjoni ta' fornitur H5P <!--quire:connecting-an-h5p-provider-->

Quire ma tinkorpora jew tibgħat l-ebda runtime H5P jew sidecar (ADR 0019). Jekk tuża
H5P, ipprovdi l-abbonament hosted tiegħek jew opera l-istanza H5P self-hosted tiegħek
separatament minn Quire. Irreġistra dak il-fornitur bħala għodda esterna LTI 1.3
u żid il-kontenut tiegħu mal-korsijiet bħala attivitajiet ta' għodda. Quire tiskambja gradi
u progress tal-attività/gradar permezz ta' LTI Assignment and Grade Services (AGS).
Jekk il-fornitur jibgħat ukoll dikjarazzjonijiet xAPI, ikkonfigura dan separatament għall-
maħżen tad-dikjarazzjonijiet xAPI ta' Quire; skambju ta' gradi/progress AGS ma jibgħatx dikjarazzjonijiet xAPI.
Imports ta' Moodle jirrapportaw attivitajiet H5P bħala li jeħtieġu konnessjoni ta' għodda LTI.
Il-fornitur jibqa' responsabbli għar-runtime H5P tiegħu, l-awtur,
il-bank tal-kontenut u l-istorja tat-tentattivi.

Biex tħaddem l-istanza self-hosted tiegħek fuq dan il-host, issettja `QUIRE_H5P_IMAGE` għall-
immaġni tiegħu u ibda l-profil `h5p`. Compose jippubblikaha fuq `QUIRE_H5P_PORT`
(8090) u jżomm id-data tagħha fil-volum `h5p-data`; l-immaġni, u l-
obbligi li jiġu magħha, jibqgħu tiegħek.

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

Kull proċess jaqra `docker/.env`. It-template, `docker/.env.example`, jelenka
kull setting bid-default tiegħu. Il-gruppi:

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

| Setting | Meaning |
| --- | --- |
| `QUIRE_APP_ORIGIN` | L-indirizz pubbliku tal-LMS, bħal `https://learn.example.com` |
| `QUIRE_CONTENT_ORIGIN` | L-oriġini tal-kontenut, host differenti |
| `QUIRE_PLATFORM_DOMAINS` | Dominji li organizzazzjonijiet jgħixu taħthom, separati b'virgoli |
| `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` hawnhekk. Ara l-gwidi l-oħra għal `vercel` u `cloudflare` |
| `QUIRE_TRUSTED_PROXY_CIDRS` | Proxies li `X-Forwarded-For` tagħhom huwa maħsub |

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

| Setting | Meaning |
| --- | --- |
| `QUIRE_SECRET_KEY` | Jiffirma sessjonijiet u tokens. 64 karattri hex |
| `QUIRE_MASTER_KEY` | Jgeżwer kredenzjali maħżuna bħal sigrieti SSO u webhook. 32 bytes, base64. Il-livell web u l-worker jeħtieġu l-istess valur. Rotazzjoni: [key-rotation.md](/mt/ops/key-rotation/) |
| `QUIRE_MASTER_KEY_VERSION` | It-tikketta tal-verżjoni taċ-ċavetta master, `v1` meta mhijiex issettjata. Għolliha meta ddawwar |
| `QUIRE_MASTER_KEY_RETIRED` | Ċwievet master ta' qabel li għadhom meħtieġa biex jaqraw dak li ssiġillaw, bħala `v1=<base64>`. Neħħi wara li rotazzjoni tintemm b'xejn mhux solvut |
| `QUIRE_COLLAB_SIGNING_KEY` | Kondiviż bejn web u collab biex jiffirma tokens tal-editjar |
| `QUIRE_BACKUP_SIGNING_KEY` | Jiffirma backups tal-korsijiet (fakultattiv) |

Żomm kopja ta' `QUIRE_MASTER_KEY` xi mkien ieħor barra dan il-host. Database
rrestawrata mingħajrha ma tistax tiddekripta l-kredenzjali li żżomm.

### Database <!--quire:database-->

| Setting | Meaning |
| --- | --- |
| `POSTGRES_PASSWORD` | Is-superuser, użat mill-container u l-backups |
| `QUIRE_DB_APP_PASSWORD`, `QUIRE_DB_MIGRATOR_PASSWORD`, `QUIRE_DB_REPORT_PASSWORD`, `QUIRE_DB_AUDIT_PASSWORD` | Passwords tar-rwoli, issettjati fl-ewwel bidu |
| `DATABASE_URL` | Ir-rwol tal-applikazzjoni. Sigurtà fil-livell tar-ringieli tapplika għal kull query li tagħmel |
| `DATABASE_MIGRATOR_URL`, `QUIRE_MIGRATION_URL` | Ir-rwol tal-migratur, għal `migrate` u `init` |
| `QUIRE_SUPERUSER_URL` | Użat biss mill-ewwel tħaddim |
| `QUIRE_REPORT_DATABASE_URL` | Ir-rwol tar-rapport ta' qari biss, għar-rapporti u l-bennej tar-rapporti |
| `QUIRE_AUDIT_DATABASE_URL` | Ir-rwol tal-verifika, għall-console tal-verifika u l-esportazzjoni SIEM |
| `QUIRE_DATABASE_ID` | Kwalunkwe UUID, fiss għall-ħajja tal-installazzjoni |

Passwords tar-rwoli jiġu applikati biss meta l-volum tad-database jinħoloq l-ewwel darba.
Biex tbiddel waħda aktar tard, uża `ALTER ROLE` u mbagħad aġġorna l-URL li taqbel.

`QUIRE_REPORT_DATABASE_URL` jintuża għad-database fiżika kkonfigurata minn
`DATABASE_URL`. Għal kull database fiżika reġistrata oħra, issettja l-URL tal-konnessjoni
`quire_report` tagħha stess fl-ambjenti tal-web u tal-worker, imbagħad poġġi
l-isem tal-varjabbli f'dik id-database **Reporting environment variable** bħala
`env:NAME`. Ir-referenza trid tindika lill-istess database bħall-konnessjoni tal-app
tagħha, idealment ir-replika tal-qari tagħha. Kull wiċċ tar-rapport isegwi l-
tenant sad-database tiegħu stess konnessjoni tar-rapport: il-bennej tar-rapporti u
rapporti ssejvjati, kunsinni skedati, esportazzjonijiet tar-rapporti, analitika, il-log tal-verifika,
ir-riżorsi tal-verifika REST u t-tiftix tal-verifika tal-assistent. L-ebda waħda
minnhom qatt ma tissellef URL tar-rapport ta' database oħra. Meta database m'għandha l-ebda
konnessjoni tar-rapport, rapporti ordinarji jaħdmu fuq il-konnessjoni tal-applikazzjoni tad-database stess,
filwaqt li analitika u kull qari tal-verifika jirrifjutaw u jgħidu hekk, għax
ir-rwol tal-applikazzjoni ma jistax jaqra t-trail tal-verifika.

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

| Setting | This release | Notes |
| --- | --- | --- |
| `QUIRE_STORAGE_DRIVER` | `local` (default), `s3` jew `azure` | `local` iżomm fajls fil-volum `files`. `s3` ikopri AWS S3, R2, interoperabbiltà GCS u maħżen oħra kompatibbli ma' S3, b'uploads multipart li jistgħu jitkomplew |
| `QUIRE_REALTIME_DRIVER` | `inprocess` (default), `sse`, `centrifugo` jew `durable_objects` | `inprocess` huwa tajjeb għal container web wieħed; uża `centrifugo` jew `sse` meta jkun hemm diversi |
| `QUIRE_CACHE_DRIVER` | `memory` (default), `postgres` jew `valkey` | `memory` huwa għal kull proċess; uża `valkey` jew `postgres` biex il-limiti tar-rata jżommu bejn containers |
| `QUIRE_VIDEO_DRIVER` | `ffmpeg` (default) jew `progressive_mp4` | Jew fornitur hosted: Cloudflare Stream, Mux jew Bunny, biċ-ċwievet tagħhom |
| `QUIRE_IMAGE_DRIVER` | `noop` (default), `imgproxy` jew `cloudflare` | `noop` iservi kull immaġni fid-daqs oriġinali tagħha. `imgproxy` jeħtieġ il-profil `images` u s-settings hawn taħt; `cloudflare` juża Cloudflare Images |
| `QUIRE_MEETING_PROVIDER` | `bbb`, `zoom`, `teams`, `meet`, `jitsi` jew `in_process` | Id-default tal-pjattaforma għas-sessjonijiet live. Mhux issettjat, sessjonijiet live jgħidu li mhumiex ikkonfigurati, sakemm organizzazzjoni tikkonnettja l-kont tagħha taħt Integrations, Live session provider. Il-kont ta' organizzazzjoni dejjem jirbaħ fuq dan il-valur. Is-settings ta' kull fornitur (`BBB_URL` u `BBB_SECRET`, il-varjabbli `ZOOM_*`, `TEAMS_*`, `GOOGLE_MEET_*` u `JITSI_*`) jinqraw biss għall-fornitur imsemmi hawnhekk |
| `QUIRE_MEETING_REGIONS` | Lista b'virgoli ta' `eu`, `uk`, `us` | Fejn il-fornitur default tal-pjattaforma jipproċessa laqgħat. Mhux issettjat, ma jiġix iċċekkjat kontra organizzazzjoni mwaħħla ma' reġjun, bħal qabel. Il-kont ta' organizzazzjoni jiddikjara r-reġjuni tiegħu fil-paġna tiegħu |

Valur ta' driver li din ir-release ma tinkludix jiġi rifjutat meta l-livell web
jibda, bis-setting imsemmija, aktar milli jiġi sostitwit bil-kwiet bid-
default.

### Immaġnijiet <!--quire:images-->

Paġni jitolbu immaġnijiet f'erba' daqsijiet fissi permezz ta'
`/api/files/{id}/image/{size}`, li jiċċekkja l-istess aċċess bħall-fajl
innifsu u mbagħad jerġa' jindirizza lejn is-servizz tal-immaġnijiet. Kull organizzazzjoni tista' titlob
għal `QUIRE_IMAGE_SPECS_PER_HOUR` (default 2000) pari ġodda ta' immaġni u daqs
fis-siegħa; daqsijiet diġà prodotti dik is-siegħa ma jgħoddux. Uża `valkey` jew
`postgres` għal `QUIRE_CACHE_DRIVER` b'aktar minn container web wieħed, biex il-
limitu jżomm bejniethom.

| Setting | Driver | Notes |
| --- | --- | --- |
| `IMGPROXY_URL` | `imgproxy` | L-indirizz li browsers jilħqu imgproxy fuqu, pereżempju `https://images.example.org`. Il-profil `images` jippubblikah fuq `QUIRE_IMAGES_PORT` (8082) |
| `IMGPROXY_KEY`, `IMGPROXY_SALT` | `imgproxy` | Strings hex, l-istess valuri li imgproxy jinbeda bihom. Iġġenera kull waħda b'`openssl rand -hex 32`. Quire jiffirma kull indirizz tal-immaġni bihom, biex imgproxy ma jirrendix xejn li Quire ma talbitx |
| `QUIRE_IMAGE_SOURCE_ORIGIN` | `imgproxy` with local storage | Fejn imgproxy jġib l-oriġinali minn. Compose jissettja `http://web:3000`. B'ħażna `s3` jew `azure` imgproxy jġib mill-bucket u dan ma jintużax |
| `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_IMAGES_TOKEN`, `CLOUDFLARE_IMAGES_ACCOUNT_HASH` | `cloudflare` | Token API b'permess ta' editjar Images, u l-hash tal-kont minn Images, Developer resources. Ixgħel varjanti flessibbli għall-kont |
| `CLOUDFLARE_IMAGES_SIGNING_KEY` | `cloudflare` | Fakultattiv. Meta ssettjat, immaġnijiet huma privati u kull indirizz huwa ffirmat u jiskadi. Mingħajrha, immaġnijiet huma pubbliċi f'indirizzi derivati minn `QUIRE_SECRET_KEY` li ħadd ma jista' jaħseb |

Cloudflare Images iżomm il-kopja tiegħu ta' kull oriġinal li jservi. Meta
fajl jitħassar, il-worker iħassar dik il-kopja qabel l-oriġinali.

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

Xogħol fl-isfond juża pg-boss fl-istess database Postgres, biex m'hemm l-ebda
servizz queue x'tħaddem u xejn x'tikkonfigura. Xogħol jiġi kkwodjat fl-istess
tranżazzjoni bħall-bidla li kkawżatu, biex ħabta ma tistax titlef wieħed jew
tibgħat wieħed darbtejn. `QUIRE_QUEUE_DRIVER` huwa `pgboss` hawnhekk, id-default tiegħu; `vercel`
u `cloudflare` iċaqalqu biss il-kunsinni ħfief ta' notifiki u webhook lill-queue
tal-pjattaforma stess, u l-gwidi Vercel u Cloudflare jiddeskrivuhom
u kif il-livelli web tagħhom jikkwodjaw.

### Email <!--quire:email-->

Issettja waħda minn:

- `QUIRE_EMAIL_PROVIDER_CONFIG`: oġġett JSON li jsemmi fornitur HTTP u
  l-kredenzjali tiegħu, bħal `{"provider":"postmark","token":"..."}`. Postmark,
  Amazon SES, Mailgun, SendGrid u Resend huma appoġġjati.
- `QUIRE_SMTP_URL`: `smtp://user:password@host:587`. Din il-mira biss; il-
  miri serverless jimblokkaw SMTP.

`QUIRE_MAIL_FROM` huwa l-mittent. Biex tipprova Quire, ibda l-profil `devmail`,
issettja `QUIRE_SMTP_URL=smtp://mailpit:1025`, u aqra l-posta f'
`http://localhost:8025`.

### Servizzi fakultattivi <!--quire:optional-services-->

| Setting | With 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` jew `QUIRE_MEILISEARCH_URL` | Tiftix estern; test sħiħ ta' Postgres inkella |
| `QUIRE_BREACH_CHECK_PROVIDER=off`, `QUIRE_BREACH_CHECK_URL` | Kontroll ta' ksur ta' password. Mixgħul default kontra `api.pwnedpasswords.com` (prefiss hash ta' ħames karattri biss jintbagħat); `off` jitfih, u l-URL tindika lejn API range li tospita int |

### Osservabbiltà <!--quire:observability-->

`OTEL_EXPORTER_OTLP_ENDPOINT` isemmi l-kollettur li kull proċess jibgħat
traċċi u metriki lilu; bil-profil `observability` huwa
`http://otelcol:4318`, u `docker/otel-collector.yaml` huwa fejn iżżid l-
esportatur għall-backend tiegħek. Il-livell web, worker, scheduler, content u collab
jesportaw spans fuq OTLP/HTTP (talbiet web, tranżazzjonijiet tad-database tat-tenant,
xogħol tal-worker u sejħiet ħerġin) meta jkun issettjat, u metriki lill-
istess endpoint kull minuta (`OTEL_METRICS_EXPORTER=none` jitfihom).
`OTEL_TRACES_SAMPLER_ARG` jissettja s-sehem ta' traċċi miżmuma. Logs imorru fuq standard
output f'`LOG_LEVEL`, u Compose ddawwarhom. Traċċi qatt ma jġorru data
personali.

### Egress reġjonali (residenza tad-data tal-UE) <!--quire:regional-egress-eu-data-residency-->

`QUIRE_REGION=eu` jgħid li l-istack isservi organizzazzjonijiet tal-Unjoni Ewropea. Il-
worker imbagħad iżomm kull talba ħierġa magħmula għal organizzazzjoni mwaħħla mal-
UE għal allowlist (21-compliance.md sezzjoni 8.1). L-allowlist hija l-
hosts li s-servizzi kkonfigurati jiddikjaraw għar-reġjun (l-endpoint tal-ħażna,
il-fornitur tal-email, fornitur tal-vidjo hosted, il-miri tal-ħażna tal-organizzazzjoni stess,
fornituri tal-AI u kont tal-email), il-hosts ta' kull servizz
taħt deroga attiva, u l-hosts li telenka int f'
`QUIRE_EGRESS_ALLOW_HOSTS`. Talba lil kull host pubbliku ieħor hija rifjutata
qabel ma tintbagħat, ir-rifjut jinkiteb fit-trail tal-verifika tal-organizzazzjoni bħala
`privacy/egress_refused`, u hija elenkata taħt Compliance, Data residency.

| Setting | Values | Effect |
| --- | --- | --- |
| `QUIRE_EGRESS_ALLOW_HOSTS` | Lista b'virgoli ta' hostnames, jew `*.example.org` għal kull subdomain | Hosts żejda li organizzazzjoni tal-UE tista' tilħaq. Endpoints webhook, xAPI u SIEM, feeds tal-blog u hosts ta' Amazon SES jappartjenu hawnhekk, għax huma għażla tal-organizzazzjoni stess u l-ebda servizz ma jiddikjarahom. Loopback, indirizzi privati u ismijiet b'tikketta waħda bħal `web` jew `clamav` huma n-network tiegħek stess u qatt ma jiġu ċċekkjati |

Organizzazzjonijiet tar-Renju Unit u tal-Istati Uniti mhumiex miżmuma ma' lista ta' hosts; iżommu l-kontrolli tar-reġjun tas-servizz. Issettja l-lista fuq il-worker; il-paġna tal-admin taqraha fuq il-livell web
biex turi l-allowlist, għalhekk poġġiha f'`docker/.env`, li kull servizz
jaqra.

Il-kontroll tal-applikazzjoni jagħti żball ċar u entrata tal-verifika, u mhuwiex
il-garanzija: il-kodiċi jista' jkun ħażin. Il-garanzija hija n-network. Compose ma
jinfurzahiex għalik. Għal stack reġjonali, poġġi s-servizzi `worker` u `web`
fuq network `internal: true` li l-unika rotta ħierġa tagħha hija proxy tal-egress
(pereżempju container Squid jew tinyproxy) li jippermetti l-istess hosts
bħala `QUIRE_EGRESS_ALLOW_HOSTS` flimkien mal-hosts tas-servizzi kkonfigurati tiegħek, u
issettja `HTTPS_PROXY` għal dawk is-servizzi. Il-paġna tar-residenza telenka l-hosts eżatti
li l-applikazzjoni tippermetti, biex iż-żewġ listi jkunu jistgħu jitqabblu.

## Saħħa <!--quire:health-->

| Endpoint | Meaning |
| --- | --- |
| `/healthz` | Liveness: il-proċess iwieġeb. Kontrolli tas-saħħa ta' Compose jużaw dan |
| `/readyz` | Readiness: dipendenzi milħuqa, u kull servizz fakultattiv irrapportat bħala kkonfigurat jew le. Indika l-load balancer tiegħek hawnhekk |

`docker compose -f docker/compose.yaml ps` juri s-saħħa ta' kull servizz.

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

Is-servizz `proxy` (Caddy, Apache-2.0, `docker/caddy/Caddyfile`) huwa parti mill-
istack default. Iwieġeb fuq ports 80 u 443 u jgħaddi:

| Host or path | Goes to |
| --- | --- |
| `QUIRE_PROXY_CONTENT_HOST` | `content` |
| `QUIRE_PROXY_APP_HOST`, kull subdomain tat-tenant u dominju personalizzat | `web` |
| `/_collab/` fuq dawk il-hosts | `collab` (websocket, `QUIRE_COLLAB_URL`) |
| `/_realtime/connection/` fuq dawk il-hosts | Il-websocket tal-klijent ta' `centrifugo`; l-API tas-server tiegħu qatt ma hija esposta |
| `/_images/` fuq dawk il-hosts | `imgproxy`, bil-profil `images` (`IMGPROXY_URL`) |

`init-env.sh` jidderiva `QUIRE_PROXY_APP_HOST`, `QUIRE_PROXY_CONTENT_HOST`,
`QUIRE_PROXY_HTTPS_PORT`, `QUIRE_COLLAB_URL` u `IMGPROXY_URL` miż-żewġ
oriġini, biex ma jistgħux jinfirdu. Editjahom flimkien jekk tibdel
oriġini bl-idejn.

Ċertifikati jsegwu `QUIRE_PROXY_TLS`:

- `internal` (id-default): l-awtorità taċ-ċertifikati ta' Caddy stess, għal
  `localhost`, `*.localhost` u `lvh.me`. Afda l-għerq tagħha darba, imbagħad ibbrażja:

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

  Żid `quire-local-ca.crt` mal-maħżen tal-fiduċja tas-sistema jew tal-browser. `curl`
  jeħodha b'`--cacert`.
- Indirizz email: ċertifikati ACME awtomatiċi (Let's Encrypt, imbagħad
  ZeroSSL) għal hostnames reali. DNS għaż-żewġ oriġini u kull host tat-tenant
  irid jindika hawnhekk, u ports 80 u 443 iridu jkunu milħuqa mill-internet.

Hosts tat-tenant jinħarġu meta jintalbu, fl-ewwel żjara, u biss meta web
jikkonferma li l-isem huwa ta' din l-installazzjoni (`/tls-allowed`, mistoqsi fuq in-
network ta' Compose). L-ebda ċertifikat wildcard jew plugin ta' fornitur DNS mhu meħtieġ,
u barrani li jindika isem lejn il-host ma jistax iġiegħlu jitlob
ċertifikati. Ċertifikati u l-awtorità lokali jgħixu fil-volum
`caddy-data`; agħmel backup tiegħu mal-bqija jekk tuża `internal`.

Web jemmen `X-Forwarded-For` mill-proxy waħdu: il-proxy għandu indirizz fiss
(`QUIRE_PROXY_ADDRESS`, default `172.29.64.10`) fuq subnet fissa
(`QUIRE_COMPOSE_SUBNET`), u `QUIRE_TRUSTED_PROXY_CIDRS` isemmi dak l-indirizz.
Jekk is-subnet tikkonfliġġi ma' network fuq il-host, biddel it-tnejn u ħaddem
`docker compose down` qabel `up`.

## Wara l-proxy reverse tiegħek <!--quire:behind-your-own-reverse-proxy-->

Biex tuża load balancer jew proxy li diġà tħaddem minflok, ħalli `proxy` barra
(`docker compose up -d --scale proxy=0`) u temm TLS quddiem `web`
(8080), `content` (8081), `collab` (1234, websocket) u `centrifugo` (8000,
websocket). Issettja l-indirizzi pubbliċi f'`QUIRE_APP_ORIGIN`,
`QUIRE_CONTENT_ORIGIN` u `QUIRE_COLLAB_URL` (`wss://`), u l-firxa tal-indirizzi tal-proxy tiegħek
f'`QUIRE_TRUSTED_PROXY_CIDRS`.

## Solvi problemi <!--quire:troubleshooting-->

- `init` joħroġ bi "QUIRE_DATABASE_ID is not a UUID": issettjah b'`uuidgen`.
- `web` jerġa' jibda b'"did not start on compose"': il-log jelenka kull setting
  li ma jistax jonora u x'tuża minflok.
- Tibdil ta' password ta' rwol f'`.env` wara l-ewwel bidu ma jagħmel xejn: l-
  iskript init jaħdem darba. Uża `ALTER ROLE`.
- Uploads ifallu bi żball ta' skennjar waqt li `CLAMAV_URL` huwa ssettjat: ClamAV jniżżel
  is-signatures tiegħu fl-ewwel bidu, li jieħu ftit minuti.

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