Merge branch 'docker-test-environment': multi-instance Docker stack + test.escapepage.com scripts

doc/test-environment.md

@@ -0,0 +1,152 @@
+# 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.test.sh
+```
+The test-specific script (not `setup.sh`): it refuses to run unless
+`COMPOSE_PROJECT_NAME` in `docker/.env` is a non-prod value, scopes every compose
+call to that project, runs the DB/cache/console steps as `www-data`, and repairs
+`var/cache` / `var/log` / `var/sessions` ownership at the end (bare `docker exec`
+runs as root, which otherwise leaves php-fpm unable to read its own cache — a
+silent 500). It never touches `var/volumes/db`.
+
+Builds `escapepage-test-*` images, starts the containers, creates + migrates
+`escapepage_test`, builds assets. Re-run any time; `--no-build` skips the 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 /var/sites/escapepage-test
+git fetch && git checkout <branch> && git pull
+./docker/setup.test.sh --no-build     # composer install, migrate, build assets, fix perms
+```
+
+`--no-build` skips the image rebuild; drop it if the Dockerfile changed.
+
+## Restarting
+
+```bash
+./docker/restart.test.sh              # down + up, keeps the DB and images
+./docker/restart.test.sh --build      # also rebuild images
+./docker/restart.test.sh --fresh-db   # also wipe var/volumes/db and re-init MySQL
+```
+
+## Safety notes
+
+- Use the **`*.test.sh`** scripts on this checkout, not `setup.sh` / `restart.sh`.
+  Both refuse to run unless `docker/.env` names a non-prod
+  `COMPOSE_PROJECT_NAME`, and both scope every action to that project — they
+  can't reach the production stack.
+- `restart.test.sh` **keeps the database** by default (you loaded prod data into
+  it); `--fresh-db` is the only thing that wipes it. It never runs a host-wide
+  `docker system prune` / `docker builder prune`, and it only repairs ownership
+  of `var/cache` / `var/log` / `var/sessions` — **never `var/volumes/db`**
+  (chowning the MySQL data dir is what corrupted it earlier this build).
+- 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,77 @@
+# =============================================================================
+#  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` / *.test.sh act on.
+#                           Must be a non-prod value or setup.test.sh / restart.test.sh
+#                           refuse to run.
+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

docker/restart.test.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Restart the TEST (staging) stack. Scoped entirely to this checkout's compose
+# project, so it can never touch the production stack. Unlike docker/restart.sh
+# it:
+#   - keeps the database by default (you loaded prod data into it) — pass
+#     --fresh-db to wipe var/volumes/db and let MySQL re-initialise
+#   - never runs a host-wide `docker system/builder prune`
+#   - only repairs ownership of var/cache, var/log, var/sessions — NEVER
+#     var/volumes/db (that dir belongs to the mysql process; chowning it is
+#     what corrupts the data directory)
+#
+# Usage:
+#   ./docker/restart.test.sh              # down + up (keeps DB and images)
+#   ./docker/restart.test.sh --build      # also rebuild images
+#   ./docker/restart.test.sh --fresh-db   # also wipe + re-initialise the database
+
+DOCKER_DIR=$(cd "$(dirname "$0")" && pwd)
+ROOT_DIR=$(cd "$DOCKER_DIR/.." && pwd)
+
+env_val() { [ -f "$DOCKER_DIR/.env" ] && grep -E "^$1=" "$DOCKER_DIR/.env" | tail -n1 | cut -d= -f2- | tr -d "\"' " || true; }
+
+if [ ! -f "$DOCKER_DIR/.env" ]; then
+  echo "Error: $DOCKER_DIR/.env not found. Copy docker/.env.test.example to docker/.env first." >&2
+  exit 1
+fi
+PROJECT="$(env_val COMPOSE_PROJECT_NAME)"
+STACK="$(env_val STACK_NAME)"; STACK="${STACK:-$PROJECT}"
+case "${PROJECT:-}" in
+  ""|escapepage|docker)
+    echo "Error: COMPOSE_PROJECT_NAME in docker/.env is '${PROJECT:-<unset>}'." >&2
+    echo "Refusing to run a test script against the production stack." >&2
+    exit 1 ;;
+esac
+
+if docker compose version >/dev/null 2>&1; then
+  DOCKER_COMPOSE="docker compose"
+elif command -v docker-compose >/dev/null 2>&1; then
+  DOCKER_COMPOSE="docker-compose"
+else
+  echo "Error: neither 'docker compose' nor 'docker-compose' is available." >&2
+  exit 1
+fi
+
+FRESH_DB=0; BUILD=0
+for arg in "$@"; do
+  case "$arg" in
+    --fresh-db) FRESH_DB=1 ;;
+    --build)    BUILD=1 ;;
+    *) echo "Unknown option: $arg" >&2; exit 1 ;;
+  esac
+done
+
+dc() { (cd "$DOCKER_DIR" && $DOCKER_COMPOSE -p "$PROJECT" -f compose.yaml -f compose.override.yaml "$@"); }
+
+echo "Restarting test stack: $STACK  (compose project: $PROJECT)"
+
+echo "Stopping containers..."
+dc down --remove-orphans || true
+# scoped fallback — only this stack
+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 [ "$FRESH_DB" -eq 1 ]; then
+  echo "Wiping the test database (var/volumes/db)..."
+  sudo rm -rf "$ROOT_DIR/var/volumes/db"
+fi
+
+echo "Repairing var/ ownership (cache/log/sessions only)..."
+sudo mkdir -p "$ROOT_DIR/var/cache" "$ROOT_DIR/var/log/php" "$ROOT_DIR/var/log/cron" "$ROOT_DIR/var/sessions"
+sudo chown -R 1000:1000 "$ROOT_DIR/var/cache" "$ROOT_DIR/var/log" "$ROOT_DIR/var/sessions"
+sudo chmod -R u+rwX,g+rwX "$ROOT_DIR/var/cache" "$ROOT_DIR/var/log" "$ROOT_DIR/var/sessions"
+
+echo "Bringing the stack back up..."
+if [ "$BUILD" -eq 1 ]; then
+  "$DOCKER_DIR/setup.test.sh"
+else
+  "$DOCKER_DIR/setup.test.sh" --no-build
+fi

docker/setup.test.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Bootstrap / re-provision a TEST (staging) stack — e.g. test.escapepage.com.
+# Same job as docker/setup.sh, but:
+#   - refuses to run unless docker/.env marks this as a non-prod stack
+#   - scopes every compose call to COMPOSE_PROJECT_NAME
+#   - runs DB / cache / console steps as www-data and repairs var/ ownership at
+#     the end, so php-fpm (www-data) can actually read the compiled container
+#     (bare `docker exec` runs as root and would leave var/cache root-owned)
+#   - NEVER touches var/volumes/db (MySQL owns that)
+#
+# Usage:
+#   ./docker/setup.test.sh              # full setup (build images)
+#   ./docker/setup.test.sh --no-build   # skip image rebuild
+#   ./docker/setup.test.sh --recreate   # force-recreate containers
+#   ./docker/setup.test.sh --down       # stop and remove this stack's containers
+
+DOCKER_DIR=$(cd "$(dirname "$0")" && pwd)
+ROOT_DIR=$(cd "$DOCKER_DIR/.." && pwd)
+
+env_val() { [ -f "$DOCKER_DIR/.env" ] && grep -E "^$1=" "$DOCKER_DIR/.env" | tail -n1 | cut -d= -f2- | tr -d "\"' " || true; }
+
+# --- safety gate: never let a *.test.sh script act on the production stack ----
+if [ ! -f "$DOCKER_DIR/.env" ]; then
+  echo "Error: $DOCKER_DIR/.env not found. Copy docker/.env.test.example to docker/.env and fill it in." >&2
+  exit 1
+fi
+PROJECT="$(env_val COMPOSE_PROJECT_NAME)"
+STACK="$(env_val STACK_NAME)"; STACK="${STACK:-$PROJECT}"
+case "${PROJECT:-}" in
+  ""|escapepage|docker)
+    echo "Error: COMPOSE_PROJECT_NAME in docker/.env is '${PROJECT:-<unset>}'." >&2
+    echo "Refusing to run a test script against the production stack." >&2
+    echo "Set COMPOSE_PROJECT_NAME and STACK_NAME to e.g. 'escapepage-test' in docker/.env." >&2
+    exit 1 ;;
+esac
+
+# --- compose command -------------------------------------------------------
+if docker compose version >/dev/null 2>&1; then
+  DOCKER_COMPOSE="docker compose"
+elif command -v docker-compose >/dev/null 2>&1; then
+  DOCKER_COMPOSE="docker-compose"
+else
+  echo "Error: neither 'docker compose' nor 'docker-compose' is available." >&2
+  exit 1
+fi
+command -v docker >/dev/null 2>&1 || { echo "Error: docker is required." >&2; exit 1; }
+
+dc()       { (cd "$DOCKER_DIR" && $DOCKER_COMPOSE -p "$PROJECT" -f compose.yaml -f compose.override.yaml "$@"); }
+pexec()    { dc exec -T php "$@"; }                 # as root (composer / npm)
+pexecwww() { dc exec -T -u www-data php "$@"; }     # as www-data (console / DB / cache)
+
+REBUILD=1; RECREATE=0; DOWN_ONLY=0
+for arg in "$@"; do
+  case "$arg" in
+    --no-build) REBUILD=0 ;;
+    --recreate) RECREATE=1 ;;
+    --down)     DOWN_ONLY=1 ;;
+    *) echo "Unknown option: $arg" >&2; exit 1 ;;
+  esac
+done
+
+echo "Test stack: $STACK  (compose project: $PROJECT)"
+
+if [ "$DOWN_ONLY" -eq 1 ]; then
+  dc down --remove-orphans
+  exit 0
+fi
+
+BUILD_ARGS=()
+[ "$REBUILD" -eq 1 ]  && BUILD_ARGS+=("--build")
+[ "$RECREATE" -eq 1 ] && BUILD_ARGS+=("--force-recreate")
+
+dc up -d "${BUILD_ARGS[@]}"
+
+# --- wait for the database ------------------------------------------------
+printf "Waiting for database to be healthy..."
+for i in $(seq 1 60); do
+  DB_ID=$(dc ps -q database 2>/dev/null || true)
+  if [ -n "$DB_ID" ] && [ "$(docker inspect -f '{{.State.Health.Status}}' "$DB_ID" 2>/dev/null || true)" = "healthy" ]; then
+    echo " OK"; break
+  fi
+  printf "."; sleep 2
+  [ "$i" -eq 60 ] && echo -e "\nWarning: database not healthy yet, continuing anyway."
+done
+
+# --- dependencies (root: writes vendor/ and node_modules/) --------------
+pexec composer install --no-interaction
+
+# --- APP_SECRET: generate into .env.local if it's set nowhere -----------
+if ! grep -qsE '^APP_SECRET=.+' "$ROOT_DIR/.env" "$ROOT_DIR/.env.local"; then
+  echo "Generating APP_SECRET in .env.local..."
+  printf 'APP_SECRET=%s\n' "$(openssl rand -hex 16)" >> "$ROOT_DIR/.env.local"
+fi
+
+# --- database (www-data: keeps var/ writable by php-fpm) ---------------
+echo "Creating database if it doesn't exist..."
+pexecwww php bin/console doctrine:database:create --if-not-exists || {
+  echo "Error: database creation failed." >&2; dc logs database | tail -n 40; exit 1;
+}
+echo "Running migrations..."
+pexecwww php bin/console doctrine:migrations:migrate -n || { echo "Error: migrations failed." >&2; exit 1; }
+
+[ -f "$ROOT_DIR/importmap.php" ] && pexec php bin/console importmap:install || true
+
+if [ -f "$ROOT_DIR/package.json" ]; then
+  echo "Installing npm dependencies..."; pexec npm ci || pexec npm install
+  echo "Building assets...";             pexec npm run build
+fi
+
+# --- repair var/ ownership for php-fpm (www-data), never var/volumes ----
+echo "Fixing var/ ownership for php-fpm..."
+pexec sh -lc 'mkdir -p var/cache var/log/php var/log/cron var/sessions && chown -R www-data:www-data var/cache var/log var/sessions'
+
+pexecwww php bin/console cache:clear
+
+NGINX_HTTPS="$(env_val NGINX_HTTPS_PORT)"
+MAILPIT_UI="$(env_val MAILPIT_UI_PORT)"
+
+cat <<EOT
+
+Test stack '$PROJECT' is up.
+
+  NPM upstream:   ${STACK}-nginx   (scheme https, port 443, "Verify SSL" off)
+  Local check:    curl -k https://${NGINX_HTTPS:-127.0.0.1:18443}/
+  Mailpit UI:     http://${MAILPIT_UI:-127.0.0.1:18026}
+
+  Logs:    docker logs -f ${STACK}-php
+  Shell:   docker exec -it -u www-data ${STACK}-php sh
+  Restart: ./docker/restart.test.sh   (add --fresh-db to wipe + re-init the DB)
+
+Re-run this script any time. Use --no-build to skip the image rebuild.
+EOT