Add dedicated setup.test.sh / restart.test.sh for the staging stack

Both refuse to run unless docker/.env names a non-prod COMPOSE_PROJECT_NAME and
scope every compose call to that project.

setup.test.sh: like setup.sh but runs the DB/cache/console steps as www-data and
repairs var/cache|log|sessions ownership at the end, so php-fpm can read its own
compiled cache (bare `docker exec` runs as root -> silent 500s). Never touches
var/volumes/db. Test-appropriate final message (NPM upstream, local curl check).

restart.test.sh: keeps the database by default (--fresh-db to wipe + re-init),
never runs a host-wide docker prune, and only chowns var/cache|log|sessions
(chowning var/volumes/db is what corrupted the MySQL data dir).

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

doc/test-environment.md

@@ -71,11 +71,17 @@ already supplied to the containers by `docker/.env`.
 
 ### 5. Build & start
 ```bash
-./docker/setup.sh
+./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 image
+`escapepage_test`, builds assets. Re-run any time; `--no-build` skips the rebuild.
-rebuild.
 
 ### 6. Nginx Proxy Manager — proxy host
 - Domain: `test.escapepage.com`
@@ -114,25 +120,32 @@ deny  all;
 ## Deploying a new version to test
 
 ```bash
-cd /opt/escapepage-test
+cd /var/sites/escapepage-test
 git fetch && git checkout <branch> && git pull
-docker compose -f docker/compose.yaml -f docker/compose.override.yaml \
+./docker/setup.test.sh --no-build     # composer install, migrate, build assets, fix perms
-  exec php composer install
+```
-docker compose ... exec php php bin/console doctrine:migrations:migrate -n
+
-docker compose ... exec php php bin/console cache:clear
+`--no-build` skips the image rebuild; drop it if the Dockerfile changed.
-docker compose ... exec php npm ci && ... npm run build
+
-docker restart escapepage-test-php-worker
+## 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
 ```
-(Or just `./docker/setup.sh --no-build`.)
 
 ## Safety notes
 
-- **`docker/restart.sh` is now scoped to `STACK_NAME` / `COMPOSE_PROJECT_NAME`**
+- Use the **`*.test.sh`** scripts on this checkout, not `setup.sh` / `restart.sh`.
-  from `docker/.env` — running it in the test checkout only touches
+  Both refuse to run unless `docker/.env` names a non-prod
-  `escapepage-test-*`. The host-wide
+  `COMPOSE_PROJECT_NAME`, and both scope every action to that project — they
-  `docker system prune` / `docker builder prune` it used to always run are now
+  can't reach the production stack.
-  opt-in via `./docker/restart.sh --prune-all`; don't use that flag while the
+- `restart.test.sh` **keeps the database** by default (you loaded prod data into
-  other stack shares the host.
+  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

docker/.env.test.example

@@ -19,7 +19,9 @@
 # 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
+#                           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
 

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