DEPLOYMENT.md: Fehlerbehebung für "password authentication failed"

Beim Ausrollen auf einem echten Server aufgetreten: PostgreSQL setzt
sein Passwort nur beim allerersten Start auf leerem Datenverzeichnis –
lief "docker compose up" vorher schon einmal ohne "--env-file
.env.local" (oder wurde LOCAL_PG_PASSWORD nachträglich geändert),
bleibt im Volume ein anderes Passwort stehen als die App danach
verwendet.

Neue Fehlerbehebung-Sektion mit der konkreten Fehlermeldung und zwei
Fixes (Volume neu anlegen bei frischem Deployment, sonst Passwort im
laufenden Container angleichen). Warnhinweis in Schritt 3 ergänzt.

.env.example: Hinweis, dass LOCAL_PG_PASSWORD nur aus Buchstaben/
Zahlen bestehen sollte (#, $, Leerzeichen, Anführungszeichen können
beim .env-Parsing zu stillen Fehlern führen).

.env.example

@@ -7,6 +7,22 @@
 # zusammen – die Zeile unten wird beim Betrieb per Docker Compose
 # NICHT verwendet, nur bei manuellem "npm run dev"/"npm run start"
 # gegen eine selbst betriebene PostgreSQL-Instanz.
+#
+# Nur Buchstaben/Zahlen verwenden (z. B. mit "openssl rand -hex 24"
+# erzeugen) – Zeichen wie #, $, Leerzeichen oder Anführungszeichen
+# werden von Docker Compose beim Einlesen von .env-Dateien speziell
+# behandelt (# beginnt z. B. einen Kommentar) und können das Passwort
+# unbemerkt verstümmeln.
+#
+# WICHTIG: PostgreSQL setzt dieses Passwort nur EINMALIG beim allerersten
+# Start auf einem leeren Datenverzeichnis. Wird der Wert hier später
+# geändert (oder "docker compose up" auch nur einmal ohne
+# "--env-file .env.local" ausgeführt, bevor er gesetzt war), bleibt im
+# bereits angelegten Docker-Volume das alte Passwort stehen – die App
+# bekommt dann "password authentication failed for user postgres". Fix:
+# "docker compose down && docker volume rm canteen-menu_pgdata", dann
+# neu starten (nur unbedenklich, solange noch keine echten Daten drin
+# sind – siehe DEPLOYMENT.md).
 LOCAL_PG_PASSWORD=<beliebiges-sicheres-passwort>
 
 # Verbindung zur PostgreSQL-Datenbank (nur für den Betrieb OHNE Docker

DEPLOYMENT.md

@@ -39,7 +39,7 @@ cp .env.example .env.local
 
 | Variable | Was rein muss |
 | --- | --- |
-| `LOCAL_PG_PASSWORD` | Ein neues, zufälliges Passwort (z. B. `openssl rand -base64 24`) – wird beim ersten Start zum Datenbank-Passwort des mitgelieferten PostgreSQL-Containers |
+| `LOCAL_PG_PASSWORD` | Ein neues, zufälliges Passwort **nur aus Buchstaben/Zahlen** (z. B. `openssl rand -hex 24`) – wird beim ersten Start zum Datenbank-Passwort des mitgelieferten PostgreSQL-Containers. Zeichen wie `#`, `$`, Leerzeichen oder Anführungszeichen können beim Einlesen der `.env`-Datei zu Problemen führen (`#` beginnt z. B. einen Kommentar) |
 | `APP_URL` | Die öffentliche URL mit Schema, z. B. `https://menu.example.de` (auch wenn HTTPS erst in Schritt 5 eingerichtet wird – schon jetzt korrekt eintragen, da daraus u. a. die Passkey-Domain abgeleitet wird) |
 | `SITE_TITLE` | Optional, Titel im Browser-Tab/Überschrift ohne Logo |
 | `ADMIN_EMAIL` | Optional, E-Mail des automatisch angelegten Admin-Erstnutzers. Ohne Angabe: `admin@<Hostname aus APP_URL>` |
@@ -59,6 +59,15 @@ touch ZUGANGSDATEN.md
 
 ## 3. App starten
 
+**Wichtig:** `.env.local` muss vollständig ausgefüllt sein, *bevor*
+dieser Befehl zum ersten Mal läuft – und danach immer mit
+`--env-file .env.local` aufgerufen werden. PostgreSQL setzt sein
+Passwort nur beim allerersten Start auf einem leeren Datenverzeichnis;
+läuft der Befehl vorher schon einmal ohne (oder mit einem anderen)
+`--env-file`, landet ein falsches Passwort dauerhaft im Datenbank-Volume
+(Symptom: `password authentication failed for user "postgres"` in den
+App-Logs, siehe [Fehlerbehebung](#fehlerbehebung)).
+
 ```bash
 docker compose --env-file .env.local up -d --build
 ```
@@ -138,6 +147,35 @@ docker compose --env-file .env.local up -d
   werden im Kantinen-Bereich gepflegt.
 - Logo/Favicon/Farben unter „Design“ (nur Admin) anpassen.
 
+## Fehlerbehebung
+
+### `password authentication failed for user "postgres"` in den App-Logs
+
+Ursache: Das Docker-Volume der Datenbank wurde bereits mit einem
+anderen Passwort initialisiert, als aktuell in `.env.local` steht (z. B.
+weil `docker compose up` einmal ohne `--env-file .env.local` lief, bevor
+das Passwort gesetzt war, oder `LOCAL_PG_PASSWORD` nachträglich geändert
+wurde – PostgreSQL übernimmt das Passwort nur beim allerersten Start).
+
+Fix, solange noch keine echten Daten in der Datenbank sind (bei einem
+frischen Deployment immer der Fall):
+
+```bash
+docker compose --env-file .env.local down
+docker volume rm canteen-menu_pgdata
+docker compose --env-file .env.local up -d --build
+docker compose logs app --tail 30
+```
+
+Existieren bereits echte Daten, stattdessen das Passwort direkt im
+laufenden Datenbank-Container an `.env.local` angleichen, statt das
+Volume zu löschen:
+
+```bash
+docker compose exec db psql -U postgres -c "ALTER USER postgres WITH PASSWORD '<Wert aus LOCAL_PG_PASSWORD>';"
+docker compose --env-file .env.local up -d
+```
+
 ## Updates einspielen
 
 ```bash