From b8d692bac5ba7961913375f64495933655cae73f Mon Sep 17 00:00:00 2001
From: tajniak81 <13187254+tajniak81@users.noreply.github.com>
Date: Thu, 22 Oct 2026 20:12:35 +0200
Subject: [PATCH] Docker: read every setting from a .env file

Each folder gets a .env.example listing every homeserver, admin panel
and web client setting with its default (empty means the default).
Compose reads .env for ports, registry and the PostgreSQL password, and
passes it to the containers through env_file; the compose files keep
only the database driver, connection string and internal addresses.
.env is git-ignored.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .gitignore                                    |   1 +
 Docker-AIO/.env.example                       | 178 ++++++++++++++++++
 Docker-AIO/README.md                          |  14 +-
 Docker-AIO/docker-compose.pocketbase.prod.yml |  19 +-
 Docker-AIO/docker-compose.pocketbase.yml      |  19 +-
 Docker-AIO/docker-compose.postgresql.prod.yml |   8 +-
 Docker-AIO/docker-compose.postgresql.yml      |   8 +-
 Docker-AIO/docker-compose.sqlite.prod.yml     |   8 +-
 Docker-AIO/docker-compose.sqlite.yml          |   8 +-
 Docker/.env.example                           | 177 +++++++++++++++++
 Docker/README.md                              |  23 ++-
 Docker/docker-compose.pocketbase.prod.yml     |  21 +--
 Docker/docker-compose.pocketbase.yml          |  21 +--
 Docker/docker-compose.postgresql.prod.yml     |  11 +-
 Docker/docker-compose.postgresql.yml          |  11 +-
 Docker/docker-compose.sqlite.prod.yml         |  10 +-
 Docker/docker-compose.sqlite.yml              |  10 +-
 17 files changed, 433 insertions(+), 114 deletions(-)
 create mode 100644 Docker-AIO/.env.example
 create mode 100644 Docker/.env.example

diff --git a/.gitignore b/.gitignore
index 778b047..c0b7973 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,6 +13,7 @@
 *.db-shm
 *.db-wal
 /pb_data/
+.env
 
 # Complement checkout, cloned by server/test/complement/run.sh
 /.complement/
diff --git a/Docker-AIO/.env.example b/Docker-AIO/.env.example
new file mode 100644
index 0000000..e81bbda
--- /dev/null
+++ b/Docker-AIO/.env.example
@@ -0,0 +1,178 @@
+# Settings for every compose file in this folder.
+#
+#   cp .env.example .env
+#
+# then edit .env. Compose reads it for the ports and the registry, and
+# hands all of it to the container, so anything below takes effect on the
+# next `docker compose ... up -d`.
+#
+# An empty value means the built-in default, given in the comment above it.
+# Every homeserver setting is described in docs/configuration.md.
+#
+# Set by the compose files, not here: the database driver and connection
+# string (each file is one database), the listen addresses, the signing key
+# and media paths inside /data, the address the admin panel and web client
+# reach the homeserver on, and whether the bundled PostgreSQL runs.
+
+# ---------------------------------------------------------------- compose
+
+# Host ports for the homeserver, the admin panel and the web client.
+WARP_PORT=8008
+WARP_ADMIN_PORT=8009
+WARP_WEB_PORT=8080
+
+# The *.prod.yml files pull $WARP_REGISTRY/warp-aio at this tag. Pin a
+# release in production.
+WARP_REGISTRY=ghcr.io/dariuszjaniak
+WARP_VERSION=latest
+
+# ------------------------------------------------------------------- aio
+
+# false runs the container without the admin panel or the web client.
+WARP_AIO_ADMIN=true
+WARP_AIO_WEB=true
+
+# ------------------------------------------------------------ homeserver
+
+# Part of every user and room ID: it cannot be changed later.
+WARP_SERVER_NAME=localhost
+
+# The URL clients are told to use, in /.well-known/matrix/client.
+# Default https://<server name>.
+WARP_WELL_KNOWN_CLIENT_BASE_URL=http://localhost:8008
+# Default empty.
+WARP_WELL_KNOWN_IDENTITY_SERVER_BASE_URL=
+# host:port other homeservers should use. Default empty: no delegation.
+WARP_WELL_KNOWN_SERVER_ADDRESS=
+
+# Registration. Default false; the admin API can switch it at runtime.
+WARP_REGISTRATION_ENABLED=false
+# Default true.
+WARP_REGISTRATION_ALLOW_RUNTIME_TOGGLE=
+# Comma-separated sign-up tokens. Default none.
+WARP_REGISTRATION_TOKENS=
+# Default false.
+WARP_REGISTRATION_REQUIRE_TOKEN=
+
+# Federation. Default false.
+WARP_FEDERATION_ENABLED=false
+# Default true.
+WARP_FEDERATION_ALLOW_RUNTIME_TOGGLE=
+# Comma-separated server names. Default none.
+WARP_FEDERATION_ALLOWLIST=
+WARP_FEDERATION_DENYLIST=
+WARP_FEDERATION_TRUSTED_KEY_SERVERS=
+# Default 24h.
+WARP_FEDERATION_KEY_VALIDITY_PERIOD=
+# A second, TLS listener for federation, e.g. :8448, with its certificate
+# and key (paths inside the container). Publish the port yourself.
+WARP_LISTEN_FEDERATION_ADDRESS=
+WARP_TLS_CERT_FILE=
+WARP_TLS_KEY_FILE=
+WARP_FEDERATION_TLS_CA_FILE=
+
+# HTTP server. Defaults 10s, 60s, 120s, 120s, 1048576, 30s.
+WARP_READ_HEADER_TIMEOUT=
+WARP_READ_TIMEOUT=
+WARP_WRITE_TIMEOUT=
+WARP_IDLE_TIMEOUT=
+WARP_MAX_HEADER_BYTES=
+WARP_SHUTDOWN_TIMEOUT=
+
+# Database pool (PostgreSQL). Defaults 10, 5, 1h, true.
+WARP_DB_MAX_OPEN_CONNS=
+WARP_DB_MAX_IDLE_CONNS=
+WARP_DB_CONN_MAX_LIFETIME=
+WARP_DB_AUTO_MIGRATE=
+
+# docker-compose.pocketbase*.yml only: keep media in an S3 bucket instead
+# of pb_data/storage. Bucket, region, endpoint and keys are all required
+# when it is on.
+WARP_PB_S3_ENABLED=false
+WARP_PB_S3_BUCKET=
+WARP_PB_S3_REGION=
+WARP_PB_S3_ENDPOINT=
+WARP_PB_S3_ACCESS_KEY=
+WARP_PB_S3_SECRET=
+WARP_PB_S3_FORCE_PATH_STYLE=false
+
+# Client API. Defaults *, false, 0s (never expire), 0s, true.
+WARP_CORS_ALLOWED_ORIGINS=
+WARP_TRUST_X_FORWARDED_FOR=
+WARP_ACCESS_TOKEN_LIFETIME=
+WARP_REFRESH_TOKEN_LIFETIME=
+WARP_RATE_LIMIT_ENABLED=
+
+# Calls: the LiveKit JWT service's URL (see docs/calls.md). Default empty.
+WARP_RTC_LIVEKIT_SERVICE_URL=
+# Delayed events. Defaults 24h, 100.
+WARP_DELAYED_EVENTS_MAX_DELAY=
+WARP_DELAYED_EVENTS_MAX_PER_USER=
+# TURN for legacy 1:1 calls: comma-separated URIs, then a shared secret or
+# a static username and password. Lifetime default 1h.
+WARP_TURN_URIS=
+WARP_TURN_SHARED_SECRET=
+WARP_TURN_USER_LIFETIME=
+WARP_TURN_USERNAME=
+WARP_TURN_PASSWORD=
+
+# Sync. Defaults false, 30s, 30s.
+WARP_SYNC_PRESENCE=
+WARP_SYNC_TYPING_TIMEOUT=
+WARP_SYNC_LONG_POLL_TIMEOUT=
+
+# Media. Defaults 52428800 (50 MiB), 0 (no limit), 32000000, 24h, 10, false.
+WARP_MEDIA_MAX_UPLOAD_BYTES=
+WARP_MEDIA_MAX_USER_STORAGE_BYTES=
+WARP_MEDIA_MAX_THUMBNAIL_PIXELS=
+WARP_MEDIA_PENDING_UPLOAD_EXPIRY=
+WARP_MEDIA_MAX_PENDING_UPLOADS=
+WARP_MEDIA_LEGACY_UNAUTHENTICATED_DOWNLOADS=
+
+# Push. Defaults true, true, 10s, 720h.
+WARP_PUSH_ENABLED=
+WARP_PUSH_INCLUDE_CONTENT=
+WARP_PUSH_GATEWAY_TIMEOUT=
+WARP_PUSH_NOTIFICATION_RETENTION=
+
+# Application services: comma-separated registration files (paths inside
+# the container). Timeout default 30s.
+WARP_APPSERVICE_CONFIG_FILES=
+WARP_APPSERVICE_TIMEOUT=
+
+# Server notices. Defaults false, server-notices, Server Notices, Server
+# Notices.
+WARP_SERVER_NOTICES_ENABLED=
+WARP_SERVER_NOTICES_LOCALPART=
+WARP_SERVER_NOTICES_DISPLAY_NAME=
+WARP_SERVER_NOTICES_ROOM_NAME=
+
+# Logging: debug, info, warn or error; text or json; file and line.
+WARP_LOG_LEVEL=info
+WARP_LOG_FORMAT=json
+WARP_LOG_ADD_SOURCE=
+
+# Metrics. Defaults true, /metrics.
+WARP_METRICS_ENABLED=
+WARP_METRICS_PATH=
+
+# OpenTelemetry tracing. Defaults false, localhost:4318, 1, warp.
+WARP_TRACING_ENABLED=false
+WARP_TRACING_ENDPOINT=
+WARP_TRACING_SAMPLE_RATIO=
+WARP_TRACING_SERVICE_NAME=
+
+# ----------------------------------------------------------- admin panel
+
+# text or json.
+WARP_ADMIN_LOG_FORMAT=json
+
+# ------------------------------------------------------------ web client
+
+# The homeserver's public URL. Set, the browser talks to it directly and
+# the web client proxies nothing; empty, it proxies the client API.
+WARP_WEB_PUBLIC_HOMESERVER=
+# Space-separated origins of the LiveKit JWT service and SFU, for calls.
+WARP_WEB_CALL_ORIGINS=
+# text or json.
+WARP_WEB_LOG_FORMAT=json
diff --git a/Docker-AIO/README.md b/Docker-AIO/README.md
index e270c6f..3480552 100644
--- a/Docker-AIO/README.md
+++ b/Docker-AIO/README.md
@@ -17,7 +17,8 @@ Everything lives in the `warp-data` volume, mounted on `/data`.
 
 ```sh
 cd Docker-AIO
-WARP_SERVER_NAME=matrix.example.org docker compose -f docker-compose.sqlite.yml up -d --build
+cp .env.example .env      # then edit it
+docker compose -f docker-compose.sqlite.yml up -d --build
 docker compose -f docker-compose.sqlite.yml exec warp warp create-account --username admin --admin
 ```
 
@@ -26,15 +27,20 @@ Homeserver on `:8008`, admin panel on `:8009`, web client on `:8080`.
 The embedded PostgreSQL listens only on a Unix socket inside the
 container, so it needs no password and is not reachable from outside.
 
-## Switches
+## Settings
+
+Every setting is in `.env`, copied from [`.env.example`](.env.example),
+which lists them all with their defaults; an empty value means the
+default. `.env` is not committed. On top of the settings of
+[Docker/](../Docker/README.md), it has:
 
 | Variable | Default | |
 | --- | --- | --- |
 | `WARP_AIO_ADMIN` | `true` | `false` runs no admin panel |
 | `WARP_AIO_WEB` | `true` | `false` runs no web client |
-| `WARP_AIO_EMBEDDED_POSTGRES` | `false` | `true` starts the bundled PostgreSQL |
 
-The other settings are those of [Docker/](../Docker/README.md).
+`WARP_AIO_EMBEDDED_POSTGRES`, which starts the bundled PostgreSQL, is set
+by `docker-compose.postgresql*.yml`.
 
 ## Prod files
 
diff --git a/Docker-AIO/docker-compose.pocketbase.prod.yml b/Docker-AIO/docker-compose.pocketbase.prod.yml
index dada5a9..5b4d4ac 100644
--- a/Docker-AIO/docker-compose.pocketbase.prod.yml
+++ b/Docker-AIO/docker-compose.pocketbase.prod.yml
@@ -2,12 +2,13 @@
 # web client in one container, pulled from a registry.
 #
 #   cd Docker-AIO
-#   WARP_SERVER_NAME=matrix.example.org docker compose -f docker-compose.pocketbase.prod.yml up -d
+#   cp .env.example .env      # then edit it
+#   docker compose -f docker-compose.pocketbase.prod.yml up -d
 #
 # PocketBase is embedded in the homeserver (the pocketbase database driver):
 # its data directory, with media in its storage, is /data/pb_data in the
-# warp-data volume. Set the WARP_PB_S3_* variables to keep media in an S3
-# bucket instead (docs/configuration.md).
+# warp-data volume. Set WARP_PB_S3_* in .env to keep media in an
+# S3 bucket instead (docs/configuration.md).
 #
 # Homeserver http://localhost:8008, admin panel http://localhost:8009, web
 # client http://localhost:8080.
@@ -29,20 +30,10 @@ services:
     image: ${WARP_REGISTRY:-ghcr.io/dariuszjaniak}/warp-aio:${WARP_VERSION:-latest}
     pull_policy: always
     restart: unless-stopped
+    env_file: .env
     environment:
-      WARP_SERVER_NAME: ${WARP_SERVER_NAME:-localhost}
-      WARP_WELL_KNOWN_CLIENT_BASE_URL: ${WARP_PUBLIC_BASEURL:-http://localhost:8008}
       WARP_DB_DRIVER: pocketbase
       WARP_DB_CONNECTION_STRING: /data/pb_data
-      WARP_PB_S3_ENABLED: ${WARP_PB_S3_ENABLED:-false}
-      WARP_PB_S3_BUCKET: ${WARP_PB_S3_BUCKET:-}
-      WARP_PB_S3_REGION: ${WARP_PB_S3_REGION:-}
-      WARP_PB_S3_ENDPOINT: ${WARP_PB_S3_ENDPOINT:-}
-      WARP_PB_S3_ACCESS_KEY: ${WARP_PB_S3_ACCESS_KEY:-}
-      WARP_PB_S3_SECRET: ${WARP_PB_S3_SECRET:-}
-      WARP_PB_S3_FORCE_PATH_STYLE: ${WARP_PB_S3_FORCE_PATH_STYLE:-false}
-      WARP_REGISTRATION_ENABLED: ${WARP_REGISTRATION_ENABLED:-false}
-      WARP_FEDERATION_ENABLED: ${WARP_FEDERATION_ENABLED:-false}
     volumes:
       - warp-data:/data
     ports:
diff --git a/Docker-AIO/docker-compose.pocketbase.yml b/Docker-AIO/docker-compose.pocketbase.yml
index b40e10a..88148e5 100644
--- a/Docker-AIO/docker-compose.pocketbase.yml
+++ b/Docker-AIO/docker-compose.pocketbase.yml
@@ -2,12 +2,13 @@
 # web client in one container, built from this checkout.
 #
 #   cd Docker-AIO
-#   WARP_SERVER_NAME=matrix.example.org docker compose -f docker-compose.pocketbase.yml up -d --build
+#   cp .env.example .env      # then edit it
+#   docker compose -f docker-compose.pocketbase.yml up -d --build
 #
 # PocketBase is embedded in the homeserver (the pocketbase database driver):
 # its data directory, with media in its storage, is /data/pb_data in the
-# warp-data volume. Set the WARP_PB_S3_* variables to keep media in an S3
-# bucket instead (docs/configuration.md).
+# warp-data volume. Set WARP_PB_S3_* in .env to keep media in an
+# S3 bucket instead (docs/configuration.md).
 #
 # Homeserver http://localhost:8008, admin panel http://localhost:8009, web
 # client http://localhost:8080.
@@ -25,20 +26,10 @@ services:
       dockerfile: Docker-AIO/Dockerfile
     image: warp-aio:latest
     restart: unless-stopped
+    env_file: .env
     environment:
-      WARP_SERVER_NAME: ${WARP_SERVER_NAME:-localhost}
-      WARP_WELL_KNOWN_CLIENT_BASE_URL: ${WARP_PUBLIC_BASEURL:-http://localhost:8008}
       WARP_DB_DRIVER: pocketbase
       WARP_DB_CONNECTION_STRING: /data/pb_data
-      WARP_PB_S3_ENABLED: ${WARP_PB_S3_ENABLED:-false}
-      WARP_PB_S3_BUCKET: ${WARP_PB_S3_BUCKET:-}
-      WARP_PB_S3_REGION: ${WARP_PB_S3_REGION:-}
-      WARP_PB_S3_ENDPOINT: ${WARP_PB_S3_ENDPOINT:-}
-      WARP_PB_S3_ACCESS_KEY: ${WARP_PB_S3_ACCESS_KEY:-}
-      WARP_PB_S3_SECRET: ${WARP_PB_S3_SECRET:-}
-      WARP_PB_S3_FORCE_PATH_STYLE: ${WARP_PB_S3_FORCE_PATH_STYLE:-false}
-      WARP_REGISTRATION_ENABLED: ${WARP_REGISTRATION_ENABLED:-false}
-      WARP_FEDERATION_ENABLED: ${WARP_FEDERATION_ENABLED:-false}
     volumes:
       - warp-data:/data
     ports:
diff --git a/Docker-AIO/docker-compose.postgresql.prod.yml b/Docker-AIO/docker-compose.postgresql.prod.yml
index ce8f6c0..fbfaea0 100644
--- a/Docker-AIO/docker-compose.postgresql.prod.yml
+++ b/Docker-AIO/docker-compose.postgresql.prod.yml
@@ -2,7 +2,8 @@
 # client and PostgreSQL in one container, pulled from a registry.
 #
 #   cd Docker-AIO
-#   WARP_SERVER_NAME=matrix.example.org docker compose -f docker-compose.postgresql.prod.yml up -d
+#   cp .env.example .env      # then edit it
+#   docker compose -f docker-compose.postgresql.prod.yml up -d
 #
 # PostgreSQL runs inside the container, listening only on a Unix socket
 # there, with its data in /data/postgres in the warp-data volume.
@@ -29,14 +30,11 @@ services:
     restart: unless-stopped
     # PostgreSQL's fast shutdown runs after the homeserver's; give both time.
     stop_grace_period: 30s
+    env_file: .env
     environment:
-      WARP_SERVER_NAME: ${WARP_SERVER_NAME:-localhost}
-      WARP_WELL_KNOWN_CLIENT_BASE_URL: ${WARP_PUBLIC_BASEURL:-http://localhost:8008}
       WARP_AIO_EMBEDDED_POSTGRES: "true"
       WARP_DB_DRIVER: postgres
       WARP_DB_CONNECTION_STRING: postgres:///warp?host=/run/postgresql&user=warp&sslmode=disable
-      WARP_REGISTRATION_ENABLED: ${WARP_REGISTRATION_ENABLED:-false}
-      WARP_FEDERATION_ENABLED: ${WARP_FEDERATION_ENABLED:-false}
     volumes:
       - warp-data:/data
     ports:
diff --git a/Docker-AIO/docker-compose.postgresql.yml b/Docker-AIO/docker-compose.postgresql.yml
index 8933c9d..9402ffd 100644
--- a/Docker-AIO/docker-compose.postgresql.yml
+++ b/Docker-AIO/docker-compose.postgresql.yml
@@ -2,7 +2,8 @@
 # client and PostgreSQL in one container, built from this checkout.
 #
 #   cd Docker-AIO
-#   WARP_SERVER_NAME=matrix.example.org docker compose -f docker-compose.postgresql.yml up -d --build
+#   cp .env.example .env      # then edit it
+#   docker compose -f docker-compose.postgresql.yml up -d --build
 #
 # PostgreSQL runs inside the container, listening only on a Unix socket
 # there, with its data in /data/postgres in the warp-data volume.
@@ -25,14 +26,11 @@ services:
     restart: unless-stopped
     # PostgreSQL's fast shutdown runs after the homeserver's; give both time.
     stop_grace_period: 30s
+    env_file: .env
     environment:
-      WARP_SERVER_NAME: ${WARP_SERVER_NAME:-localhost}
-      WARP_WELL_KNOWN_CLIENT_BASE_URL: ${WARP_PUBLIC_BASEURL:-http://localhost:8008}
       WARP_AIO_EMBEDDED_POSTGRES: "true"
       WARP_DB_DRIVER: postgres
       WARP_DB_CONNECTION_STRING: postgres:///warp?host=/run/postgresql&user=warp&sslmode=disable
-      WARP_REGISTRATION_ENABLED: ${WARP_REGISTRATION_ENABLED:-false}
-      WARP_FEDERATION_ENABLED: ${WARP_FEDERATION_ENABLED:-false}
     volumes:
       - warp-data:/data
     ports:
diff --git a/Docker-AIO/docker-compose.sqlite.prod.yml b/Docker-AIO/docker-compose.sqlite.prod.yml
index 289a4a5..f05a879 100644
--- a/Docker-AIO/docker-compose.sqlite.prod.yml
+++ b/Docker-AIO/docker-compose.sqlite.prod.yml
@@ -2,7 +2,8 @@
 # client in one container, pulled from a registry.
 #
 #   cd Docker-AIO
-#   WARP_SERVER_NAME=matrix.example.org docker compose -f docker-compose.sqlite.prod.yml up -d
+#   cp .env.example .env      # then edit it
+#   docker compose -f docker-compose.sqlite.prod.yml up -d
 #
 # Homeserver http://localhost:8008, admin panel http://localhost:8009, web
 # client http://localhost:8080. The database, signing key and media live
@@ -25,12 +26,9 @@ services:
     image: ${WARP_REGISTRY:-ghcr.io/dariuszjaniak}/warp-aio:${WARP_VERSION:-latest}
     pull_policy: always
     restart: unless-stopped
+    env_file: .env
     environment:
-      WARP_SERVER_NAME: ${WARP_SERVER_NAME:-localhost}
-      WARP_WELL_KNOWN_CLIENT_BASE_URL: ${WARP_PUBLIC_BASEURL:-http://localhost:8008}
       WARP_DB_DRIVER: sqlite
-      WARP_REGISTRATION_ENABLED: ${WARP_REGISTRATION_ENABLED:-false}
-      WARP_FEDERATION_ENABLED: ${WARP_FEDERATION_ENABLED:-false}
     volumes:
       - warp-data:/data
     ports:
diff --git a/Docker-AIO/docker-compose.sqlite.yml b/Docker-AIO/docker-compose.sqlite.yml
index 28a7e01..5346174 100644
--- a/Docker-AIO/docker-compose.sqlite.yml
+++ b/Docker-AIO/docker-compose.sqlite.yml
@@ -2,7 +2,8 @@
 # client in one container, built from this checkout.
 #
 #   cd Docker-AIO
-#   WARP_SERVER_NAME=matrix.example.org docker compose -f docker-compose.sqlite.yml up -d --build
+#   cp .env.example .env      # then edit it
+#   docker compose -f docker-compose.sqlite.yml up -d --build
 #
 # Homeserver http://localhost:8008, admin panel http://localhost:8009, web
 # client http://localhost:8080. The database, signing key and media live
@@ -21,12 +22,9 @@ services:
       dockerfile: Docker-AIO/Dockerfile
     image: warp-aio:latest
     restart: unless-stopped
+    env_file: .env
     environment:
-      WARP_SERVER_NAME: ${WARP_SERVER_NAME:-localhost}
-      WARP_WELL_KNOWN_CLIENT_BASE_URL: ${WARP_PUBLIC_BASEURL:-http://localhost:8008}
       WARP_DB_DRIVER: sqlite
-      WARP_REGISTRATION_ENABLED: ${WARP_REGISTRATION_ENABLED:-false}
-      WARP_FEDERATION_ENABLED: ${WARP_FEDERATION_ENABLED:-false}
     volumes:
       - warp-data:/data
     ports:
diff --git a/Docker/.env.example b/Docker/.env.example
new file mode 100644
index 0000000..de6170b
--- /dev/null
+++ b/Docker/.env.example
@@ -0,0 +1,177 @@
+# Settings for every compose file in this folder.
+#
+#   cp .env.example .env
+#
+# then edit .env. Compose reads it for the ports, the registry and the
+# PostgreSQL password, and hands all of it to the containers, so anything
+# below takes effect on the next `docker compose ... up -d`.
+#
+# An empty value means the built-in default, given in the comment above it.
+# Every homeserver setting is described in docs/configuration.md.
+#
+# Set by the compose files, not here: the database driver and connection
+# string (each file is one database), the listen addresses, the signing key
+# and media paths inside /data, and the address the admin panel and web
+# client reach the homeserver on.
+
+# ---------------------------------------------------------------- compose
+
+# Host ports for the homeserver, the admin panel and the web client.
+WARP_PORT=8008
+WARP_ADMIN_PORT=8009
+WARP_WEB_PORT=8080
+
+# The *.prod.yml files pull $WARP_REGISTRY/warp, warp-admin and warp-web at
+# this tag. Pin a release in production.
+WARP_REGISTRY=ghcr.io/dariuszjaniak
+WARP_VERSION=latest
+
+# docker-compose.postgresql*.yml only. Used when PostgreSQL is first set up;
+# changing it later does not change the database's password. The prod file
+# refuses to start without it.
+WARP_POSTGRES_PASSWORD=change-me
+
+# ------------------------------------------------------------ homeserver
+
+# Part of every user and room ID: it cannot be changed later.
+WARP_SERVER_NAME=localhost
+
+# The URL clients are told to use, in /.well-known/matrix/client.
+# Default https://<server name>.
+WARP_WELL_KNOWN_CLIENT_BASE_URL=http://localhost:8008
+# Default empty.
+WARP_WELL_KNOWN_IDENTITY_SERVER_BASE_URL=
+# host:port other homeservers should use. Default empty: no delegation.
+WARP_WELL_KNOWN_SERVER_ADDRESS=
+
+# Registration. Default false; the admin API can switch it at runtime.
+WARP_REGISTRATION_ENABLED=false
+# Default true.
+WARP_REGISTRATION_ALLOW_RUNTIME_TOGGLE=
+# Comma-separated sign-up tokens. Default none.
+WARP_REGISTRATION_TOKENS=
+# Default false.
+WARP_REGISTRATION_REQUIRE_TOKEN=
+
+# Federation. Default false.
+WARP_FEDERATION_ENABLED=false
+# Default true.
+WARP_FEDERATION_ALLOW_RUNTIME_TOGGLE=
+# Comma-separated server names. Default none.
+WARP_FEDERATION_ALLOWLIST=
+WARP_FEDERATION_DENYLIST=
+WARP_FEDERATION_TRUSTED_KEY_SERVERS=
+# Default 24h.
+WARP_FEDERATION_KEY_VALIDITY_PERIOD=
+# A second, TLS listener for federation, e.g. :8448, with its certificate
+# and key (paths inside the container). Publish the port yourself.
+WARP_LISTEN_FEDERATION_ADDRESS=
+WARP_TLS_CERT_FILE=
+WARP_TLS_KEY_FILE=
+WARP_FEDERATION_TLS_CA_FILE=
+
+# HTTP server. Defaults 10s, 60s, 120s, 120s, 1048576, 30s.
+WARP_READ_HEADER_TIMEOUT=
+WARP_READ_TIMEOUT=
+WARP_WRITE_TIMEOUT=
+WARP_IDLE_TIMEOUT=
+WARP_MAX_HEADER_BYTES=
+WARP_SHUTDOWN_TIMEOUT=
+
+# Database pool (PostgreSQL). Defaults 10, 5, 1h, true.
+WARP_DB_MAX_OPEN_CONNS=
+WARP_DB_MAX_IDLE_CONNS=
+WARP_DB_CONN_MAX_LIFETIME=
+WARP_DB_AUTO_MIGRATE=
+
+# docker-compose.pocketbase*.yml only: keep media in an S3 bucket instead
+# of pb_data/storage. Bucket, region, endpoint and keys are all required
+# when it is on.
+WARP_PB_S3_ENABLED=false
+WARP_PB_S3_BUCKET=
+WARP_PB_S3_REGION=
+WARP_PB_S3_ENDPOINT=
+WARP_PB_S3_ACCESS_KEY=
+WARP_PB_S3_SECRET=
+WARP_PB_S3_FORCE_PATH_STYLE=false
+
+# Client API. Defaults *, false, 0s (never expire), 0s, true.
+WARP_CORS_ALLOWED_ORIGINS=
+WARP_TRUST_X_FORWARDED_FOR=
+WARP_ACCESS_TOKEN_LIFETIME=
+WARP_REFRESH_TOKEN_LIFETIME=
+WARP_RATE_LIMIT_ENABLED=
+
+# Calls: the LiveKit JWT service's URL (see docs/calls.md). Default empty.
+WARP_RTC_LIVEKIT_SERVICE_URL=
+# Delayed events. Defaults 24h, 100.
+WARP_DELAYED_EVENTS_MAX_DELAY=
+WARP_DELAYED_EVENTS_MAX_PER_USER=
+# TURN for legacy 1:1 calls: comma-separated URIs, then a shared secret or
+# a static username and password. Lifetime default 1h.
+WARP_TURN_URIS=
+WARP_TURN_SHARED_SECRET=
+WARP_TURN_USER_LIFETIME=
+WARP_TURN_USERNAME=
+WARP_TURN_PASSWORD=
+
+# Sync. Defaults false, 30s, 30s.
+WARP_SYNC_PRESENCE=
+WARP_SYNC_TYPING_TIMEOUT=
+WARP_SYNC_LONG_POLL_TIMEOUT=
+
+# Media. Defaults 52428800 (50 MiB), 0 (no limit), 32000000, 24h, 10, false.
+WARP_MEDIA_MAX_UPLOAD_BYTES=
+WARP_MEDIA_MAX_USER_STORAGE_BYTES=
+WARP_MEDIA_MAX_THUMBNAIL_PIXELS=
+WARP_MEDIA_PENDING_UPLOAD_EXPIRY=
+WARP_MEDIA_MAX_PENDING_UPLOADS=
+WARP_MEDIA_LEGACY_UNAUTHENTICATED_DOWNLOADS=
+
+# Push. Defaults true, true, 10s, 720h.
+WARP_PUSH_ENABLED=
+WARP_PUSH_INCLUDE_CONTENT=
+WARP_PUSH_GATEWAY_TIMEOUT=
+WARP_PUSH_NOTIFICATION_RETENTION=
+
+# Application services: comma-separated registration files (paths inside
+# the container). Timeout default 30s.
+WARP_APPSERVICE_CONFIG_FILES=
+WARP_APPSERVICE_TIMEOUT=
+
+# Server notices. Defaults false, server-notices, Server Notices, Server
+# Notices.
+WARP_SERVER_NOTICES_ENABLED=
+WARP_SERVER_NOTICES_LOCALPART=
+WARP_SERVER_NOTICES_DISPLAY_NAME=
+WARP_SERVER_NOTICES_ROOM_NAME=
+
+# Logging: debug, info, warn or error; text or json; file and line.
+WARP_LOG_LEVEL=info
+WARP_LOG_FORMAT=json
+WARP_LOG_ADD_SOURCE=
+
+# Metrics. Defaults true, /metrics.
+WARP_METRICS_ENABLED=
+WARP_METRICS_PATH=
+
+# OpenTelemetry tracing. Defaults false, localhost:4318, 1, warp.
+WARP_TRACING_ENABLED=false
+WARP_TRACING_ENDPOINT=
+WARP_TRACING_SAMPLE_RATIO=
+WARP_TRACING_SERVICE_NAME=
+
+# ----------------------------------------------------------- admin panel
+
+# text or json.
+WARP_ADMIN_LOG_FORMAT=json
+
+# ------------------------------------------------------------ web client
+
+# The homeserver's public URL. Set, the browser talks to it directly and
+# the web client proxies nothing; empty, it proxies the client API.
+WARP_WEB_PUBLIC_HOMESERVER=
+# Space-separated origins of the LiveKit JWT service and SFU, for calls.
+WARP_WEB_CALL_ORIGINS=
+# text or json.
+WARP_WEB_LOG_FORMAT=json
diff --git a/Docker/README.md b/Docker/README.md
index 547b44b..fa8d8af 100644
--- a/Docker/README.md
+++ b/Docker/README.md
@@ -13,12 +13,13 @@ The homeserver (`warp`), the admin panel (`warp-admin`) and the web client
 
 ```sh
 cd Docker
-WARP_SERVER_NAME=matrix.example.org docker compose -f docker-compose.sqlite.yml up -d --build
+cp .env.example .env      # then edit it
+docker compose -f docker-compose.sqlite.yml up -d --build
 docker compose -f docker-compose.sqlite.yml exec warp warp create-account --username admin --admin
 ```
 
 Homeserver on `:8008`, admin panel on `:8009`, web client on `:8080`
-(`WARP_PORT`, `WARP_ADMIN_PORT`, `WARP_WEB_PORT` move them). Put a
+(`WARP_PORT`, `WARP_ADMIN_PORT`, `WARP_WEB_PORT` in `.env` move them). Put a
 TLS-terminating reverse proxy in front before exposing them; see
 [docs/deployment.md](../docs/deployment.md).
 
@@ -44,14 +45,12 @@ done
 
 ## Settings
 
-| Variable | Default |
-| --- | --- |
-| `WARP_SERVER_NAME` | `localhost` |
-| `WARP_PUBLIC_BASEURL` | `http://localhost:8008` |
-| `WARP_REGISTRATION_ENABLED` | `false` |
-| `WARP_FEDERATION_ENABLED` | `false` |
-| `WARP_POSTGRES_PASSWORD` | `warp` (required in prod) |
-| `WARP_PB_S3_*` | S3 media for PocketBase, off |
+Every setting is in `.env`, copied from [`.env.example`](.env.example),
+which lists them all with their defaults; an empty value means the
+default. Compose reads it for the ports, the registry and the PostgreSQL
+password, and passes all of it to the homeserver, the admin panel and the
+web client. `.env` is not committed.
 
-Any other setting from [docs/configuration.md](../docs/configuration.md)
-can be added to the `warp` service's environment.
+The compose files set only what makes each one what it is: the database
+driver and connection string, and the address the admin panel and web
+client reach the homeserver on.
diff --git a/Docker/docker-compose.pocketbase.prod.yml b/Docker/docker-compose.pocketbase.prod.yml
index d233104..efd2643 100644
--- a/Docker/docker-compose.pocketbase.prod.yml
+++ b/Docker/docker-compose.pocketbase.prod.yml
@@ -2,12 +2,13 @@
 # each in its own container, pulled from a registry.
 #
 #   cd Docker
-#   WARP_SERVER_NAME=matrix.example.org docker compose -f docker-compose.pocketbase.prod.yml up -d
+#   cp .env.example .env      # then edit it
+#   docker compose -f docker-compose.pocketbase.prod.yml up -d
 #
 # PocketBase is embedded in the homeserver (the pocketbase database driver),
 # so it is not a container of its own: its data directory, with media in
-# its storage, is /data/pb_data in the warp-data volume. Set the WARP_PB_S3_*
-# variables to keep media in an S3 bucket instead (docs/configuration.md).
+# its storage, is /data/pb_data in the warp-data volume. Set WARP_PB_S3_*
+# in .env to keep media in an S3 bucket instead (docs/configuration.md).
 #
 # Homeserver http://localhost:8008, admin panel http://localhost:8009, web
 # client http://localhost:8080.
@@ -34,20 +35,10 @@ services:
     entrypoint: ["/bin/sh", "-c"]
     command:
       - test -f /data/signing.key || warp generate-keys --output /data/signing.key; exec warp serve
+    env_file: .env
     environment:
-      WARP_SERVER_NAME: ${WARP_SERVER_NAME:-localhost}
-      WARP_WELL_KNOWN_CLIENT_BASE_URL: ${WARP_PUBLIC_BASEURL:-http://localhost:8008}
       WARP_DB_DRIVER: pocketbase
       WARP_DB_CONNECTION_STRING: /data/pb_data
-      WARP_PB_S3_ENABLED: ${WARP_PB_S3_ENABLED:-false}
-      WARP_PB_S3_BUCKET: ${WARP_PB_S3_BUCKET:-}
-      WARP_PB_S3_REGION: ${WARP_PB_S3_REGION:-}
-      WARP_PB_S3_ENDPOINT: ${WARP_PB_S3_ENDPOINT:-}
-      WARP_PB_S3_ACCESS_KEY: ${WARP_PB_S3_ACCESS_KEY:-}
-      WARP_PB_S3_SECRET: ${WARP_PB_S3_SECRET:-}
-      WARP_PB_S3_FORCE_PATH_STYLE: ${WARP_PB_S3_FORCE_PATH_STYLE:-false}
-      WARP_REGISTRATION_ENABLED: ${WARP_REGISTRATION_ENABLED:-false}
-      WARP_FEDERATION_ENABLED: ${WARP_FEDERATION_ENABLED:-false}
     volumes:
       - warp-data:/data
     ports:
@@ -59,6 +50,7 @@ services:
     restart: unless-stopped
     depends_on:
       - warp
+    env_file: .env
     environment:
       WARP_ADMIN_HOMESERVER: http://warp:8008
     ports:
@@ -70,6 +62,7 @@ services:
     restart: unless-stopped
     depends_on:
       - warp
+    env_file: .env
     environment:
       WARP_WEB_HOMESERVER: http://warp:8008
     ports:
diff --git a/Docker/docker-compose.pocketbase.yml b/Docker/docker-compose.pocketbase.yml
index dc7f892..a707772 100644
--- a/Docker/docker-compose.pocketbase.yml
+++ b/Docker/docker-compose.pocketbase.yml
@@ -2,12 +2,13 @@
 # each in its own container, built from this checkout.
 #
 #   cd Docker
-#   WARP_SERVER_NAME=matrix.example.org docker compose -f docker-compose.pocketbase.yml up -d --build
+#   cp .env.example .env      # then edit it
+#   docker compose -f docker-compose.pocketbase.yml up -d --build
 #
 # PocketBase is embedded in the homeserver (the pocketbase database driver),
 # so it is not a container of its own: its data directory, with media in
-# its storage, is /data/pb_data in the warp-data volume. Set the WARP_PB_S3_*
-# variables to keep media in an S3 bucket instead (docs/configuration.md).
+# its storage, is /data/pb_data in the warp-data volume. Set WARP_PB_S3_*
+# in .env to keep media in an S3 bucket instead (docs/configuration.md).
 #
 # Homeserver http://localhost:8008, admin panel http://localhost:8009, web
 # client http://localhost:8080.
@@ -30,20 +31,10 @@ services:
     entrypoint: ["/bin/sh", "-c"]
     command:
       - test -f /data/signing.key || warp generate-keys --output /data/signing.key; exec warp serve
+    env_file: .env
     environment:
-      WARP_SERVER_NAME: ${WARP_SERVER_NAME:-localhost}
-      WARP_WELL_KNOWN_CLIENT_BASE_URL: ${WARP_PUBLIC_BASEURL:-http://localhost:8008}
       WARP_DB_DRIVER: pocketbase
       WARP_DB_CONNECTION_STRING: /data/pb_data
-      WARP_PB_S3_ENABLED: ${WARP_PB_S3_ENABLED:-false}
-      WARP_PB_S3_BUCKET: ${WARP_PB_S3_BUCKET:-}
-      WARP_PB_S3_REGION: ${WARP_PB_S3_REGION:-}
-      WARP_PB_S3_ENDPOINT: ${WARP_PB_S3_ENDPOINT:-}
-      WARP_PB_S3_ACCESS_KEY: ${WARP_PB_S3_ACCESS_KEY:-}
-      WARP_PB_S3_SECRET: ${WARP_PB_S3_SECRET:-}
-      WARP_PB_S3_FORCE_PATH_STYLE: ${WARP_PB_S3_FORCE_PATH_STYLE:-false}
-      WARP_REGISTRATION_ENABLED: ${WARP_REGISTRATION_ENABLED:-false}
-      WARP_FEDERATION_ENABLED: ${WARP_FEDERATION_ENABLED:-false}
     volumes:
       - warp-data:/data
     ports:
@@ -57,6 +48,7 @@ services:
     restart: unless-stopped
     depends_on:
       - warp
+    env_file: .env
     environment:
       WARP_ADMIN_HOMESERVER: http://warp:8008
     ports:
@@ -70,6 +62,7 @@ services:
     restart: unless-stopped
     depends_on:
       - warp
+    env_file: .env
     environment:
       WARP_WEB_HOMESERVER: http://warp:8008
     ports:
diff --git a/Docker/docker-compose.postgresql.prod.yml b/Docker/docker-compose.postgresql.prod.yml
index b1da0f9..4d6ca9f 100644
--- a/Docker/docker-compose.postgresql.prod.yml
+++ b/Docker/docker-compose.postgresql.prod.yml
@@ -2,8 +2,8 @@
 # PostgreSQL, each in its own container, pulled from a registry.
 #
 #   cd Docker
-#   WARP_SERVER_NAME=matrix.example.org WARP_POSTGRES_PASSWORD=change-me \
-#     docker compose -f docker-compose.postgresql.prod.yml up -d
+#   cp .env.example .env      # then edit it; set WARP_POSTGRES_PASSWORD
+#   docker compose -f docker-compose.postgresql.prod.yml up -d
 #
 # Homeserver http://localhost:8008, admin panel http://localhost:8009, web
 # client http://localhost:8080. PostgreSQL is reachable only on the compose
@@ -51,13 +51,10 @@ services:
     entrypoint: ["/bin/sh", "-c"]
     command:
       - test -f /data/signing.key || warp generate-keys --output /data/signing.key; exec warp serve
+    env_file: .env
     environment:
-      WARP_SERVER_NAME: ${WARP_SERVER_NAME:-localhost}
-      WARP_WELL_KNOWN_CLIENT_BASE_URL: ${WARP_PUBLIC_BASEURL:-http://localhost:8008}
       WARP_DB_DRIVER: postgres
       WARP_DB_CONNECTION_STRING: postgres://warp:${WARP_POSTGRES_PASSWORD:?set WARP_POSTGRES_PASSWORD}@postgres:5432/warp?sslmode=disable
-      WARP_REGISTRATION_ENABLED: ${WARP_REGISTRATION_ENABLED:-false}
-      WARP_FEDERATION_ENABLED: ${WARP_FEDERATION_ENABLED:-false}
     volumes:
       - warp-data:/data
     ports:
@@ -69,6 +66,7 @@ services:
     restart: unless-stopped
     depends_on:
       - warp
+    env_file: .env
     environment:
       WARP_ADMIN_HOMESERVER: http://warp:8008
     ports:
@@ -80,6 +78,7 @@ services:
     restart: unless-stopped
     depends_on:
       - warp
+    env_file: .env
     environment:
       WARP_WEB_HOMESERVER: http://warp:8008
     ports:
diff --git a/Docker/docker-compose.postgresql.yml b/Docker/docker-compose.postgresql.yml
index 7f3e467..62d573d 100644
--- a/Docker/docker-compose.postgresql.yml
+++ b/Docker/docker-compose.postgresql.yml
@@ -2,8 +2,8 @@
 # PostgreSQL, each in its own container, built from this checkout.
 #
 #   cd Docker
-#   WARP_SERVER_NAME=matrix.example.org WARP_POSTGRES_PASSWORD=change-me \
-#     docker compose -f docker-compose.postgresql.yml up -d --build
+#   cp .env.example .env      # then edit it; set WARP_POSTGRES_PASSWORD
+#   docker compose -f docker-compose.postgresql.yml up -d --build
 #
 # Homeserver http://localhost:8008, admin panel http://localhost:8009, web
 # client http://localhost:8080. PostgreSQL is reachable only on the compose
@@ -47,13 +47,10 @@ services:
     entrypoint: ["/bin/sh", "-c"]
     command:
       - test -f /data/signing.key || warp generate-keys --output /data/signing.key; exec warp serve
+    env_file: .env
     environment:
-      WARP_SERVER_NAME: ${WARP_SERVER_NAME:-localhost}
-      WARP_WELL_KNOWN_CLIENT_BASE_URL: ${WARP_PUBLIC_BASEURL:-http://localhost:8008}
       WARP_DB_DRIVER: postgres
       WARP_DB_CONNECTION_STRING: postgres://warp:${WARP_POSTGRES_PASSWORD:-warp}@postgres:5432/warp?sslmode=disable
-      WARP_REGISTRATION_ENABLED: ${WARP_REGISTRATION_ENABLED:-false}
-      WARP_FEDERATION_ENABLED: ${WARP_FEDERATION_ENABLED:-false}
     volumes:
       - warp-data:/data
     ports:
@@ -67,6 +64,7 @@ services:
     restart: unless-stopped
     depends_on:
       - warp
+    env_file: .env
     environment:
       WARP_ADMIN_HOMESERVER: http://warp:8008
     ports:
@@ -80,6 +78,7 @@ services:
     restart: unless-stopped
     depends_on:
       - warp
+    env_file: .env
     environment:
       WARP_WEB_HOMESERVER: http://warp:8008
     ports:
diff --git a/Docker/docker-compose.sqlite.prod.yml b/Docker/docker-compose.sqlite.prod.yml
index cc8d503..0044283 100644
--- a/Docker/docker-compose.sqlite.prod.yml
+++ b/Docker/docker-compose.sqlite.prod.yml
@@ -2,7 +2,8 @@
 # in its own container, pulled from a registry.
 #
 #   cd Docker
-#   WARP_SERVER_NAME=matrix.example.org docker compose -f docker-compose.sqlite.prod.yml up -d
+#   cp .env.example .env      # then edit it
+#   docker compose -f docker-compose.sqlite.prod.yml up -d
 #
 # Homeserver http://localhost:8008, admin panel http://localhost:8009, web
 # client http://localhost:8080. The database, signing key and media live
@@ -30,12 +31,9 @@ services:
     entrypoint: ["/bin/sh", "-c"]
     command:
       - test -f /data/signing.key || warp generate-keys --output /data/signing.key; exec warp serve
+    env_file: .env
     environment:
-      WARP_SERVER_NAME: ${WARP_SERVER_NAME:-localhost}
-      WARP_WELL_KNOWN_CLIENT_BASE_URL: ${WARP_PUBLIC_BASEURL:-http://localhost:8008}
       WARP_DB_DRIVER: sqlite
-      WARP_REGISTRATION_ENABLED: ${WARP_REGISTRATION_ENABLED:-false}
-      WARP_FEDERATION_ENABLED: ${WARP_FEDERATION_ENABLED:-false}
     volumes:
       - warp-data:/data
     ports:
@@ -47,6 +45,7 @@ services:
     restart: unless-stopped
     depends_on:
       - warp
+    env_file: .env
     environment:
       WARP_ADMIN_HOMESERVER: http://warp:8008
     ports:
@@ -58,6 +57,7 @@ services:
     restart: unless-stopped
     depends_on:
       - warp
+    env_file: .env
     environment:
       WARP_WEB_HOMESERVER: http://warp:8008
     ports:
diff --git a/Docker/docker-compose.sqlite.yml b/Docker/docker-compose.sqlite.yml
index 487b080..14fd466 100644
--- a/Docker/docker-compose.sqlite.yml
+++ b/Docker/docker-compose.sqlite.yml
@@ -2,7 +2,8 @@
 # in its own container, built from this checkout.
 #
 #   cd Docker
-#   WARP_SERVER_NAME=matrix.example.org docker compose -f docker-compose.sqlite.yml up -d --build
+#   cp .env.example .env      # then edit it
+#   docker compose -f docker-compose.sqlite.yml up -d --build
 #
 # Homeserver http://localhost:8008, admin panel http://localhost:8009, web
 # client http://localhost:8080. The database, signing key and media live
@@ -26,12 +27,9 @@ services:
     entrypoint: ["/bin/sh", "-c"]
     command:
       - test -f /data/signing.key || warp generate-keys --output /data/signing.key; exec warp serve
+    env_file: .env
     environment:
-      WARP_SERVER_NAME: ${WARP_SERVER_NAME:-localhost}
-      WARP_WELL_KNOWN_CLIENT_BASE_URL: ${WARP_PUBLIC_BASEURL:-http://localhost:8008}
       WARP_DB_DRIVER: sqlite
-      WARP_REGISTRATION_ENABLED: ${WARP_REGISTRATION_ENABLED:-false}
-      WARP_FEDERATION_ENABLED: ${WARP_FEDERATION_ENABLED:-false}
     volumes:
       - warp-data:/data
     ports:
@@ -45,6 +43,7 @@ services:
     restart: unless-stopped
     depends_on:
       - warp
+    env_file: .env
     environment:
       WARP_ADMIN_HOMESERVER: http://warp:8008
     ports:
@@ -58,6 +57,7 @@ services:
     restart: unless-stopped
     depends_on:
       - warp
+    env_file: .env
     environment:
       WARP_WEB_HOMESERVER: http://warp:8008
     ports: