From e3085704568889cce2e791b8455650440bc39bef Mon Sep 17 00:00:00 2001 From: John McLear Date: Sun, 7 Jun 2026 19:00:03 +0100 Subject: [PATCH] docs: document docker-compose credential + TRUST_PROXY changes (#7907 follow-up) #7907 made the production docker-compose require ADMIN_PASSWORD and the DB password (no insecure fallback) and defaulted TRUST_PROXY to false, but only changed docker-compose.yml. This brings the docs in line: - .env.default: document DOCKER_COMPOSE_APP_TRUST_PROXY (set true behind a trusted reverse proxy) and note ADMIN_PASSWORD is required (compose won't start while it's empty). - .env.dev.default: document the dev DOCKER_COMPOSE_APP_DEV_ENV_TRUST_PROXY. - README.md / doc/docker.md: update the embedded compose snippets to match the merged file (required ADMIN_PASSWORD/DB password, TRUST_PROXY default false). Co-Authored-By: Claude Opus 4.8 (1M context) --- .env.default | 10 ++++++++++ .env.dev.default | 4 ++++ README.md | 8 ++++---- doc/docker.md | 8 ++++---- 4 files changed, 22 insertions(+), 8 deletions(-) diff --git a/.env.default b/.env.default index e9b560b72cb..d4254427ef7 100644 --- a/.env.default +++ b/.env.default @@ -11,8 +11,18 @@ DOCKER_COMPOSE_APP_PORT_TARGET=9001 # The env var DEFAULT_PAD_TEXT seems to be mandatory in the latest version of etherpad. DOCKER_COMPOSE_APP_DEV_ENV_DEFAULT_PAD_TEXT="Welcome to etherpad" +# REQUIRED. The /admin account password. docker-compose refuses to start while +# this is empty (the value has no insecure fallback). Set a strong value — the +# /admin UI can install plugins, which is arbitrary code execution. DOCKER_COMPOSE_APP_ADMIN_PASSWORD= +# Set to true ONLY when Etherpad runs behind a trusted reverse proxy that sets +# the X-Forwarded-* headers (Traefik, Nginx, Kubernetes Ingress, …). On a +# directly-exposed instance keep it false so clients can't spoof their IP. If you +# DO run behind a proxy you must set this to true, otherwise HTTPS detection +# (secure cookies) and client-IP / rate-limiting will be wrong. +DOCKER_COMPOSE_APP_TRUST_PROXY=false + DOCKER_COMPOSE_POSTGRES_DATABASE=db DOCKER_COMPOSE_POSTGRES_PASSWORD=etherpad-lite-password DOCKER_COMPOSE_POSTGRES_USER=etherpad-lite-user diff --git a/.env.dev.default b/.env.dev.default index b78b5599aa1..8aa1709f804 100644 --- a/.env.dev.default +++ b/.env.dev.default @@ -13,6 +13,10 @@ DOCKER_COMPOSE_APP_DEV_ENV_DEFAULT_PAD_TEXT="Welcome to etherpad" DOCKER_COMPOSE_APP_DEV_ADMIN_PASSWORD= +# docker-compose.dev.yml defaults this to true (dev convenience). Set to false if +# you are not running the dev container behind a reverse proxy. +DOCKER_COMPOSE_APP_DEV_ENV_TRUST_PROXY=true + DOCKER_COMPOSE_POSTGRES_DEV_ENV_POSTGRES_DATABASE=db DOCKER_COMPOSE_POSTGRES_DEV_ENV_POSTGRES_PASSWORD=etherpad-lite-password DOCKER_COMPOSE_POSTGRES_DEV_ENV_POSTGRES_USER=etherpad-lite-user \ No newline at end of file diff --git a/README.md b/README.md index 3be539f4ce8..b52dec31f1e 100644 --- a/README.md +++ b/README.md @@ -117,11 +117,11 @@ services: - postgres environment: NODE_ENV: production - ADMIN_PASSWORD: ${DOCKER_COMPOSE_APP_ADMIN_PASSWORD:-admin} + ADMIN_PASSWORD: "${DOCKER_COMPOSE_APP_ADMIN_PASSWORD:?Set DOCKER_COMPOSE_APP_ADMIN_PASSWORD to a strong value}" DB_CHARSET: ${DOCKER_COMPOSE_APP_DB_CHARSET:-utf8mb4} DB_HOST: postgres DB_NAME: ${DOCKER_COMPOSE_POSTGRES_DATABASE:-etherpad} - DB_PASS: ${DOCKER_COMPOSE_POSTGRES_PASSWORD:-admin} + DB_PASS: "${DOCKER_COMPOSE_POSTGRES_PASSWORD:?Set DOCKER_COMPOSE_POSTGRES_PASSWORD to a strong value}" DB_PORT: ${DOCKER_COMPOSE_POSTGRES_PORT:-5432} DB_TYPE: "postgres" DB_USER: ${DOCKER_COMPOSE_POSTGRES_USER:-admin} @@ -129,7 +129,7 @@ services: DEFAULT_PAD_TEXT: ${DOCKER_COMPOSE_APP_DEFAULT_PAD_TEXT:- } DISABLE_IP_LOGGING: ${DOCKER_COMPOSE_APP_DISABLE_IP_LOGGING:-false} SOFFICE: ${DOCKER_COMPOSE_APP_SOFFICE:-null} - TRUST_PROXY: ${DOCKER_COMPOSE_APP_TRUST_PROXY:-true} + TRUST_PROXY: ${DOCKER_COMPOSE_APP_TRUST_PROXY:-false} restart: always ports: - "${DOCKER_COMPOSE_APP_PORT_PUBLISHED:-9001}:${DOCKER_COMPOSE_APP_PORT_TARGET:-9001}" @@ -138,7 +138,7 @@ services: image: postgres:15-alpine environment: POSTGRES_DB: ${DOCKER_COMPOSE_POSTGRES_DATABASE:-etherpad} - POSTGRES_PASSWORD: ${DOCKER_COMPOSE_POSTGRES_PASSWORD:-admin} + POSTGRES_PASSWORD: "${DOCKER_COMPOSE_POSTGRES_PASSWORD:?Set DOCKER_COMPOSE_POSTGRES_PASSWORD to a strong value}" POSTGRES_PORT: ${DOCKER_COMPOSE_POSTGRES_PORT:-5432} POSTGRES_USER: ${DOCKER_COMPOSE_POSTGRES_USER:-admin} PGDATA: /var/lib/postgresql/data/pgdata diff --git a/doc/docker.md b/doc/docker.md index 5a5a4281691..a0e424ee317 100644 --- a/doc/docker.md +++ b/doc/docker.md @@ -355,11 +355,11 @@ services: - postgres environment: NODE_ENV: production - ADMIN_PASSWORD: ${DOCKER_COMPOSE_APP_ADMIN_PASSWORD:-admin} + ADMIN_PASSWORD: "${DOCKER_COMPOSE_APP_ADMIN_PASSWORD:?Set DOCKER_COMPOSE_APP_ADMIN_PASSWORD to a strong value}" DB_CHARSET: ${DOCKER_COMPOSE_APP_DB_CHARSET:-utf8mb4} DB_HOST: postgres DB_NAME: ${DOCKER_COMPOSE_POSTGRES_DATABASE:-etherpad} - DB_PASS: ${DOCKER_COMPOSE_POSTGRES_PASSWORD:-admin} + DB_PASS: "${DOCKER_COMPOSE_POSTGRES_PASSWORD:?Set DOCKER_COMPOSE_POSTGRES_PASSWORD to a strong value}" DB_PORT: ${DOCKER_COMPOSE_POSTGRES_PORT:-5432} DB_TYPE: "postgres" DB_USER: ${DOCKER_COMPOSE_POSTGRES_USER:-admin} @@ -367,7 +367,7 @@ services: DEFAULT_PAD_TEXT: ${DOCKER_COMPOSE_APP_DEFAULT_PAD_TEXT:- } DISABLE_IP_LOGGING: ${DOCKER_COMPOSE_APP_DISABLE_IP_LOGGING:-false} SOFFICE: ${DOCKER_COMPOSE_APP_SOFFICE:-null} - TRUST_PROXY: ${DOCKER_COMPOSE_APP_TRUST_PROXY:-true} + TRUST_PROXY: ${DOCKER_COMPOSE_APP_TRUST_PROXY:-false} restart: always ports: - "${DOCKER_COMPOSE_APP_PORT_PUBLISHED:-9001}:${DOCKER_COMPOSE_APP_PORT_TARGET:-9001}" @@ -376,7 +376,7 @@ services: image: postgres:15-alpine environment: POSTGRES_DB: ${DOCKER_COMPOSE_POSTGRES_DATABASE:-etherpad} - POSTGRES_PASSWORD: ${DOCKER_COMPOSE_POSTGRES_PASSWORD:-admin} + POSTGRES_PASSWORD: "${DOCKER_COMPOSE_POSTGRES_PASSWORD:?Set DOCKER_COMPOSE_POSTGRES_PASSWORD to a strong value}" POSTGRES_PORT: ${DOCKER_COMPOSE_POSTGRES_PORT:-5432} POSTGRES_USER: ${DOCKER_COMPOSE_POSTGRES_USER:-admin} PGDATA: /var/lib/postgresql/data/pgdata