From d38bf33a690bec1baf53d6ad7aafee5eb2f8900f Mon Sep 17 00:00:00 2001
From: Devvyn <22340871+opticon454@users.noreply.github.com>
Date: Fri, 4 Sep 2026 20:07:10 +0800
Subject: [PATCH] docs(docker): document the reverse-proxy host allowlist

CODEMAN_ALLOWED_HOSTS is a real, documented application setting (the Host-
header allowlist in network-auth-policy.ts), but docker-compose.yaml does not
forward it from .env into the container - Compose only passes through
variables explicitly listed under environment:, and this is not one of them.
Set without that passthrough, any request through a reverse proxy is rejected
with 403 Forbidden: host not allowed before it reaches any handler, and
nothing in the Docker deployment docs said why.

Document the variable and the override needed to forward it, using the
Local customisation mechanism already described above it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docker/README.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/docker/README.md b/docker/README.md
index 27af041b..7d3a1e84 100644
--- a/docker/README.md
+++ b/docker/README.md
@@ -54,6 +54,34 @@ services:
       - /srv/projects:/srv/projects
 ```
 
+### Reverse-proxy host allowlist
+
+Codeman rejects any request whose `Host` header is not on its own allowlist - a
+DNS-rebinding guard, not a Compose or Docker concern. Loopback, any IP literal,
+the configured `--host`, and a few tunnel-provider suffixes are allowed by
+default; a reverse-proxied domain is not, and is rejected with
+`403 Forbidden: host not allowed` before the request reaches any handler.
+
+Add the domain with `CODEMAN_ALLOWED_HOSTS` in `.env`:
+
+```sh
+CODEMAN_ALLOWED_HOSTS='codeman.example.com,.internal.example.com'
+```
+
+`docker-compose.yaml` does not forward this variable into the container - it
+only passes through the environment keys it explicitly lists, and this is not
+one of them. Forward it yourself in `docker-compose.override.yml`:
+
+```yaml
+services:
+  codeman:
+    environment:
+      CODEMAN_ALLOWED_HOSTS: ${CODEMAN_ALLOWED_HOSTS}
+```
+
+See the application's own `docs/wiki/Remote-Access.md` for the full allowlist
+format and the tunnel providers it accepts by default.
+
 ## Application data storage
 
 The default configuration uses a host-folder bind mount: