docker: make the stack multi-instance so a test.escapepage.com copy can run alongside prod

compose.yaml / compose.override.yaml:
- container_name is now ${STACK_NAME:-escapepage}-* (STACK_NAME is a plain var,
  not COMPOSE_PROJECT_NAME, so prod keeps its escapepage-* names with no config change)
- every published host port is ${*_PORT:-<current default>}, so prod is unchanged
  and a second stack can bind its own (localhost-only) ports
- nginx joins the external nginx_default network so Nginx Proxy Manager can
  forward to <stack>-nginx by name

restart.sh:
- scoped to STACK_NAME / COMPOSE_PROJECT_NAME read from docker/.env, so running it
  from the test checkout can't touch the prod stack
- host-wide `docker system prune` / `docker builder prune` moved behind --prune-all

Adds docker/.env.test.example and doc/test-environment.md (separate checkout,
env layers, NPM proxy host + Access List IP allowlist, Mercure on test).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

doc/test-environment.md

@@ -0,0 +1,139 @@
+# Test / staging environment (`test.escapepage.com`)
+
+Runs a second copy of the full Docker stack on the same server as production,
+behind the same Nginx Proxy Manager (NPM). Production is untouched: with no
+`docker/.env` overrides, `compose.yaml` behaves exactly as before.
+
+## How isolation works
+
+`docker/compose.yaml` derives everything instance-specific from `docker/.env`:
+
+| Concern | Mechanism | prod (no overrides) | test |
+|---|---|---|---|
+| Container names | `${STACK_NAME:-escapepage}-*` | `escapepage-php` … | `escapepage-test-php` … |
+| Compose project (networks, labels) | `COMPOSE_PROJECT_NAME` | `docker` (unchanged) | `escapepage-test` |
+| Published ports | `${NGINX_HTTP_PORT:-8080}` etc. | `0.0.0.0:8080/8443/3306/8090/8025` | `127.0.0.1:8081/8444/3307/8091/8026` |
+| Database files | bind mount `../var/volumes/db` | per checkout | per checkout |
+| Web reachability | `nginx` joined to external `nginx_default` | via NPM | via NPM |
+
+`STACK_NAME` is a plain variable (not the Compose-managed `COMPOSE_PROJECT_NAME`),
+so its `:-escapepage` default is reliable and **production needs no `docker/.env`
+change** to keep its `escapepage-*` container names.
+
+`nginx`, `mercure` and `mailer` all sit on the external `nginx_default` network,
+so NPM forwards straight to `escapepage-test-nginx` / `-mercure` by name — no
+public host port needed.
+
+## Production checkout — optional
+
+Nothing is required. Two optional tidy-ups, each needing a `docker compose up -d`
+to recreate the affected container:
+
+- The `nginx` service now also attaches to `nginx_default`. If you'd rather have
+  NPM forward to `escapepage-nginx` by name instead of `host:8080`, recreate it
+  and repoint the NPM proxy host. Otherwise the published `8080/8443` still work
+  as before and you can ignore this.
+- Add `STACK_NAME=escapepage` and `COMPOSE_PROJECT_NAME=escapepage` to the
+  production `docker/.env` to move it off the implicit `docker` project name.
+  Cosmetic; do it only if you want the two stacks named symmetrically.
+
+## Standing up the test stack
+
+### 1. DNS
+`test.escapepage.com` → server IP. (`mercure-test.escapepage.com` too if you want
+live game features.) On Cloudflare, DNS-only ("grey cloud") keeps it low-profile.
+
+### 2. Separate checkout
+```bash
+git clone <repo> /opt/escapepage-test
+cd /opt/escapepage-test
+git checkout <branch-to-test>
+```
+Use a **separate clone**, not `git worktree` — the Docker build context is the
+checkout directory and full isolation avoids surprises.
+
+### 3. Compose env
+```bash
+cp docker/.env.test.example docker/.env
+# edit: real passwords, fresh MERCURE_JWT_SECRET (openssl rand -hex 32), reCAPTCHA keys
+```
+
+### 4. Symfony env overrides
+Create `/opt/escapepage-test/.env.local` in the checkout (git-ignored):
+```
+APP_SECRET=<openssl rand -hex 16>
+# Behind NPM the forwarded client IP lands from a Docker-private range; trust them
+# all on staging so URL generation / HTTPS detection work.
+TRUSTED_PROXIES=127.0.0.1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
+```
+`APP_ENV=prod`, `DATABASE_URL`, `SITE_BASE_URL`, `MERCURE_*` and `MAILER_DSN` are
+already supplied to the containers by `docker/.env`.
+
+### 5. Build & start
+```bash
+./docker/setup.sh
+```
+Builds `escapepage-test-*` images, starts the containers, creates + migrates
+`escapepage_test`, builds assets. Re-run any time; `--no-build` skips the image
+rebuild.
+
+### 6. Nginx Proxy Manager — proxy host
+- Domain: `test.escapepage.com`
+- Forward to: `escapepage-test-nginx`, port **443**, scheme **https**
+  (the app nginx force-redirects 80→443 and serves a self-signed cert; leave
+  "Verify SSL" off — same arrangement as production)
+- SSL: request a Let's Encrypt cert, Force SSL, HTTP/2
+- Optional: add response header `X-Robots-Tag: noindex`
+
+If you want live game screens, add a second proxy host
+`mercure-test.escapepage.com` → `escapepage-test-mercure` port `80` (http).
+
+### 7. Restrict access to your IP — NPM Access List
+A host firewall on 80/443 can't help: prod and test share those ports on NPM.
+Restrict at the proxy instead.
+
+- **NPM → Access Lists → Add Access List**
+  - Name: e.g. `staging-allowlist`
+  - Authorisation: leave empty
+  - Access: `Allow  <your.public.ip>`  then a final `Deny  all`
+  - Satisfy: **Any**
+- Edit the `test.escapepage.com` proxy host → **Access List** → select it.
+- Do the same on `mercure-test.escapepage.com` if you added it.
+
+Everyone else gets `403` at the proxy. Update the IP in one place when it changes.
+
+Defence in depth (optional): in `/opt/escapepage-test/docker/nginx/default.conf`,
+inside the `server { listen 443 ... }` block:
+```nginx
+set_real_ip_from 172.16.0.0/12;   # NPM's docker network
+real_ip_header   X-Forwarded-For;
+allow <your.public.ip>;
+deny  all;
+```
+
+## Deploying a new version to test
+
+```bash
+cd /opt/escapepage-test
+git fetch && git checkout <branch> && git pull
+docker compose -f docker/compose.yaml -f docker/compose.override.yaml \
+  exec php composer install
+docker compose ... exec php php bin/console doctrine:migrations:migrate -n
+docker compose ... exec php php bin/console cache:clear
+docker compose ... exec php npm ci && ... npm run build
+docker restart escapepage-test-php-worker
+```
+(Or just `./docker/setup.sh --no-build`.)
+
+## Safety notes
+
+- **`docker/restart.sh` is now scoped to `STACK_NAME` / `COMPOSE_PROJECT_NAME`**
+  from `docker/.env` — running it in the test checkout only touches
+  `escapepage-test-*`. The host-wide
+  `docker system prune` / `docker builder prune` it used to always run are now
+  opt-in via `./docker/restart.sh --prune-all`; don't use that flag while the
+  other stack shares the host.
+- The test `docker/.env` uses its own `DB_NAME` and passwords so a config slip
+  can't reach the production database.
+- `MAILER_DSN=smtp://mailer:1026` keeps staging mail inside Mailpit instead of
+  sending through Mailgun.

docker/.env.test.example

@@ -0,0 +1,75 @@
+# =============================================================================
+#  docker/.env for a TEST / STAGING stack  (e.g. test.escapepage.com)
+# =============================================================================
+#  Copy this to  docker/.env  inside the *test* checkout and fill in the blanks.
+#  docker/.env is git-ignored, so it never leaves the server.
+#
+#  Compose reads this file automatically. Anything unique per stack is derived
+#  from COMPOSE_PROJECT_NAME + the *_PORT vars below, so the same compose.yaml
+#  serves both production and this copy.
+#
+#  Two config layers, don't mix them up:
+#   - THIS file  -> consumed by `docker compose` (container names, ports, and the
+#                   runtime env it injects into the php containers).
+#   - <checkout>/.env(.local) -> consumed by Symfony itself (APP_SECRET,
+#                   TRUSTED_PROXIES, messenger DSN, CLI database access, ...).
+# =============================================================================
+
+## --- Instance identity -------------------------------------------------------
+# Both must be unique on the host.
+#   STACK_NAME           -> prefix for every container_name (escapepage-test-php …)
+#   COMPOSE_PROJECT_NAME -> compose project: isolates networks, volumes and the
+#                           labels that `docker compose down` / restart.sh act on
+STACK_NAME=escapepage-test
+COMPOSE_PROJECT_NAME=escapepage-test
+
+## --- Published host ports ---------------------------------------------------
+# Bound to localhost only: the sole public entrypoint is Nginx Proxy Manager,
+# which reaches the containers over the shared `nginx_default` network by name.
+# Pick ports that don't clash with the production stack (8080/8443/3306/8090/8025/1025).
+NGINX_HTTP_PORT=127.0.0.1:8081
+NGINX_HTTPS_PORT=127.0.0.1:8444
+DB_HOST_PORT=127.0.0.1:3307
+MERCURE_HTTP_PORT=127.0.0.1:8091
+MAILPIT_UI_PORT=127.0.0.1:8026
+MAILPIT_SMTP_PORT=127.0.0.1:1026
+
+## --- PHP image build ------------------------------------------------------
+USER_ID=1000
+GROUP_ID=1000
+
+## --- Symfony runtime (injected into php / php-worker / php-cron) ------------
+APP_ENV=prod
+SITE_BASE_URL=https://test.escapepage.com
+
+# Staging should NOT send real mail. Point at the bundled Mailpit and read it
+# at http://127.0.0.1:8026 on the server (or via an NPM host if you expose it).
+MAILER_DSN=smtp://mailer:1026
+MAILER_FROM=mailer@test.escapepage.com
+
+## --- Database -------------------------------------------------------------
+# `database` is the compose *service* name and resolves inside this stack's
+# own network - keep it as-is. Use its own name + fresh credentials so a mistake
+# here can never point at the production database.
+DB_NAME=escapepage_test
+DB_USER=escapepage
+DB_PASSWORD=CHANGE_ME_test_db_password
+MYSQL_ROOT_PASSWORD=CHANGE_ME_test_root_password
+DATABASE_URL=pdo_mysql://escapepage:CHANGE_ME_test_db_password@database:3306/escapepage_test?serverVersion=8.0.32&charset=utf8mb4
+
+## --- Mercure -----------------------------------------------------------------
+# Internal hub URL (service name, stays the same). Public URL + CORS must be the
+# test domain. Add a `mercure-test.escapepage.com` proxy host in NPM ->
+# <project>-mercure:80.
+MERCURE_URL=http://mercure/.well-known/mercure
+MERCURE_PUBLIC_URL=https://mercure-test.escapepage.com/.well-known/mercure
+MERCURE_JWT_SECRET=CHANGE_ME_generate_with_openssl_rand_hex_32
+MERCURE_CORS_ALLOWED_ORIGINS="https://test.escapepage.com"
+MERCURE_TOPIC_BASE=https://test.escapepage.com
+
+## --- reCAPTCHA v3 ----------------------------------------------------------
+# Register test.escapepage.com in the reCAPTCHA admin console and paste its keys,
+# or leave the placeholders and expect the contact / "suggest a room" forms to
+# fail captcha validation on staging.
+RECAPTCHA3_KEY=CHANGE_ME_or_reuse_prod_if_domain_added
+RECAPTCHA3_SECRET=CHANGE_ME_or_reuse_prod_if_domain_added

docker/compose.override.yaml

@@ -17,8 +17,8 @@ services:
   mailer:
     image: axllent/mailpit
     ports:
-      - "1025:1025"
+      - "${MAILPIT_SMTP_PORT:-1025}:1025"
-      - "8025:8025"
+      - "${MAILPIT_UI_PORT:-8025}:8025"
     environment:
       MP_SMTP_AUTH_ACCEPT_ANY: 1
       MP_SMTP_AUTH_ALLOW_INSECURE: 1

docker/compose.yaml

@@ -1,5 +1,14 @@
 version: '3.7'
 
+# This stack can run more than once on the same host (e.g. production + a
+# test.escapepage.com staging copy). Everything that must be unique per instance
+# comes from docker/.env:
+#   STACK_NAME              -> container name prefix   (default: escapepage)
+#   COMPOSE_PROJECT_NAME    -> compose project / network namespace
+#   NGINX_HTTP_PORT etc.    -> published host ports
+# With no docker/.env overrides it behaves exactly as before: containers
+# escapepage-*, ports 8080/8443/3306/8090/8025.
+
 services:
   php:
     build:
@@ -8,7 +17,7 @@ services:
       args:
         USER_ID: ${USER_ID}
         GROUP_ID: ${GROUP_ID}
-    container_name: escapepage-php
+    container_name: ${STACK_NAME:-escapepage}-php
     volumes:
       - ../:/var/www/html:delegated
       - /etc/hosts:/etc/hosts:ro
@@ -40,7 +49,7 @@ services:
       args:
         USER_ID: ${USER_ID}
         GROUP_ID: ${GROUP_ID}
-    container_name: escapepage-php-worker
+    container_name: ${STACK_NAME:-escapepage}-php-worker
     volumes:
       - ../:/var/www/html:delegated
       - /etc/hosts:/etc/hosts:ro
@@ -73,7 +82,7 @@ services:
       args:
         USER_ID: ${USER_ID}
         GROUP_ID: ${GROUP_ID}
-    container_name: escapepage-php-cron
+    container_name: ${STACK_NAME:-escapepage}-php-cron
     volumes:
       - ../:/var/www/html:delegated
       - /etc/hosts:/etc/hosts:ro
@@ -101,10 +110,10 @@ services:
 
   nginx:
     image: nginx:1.29.4-alpine
-    container_name: escapepage-nginx
+    container_name: ${STACK_NAME:-escapepage}-nginx
     ports:
-      - "8080:80"
+      - "${NGINX_HTTP_PORT:-8080}:80"
-      - "8443:443"
+      - "${NGINX_HTTPS_PORT:-8443}:443"
     volumes:
       - ../:/var/www/html:ro
       - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
@@ -112,16 +121,18 @@ services:
       - /etc/hosts:/etc/hosts:ro
     depends_on:
       - php
-    # networks:
+    # Joined to the Nginx Proxy Manager network so NPM can forward straight to
-    #   backend:
+    # "<project>-nginx" without going back out to a published host port.
-    #     ipv4_address: 172.23.0.12
+    networks:
+      - default
+      - nginx_proxy
     restart: unless-stopped
 
   mailer:
     image: axllent/mailpit:latest
-    container_name: escapepage-mailer
+    container_name: ${STACK_NAME:-escapepage}-mailer
     ports:
-      - "8025:8025"
+      - "${MAILPIT_UI_PORT:-8025}:8025"
     volumes:
       - /etc/hosts:/etc/hosts:ro
     networks:
@@ -131,7 +142,7 @@ services:
 
   mercure:
     image: dunglas/mercure:v0.21
-    container_name: escapepage-mercure
+    container_name: ${STACK_NAME:-escapepage}-mercure
     environment:
       SERVER_NAME: "http://:80"
       MERCURE_PUBLISHER_JWT_KEY: ${MERCURE_JWT_SECRET}
@@ -143,7 +154,7 @@ services:
         publish_origins ${MERCURE_CORS_ALLOWED_ORIGINS}
         anonymous
     ports:
-      - "8090:80"
+      - "${MERCURE_HTTP_PORT:-8090}:80"
     volumes:
       - /etc/hosts:/etc/hosts:ro
     networks:
@@ -154,7 +165,7 @@ services:
   ###> doctrine/doctrine-bundle ###
   database:
     image: mysql:8.0
-    container_name: escapepage-db
+    container_name: ${STACK_NAME:-escapepage}-db
     environment:
       MYSQL_DATABASE: ${DB_NAME}
       MYSQL_USER: ${DB_USER}
@@ -173,7 +184,7 @@ services:
       - /etc/hosts:/etc/hosts:ro
     # Uncomment the two lines below if you need to access MySQL from your host (workbench, etc.)
     ports:
-      - "3306:3306"
+      - "${DB_HOST_PORT:-3306}:3306"
     # networks:
     #   backend:
     #     ipv4_address: 172.23.0.15

docker/restart.sh

@@ -1,22 +1,50 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Script to completely restart the project as requested
+# Completely restart ONE project stack (prod or a test/staging copy).
-# Can be run from any directory
+# Can be run from any directory. Everything is scoped to the Compose project
+# name so running this from the test checkout never touches the prod stack.
+#
+#   ./docker/restart.sh              # rebuild-less restart of this checkout's stack
+#   ./docker/restart.sh --prune-all  # also run host-wide `docker system/builder prune`
+#                                    # (old behaviour; skip it when another stack shares the host)
 
 DOCKER_DIR=$(cd "$(dirname "$0")" && pwd)
 ROOT_DIR=$(cd "$DOCKER_DIR/.." && pwd)
 
-echo "Stopping and removing containers..."
+PRUNE_ALL=0
-(cd "$DOCKER_DIR" && docker compose -f compose.yaml -f compose.override.yaml down -v --remove-orphans) || true
+for arg in "$@"; do
-docker network rm escapepage_network || true
+  case "$arg" in
-docker network rm $(docker network ls -q --filter name=escapepage) || true
+    --prune-all) PRUNE_ALL=1 ;;
-docker network prune -f || true
+    *) echo "Unknown option: $arg" >&2; exit 1 ;;
-docker rm -f escapepage-db escapepage-php escapepage-nginx escapepage-mercure escapepage-mailer escapepage-php-worker escapepage-php-cron || true
+  esac
-docker system prune -f || true
+done
 
-echo "Clearing Docker build cache..."
+# Read the identifiers from docker/.env (same file Compose uses). STACK_NAME is
-docker builder prune -af
+# the container-name prefix; COMPOSE_PROJECT_NAME is the compose project.
+read_env() { [ -f "$DOCKER_DIR/.env" ] && grep -E "^$1=" "$DOCKER_DIR/.env" | tail -n1 | cut -d= -f2- | tr -d "\"'" || true; }
+STACK="$(read_env STACK_NAME)";            STACK="${STACK:-escapepage}"
+PROJECT="$(read_env COMPOSE_PROJECT_NAME)"; PROJECT="${PROJECT:-$STACK}"
+echo "Restarting stack: $STACK (compose project: $PROJECT)"
+
+echo "Stopping and removing containers..."
+(cd "$DOCKER_DIR" && docker compose -p "$PROJECT" -f compose.yaml -f compose.override.yaml down -v --remove-orphans) || true
+
+# Belt-and-suspenders: drop anything still lingering for THIS stack only.
+docker rm -f \
+  "${STACK}-db" "${STACK}-php" "${STACK}-nginx" "${STACK}-mercure" \
+  "${STACK}-mailer" "${STACK}-php-worker" "${STACK}-php-cron" 2>/dev/null || true
+for net in $(docker network ls -q --filter "name=^${PROJECT}_" 2>/dev/null); do
+  docker network rm "$net" || true
+done
+
+if [ "$PRUNE_ALL" -eq 1 ]; then
+  echo "Host-wide prune (containers, networks, build cache)..."
+  docker system prune -f || true
+  docker builder prune -af || true
+else
+  echo "Skipping host-wide prune (pass --prune-all to force it)."
+fi
 
 echo "Setting permissions for var/volumes/db and var directories..."
 sudo chown -R 1000:1000 "$ROOT_DIR/var/volumes/db" || true