tools/dev-deploy/.env.example

@@ -14,7 +14,9 @@ BACKEND_DEV_SANDBOX_ENGINE_VERSION=0.1.0
 BACKEND_DEV_SANDBOX_PLAYER_COUNT=20
 
 # `123456` short-circuits the email-code path for the dev account.
-# Leave empty in environments where real Mailpit codes must be used.
+# This is also the docker-compose default — set the variable to an
+# empty string here when the environment must rely on real Mailpit
+# codes (e.g. mail-flow QA).
 BACKEND_AUTH_DEV_FIXED_CODE=123456
 
 # Name of the external Docker bridge the host Caddy is attached to.

tools/dev-deploy/README.md

@@ -91,14 +91,16 @@ calls `make clean-data`.
 
 ## Logging in
 
-The same dev-mode email-code override as `tools/local-dev/` applies:
+The same dev-mode email-code override as `tools/local-dev/` applies,
+and the dev-deploy compose ships with it enabled by default:
 
 1. Enter `dev@galaxy.lan` (or whatever `BACKEND_DEV_SANDBOX_EMAIL`
    resolves to) in the login form.
-2. Submit `123456` as the code if `BACKEND_AUTH_DEV_FIXED_CODE` is
-   non-empty. Otherwise open Mailpit at
-   `http://galaxy-mailpit:8025/` from inside the network or proxy it
-   through the host Caddy when needed.
+2. Submit `123456` as the code — the docker-compose default for
+   `BACKEND_AUTH_DEV_FIXED_CODE` is `123456`, so the bcrypt-hashed
+   email code stays a fallback. To force real Mailpit codes (e.g. for
+   mail-flow QA), set `BACKEND_AUTH_DEV_FIXED_CODE=` (empty) in a
+   local `.env` and `make rebuild`.
 
 The fixed-code override is rejected by production env loaders, so it
 cannot leak into the prod environment.

tools/dev-deploy/docker-compose.yml

@@ -101,7 +101,12 @@ services:
       BACKEND_NOTIFICATION_WORKER_INTERVAL: 500ms
       BACKEND_OTEL_TRACES_EXPORTER: none
       BACKEND_OTEL_METRICS_EXPORTER: none
-      BACKEND_AUTH_DEV_FIXED_CODE: ${BACKEND_AUTH_DEV_FIXED_CODE:-}
+      # Long-lived dev environment always opts into the fixed-code
+      # override so a returning developer can sign in with `123456`
+      # even after the matching browser session was cleared (the real
+      # bcrypt-hashed code is single-use). Set the var to an empty
+      # string in `.env` to disable.
+      BACKEND_AUTH_DEV_FIXED_CODE: ${BACKEND_AUTH_DEV_FIXED_CODE:-123456}
       BACKEND_DEV_SANDBOX_EMAIL: ${BACKEND_DEV_SANDBOX_EMAIL:-}
       BACKEND_DEV_SANDBOX_ENGINE_IMAGE: ${BACKEND_DEV_SANDBOX_ENGINE_IMAGE:-galaxy-engine:dev}
       BACKEND_DEV_SANDBOX_ENGINE_VERSION: ${BACKEND_DEV_SANDBOX_ENGINE_VERSION:-0.1.0}