Fix pipeline deployment with postgres

docs/persistent-storage.md

@@ -12,8 +12,10 @@ school ownership of every relationship.
 Production uses `deploy/compose.yaml`: PostgreSQL has no published port and keeps
 its data in the named volume `agiledancers-production-database`. Set a long random
 `DATABASE_PASSWORD` in the mode-600 `production.env` on the NAS before the first
-S16 deployment. The release helper exports it for Compose without writing it to
-release metadata. The backend receives:
+S16 deployment. Compose reads it directly from this file, including when Docker runs through
+`sudo`; exporting it in the SSH shell does not survive the default sudo environment
+filter. The password is never written to release metadata. Deployment preflight
+rejects a missing password before pulling images or replacing containers. The backend receives:
 
 - `DATABASE_URL=jdbc:postgresql://database:5432/agiledancers`
 - `DATABASE_USER=agiledancers`
@@ -26,6 +28,23 @@ WAL, fsync and synchronous-commit defaults must remain enabled. Application writ
 are acknowledged only after commit. A network loss during acknowledgement can
 leave the client uncertain; reload current data before deciding to retry.
 
+## Deployment failure before the first S16 release
+
+A missing `DATABASE_PASSWORD` can make `compose config --quiet` exit with status
+15. Configure the password in the existing NAS `production.env` (trusted shell
+configuration, mode `600`), for example `DATABASE_PASSWORD='<long random value>'`.
+Keep the same password after PostgreSQL initializes its volume: changing only this
+file does not change the database account password. Use Compose v2.17 or newer;
+the deployment reads `production.env` and then the retained `release.env` through
+two `--env-file` options, so sudo cannot discard the credential. Do not print
+expanded Compose configuration because it contains the password; use `config --quiet`.
+
+If the attempt was rejected before container replacement, no pending journal or
+lock remains and the old release continues running. After merging the deployment
+fix and completing the export below, run a new deployment. Use retry only if the
+failed attempt already created a version tag. Do not remove a lock or pending
+journal if one does remain; follow the production recovery runbook.
+
 ## Transition from the previous release
 
 1. Export **every school** through JSON while the old backend is still running.