From b565825cd92016d84c3f47a2222b448549d96f9b Mon Sep 17 00:00:00 2001 From: Frank Date: Sat, 29 Aug 2026 23:52:53 +0200 Subject: [PATCH] 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:-}, 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 -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 --- doc/test-environment.md | 139 +++++++++++++++++++++++++++++++++++ docker/.env.test.example | 75 +++++++++++++++++++ docker/compose.override.yaml | 4 +- docker/compose.yaml | 41 +++++++---- docker/restart.sh | 50 ++++++++++--- 5 files changed, 281 insertions(+), 28 deletions(-) create mode 100644 doc/test-environment.md create mode 100644 docker/.env.test.example diff --git a/doc/test-environment.md b/doc/test-environment.md new file mode 100644 index 0000000..6fcbfb1 --- /dev/null +++ b/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 /opt/escapepage-test +cd /opt/escapepage-test +git checkout +``` +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= +# 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 ` 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 ; +deny all; +``` + +## Deploying a new version to test + +```bash +cd /opt/escapepage-test +git fetch && git checkout && 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. diff --git a/docker/.env.test.example b/docker/.env.test.example new file mode 100644 index 0000000..bb8565c --- /dev/null +++ b/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). +# - /.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 -> +# -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 diff --git a/docker/compose.override.yaml b/docker/compose.override.yaml index 54b56d7..5abbe42 100644 --- a/docker/compose.override.yaml +++ b/docker/compose.override.yaml @@ -17,8 +17,8 @@ services: mailer: image: axllent/mailpit ports: - - "1025:1025" - - "8025:8025" + - "${MAILPIT_SMTP_PORT:-1025}:1025" + - "${MAILPIT_UI_PORT:-8025}:8025" environment: MP_SMTP_AUTH_ACCEPT_ANY: 1 MP_SMTP_AUTH_ALLOW_INSECURE: 1 diff --git a/docker/compose.yaml b/docker/compose.yaml index b876a66..33d246b 100644 --- a/docker/compose.yaml +++ b/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" - - "8443:443" + - "${NGINX_HTTP_PORT:-8080}:80" + - "${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: - # backend: - # ipv4_address: 172.23.0.12 + # Joined to the Nginx Proxy Manager network so NPM can forward straight to + # "-nginx" without going back out to a published host port. + 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 diff --git a/docker/restart.sh b/docker/restart.sh index 68d1a26..97fd955 100755 --- a/docker/restart.sh +++ b/docker/restart.sh @@ -1,22 +1,50 @@ #!/usr/bin/env bash set -euo pipefail -# Script to completely restart the project as requested -# Can be run from any directory +# Completely restart ONE project stack (prod or a test/staging copy). +# 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..." -(cd "$DOCKER_DIR" && docker compose -f compose.yaml -f compose.override.yaml down -v --remove-orphans) || true -docker network rm escapepage_network || true -docker network rm $(docker network ls -q --filter name=escapepage) || true -docker network prune -f || true -docker rm -f escapepage-db escapepage-php escapepage-nginx escapepage-mercure escapepage-mailer escapepage-php-worker escapepage-php-cron || true -docker system prune -f || true +PRUNE_ALL=0 +for arg in "$@"; do + case "$arg" in + --prune-all) PRUNE_ALL=1 ;; + *) echo "Unknown option: $arg" >&2; exit 1 ;; + esac +done -echo "Clearing Docker build cache..." -docker builder prune -af +# Read the identifiers from docker/.env (same file Compose uses). STACK_NAME is +# 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