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.

docs/production-deployment.md

@@ -30,7 +30,7 @@ Gebruik je bestaande beheeraccount voor deze stappen:
 5. Schakel **Terminal en SNMP → Terminal → SSH-service inschakelen** in. De
    maintainer heeft SSH-poort **22** bevestigd. Beperk toegang tot mini-pc/LAN/VPN;
    configureer geen internet-portforwarding.
-6. Controleer dat Container Manager/Docker draait, dat Docker Compose **v2**,
+6. Controleer dat Container Manager/Docker draait, dat Docker Compose **v2.17 of nieuwer**,
    `curl`, `timeout` met `-k` en `sh` beschikbaar zijn. Op de NAS is geen Java,
    Python of Git nodig. Controleer het Docker-pad, doorgaans `/usr/local/bin/docker`.
 
@@ -287,8 +287,8 @@ nieuwe release door te drukken.
 ## Na S16 en lokale verificatie
 
 De databaseservice en het volume `agiledancers-production-database` blijven buiten
-de vervanging van backend en frontend. `production.env` levert het databasewachtwoord
-ook bij retry en rollback; het staat niet in releasebestanden. De procedure vereist
+de vervanging van backend en frontend. Compose leest `production.env` rechtstreeks via `--env-file`, zodat het
+databasewachtwoord ook via sudo en bij retry en rollback beschikbaar is; het staat niet in releasebestanden. De procedure vereist
 databasecompatibiliteit met de vorige applicatieversie. Plan incompatibele migraties
 apart: imageherstel maakt geen migratie ongedaan. Rollback naar een oude release
 van vóór S16 kan de database niet lezen. Backup/restore blijven S17-werk.