Merge fix/deployment-guide-pg-password: DB-Port nicht mehr exponiert, Deployment-Doku-Fixes

Datenbank ist nur noch im internen Compose-Netzwerk erreichbar (kein
Host-Port mehr). DEPLOYMENT.md: Fehlerbehebung für "password
authentication failed" (PostgreSQL übernimmt das Passwort nur beim
allerersten Start), .env.example warnt vor Sonderzeichen in
LOCAL_PG_PASSWORD.

.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

CHANGELOG.md

@@ -4,6 +4,26 @@ Alle nennenswerten Änderungen an diesem Projekt werden hier dokumentiert.
 Format angelehnt an [Keep a Changelog](https://keepachangelog.com/de/1.1.0/),
 Versionierung nach [Semantic Versioning](https://semver.org/lang/de/).
 
+## [1.6.1] – 2026-07-18
+
+### Geändert
+- PostgreSQL-Container ist nicht mehr über einen Host-Port erreichbar
+  (`docker-compose.yml`: `ports: 5433:5432` beim `db`-Dienst entfernt).
+  App und Dev-Server erreichen die Datenbank weiterhin über das von
+  Docker Compose automatisch angelegte interne Netzwerk (Hostname
+  `db`) – reduziert die Angriffsfläche, ohne den Betrieb zu ändern.
+  Debugging/Backup weiterhin über `docker compose exec db psql`/
+  `pg_dump` möglich.
+
+### Behoben
+- DEPLOYMENT.md: Fehlerbehebung-Abschnitt für
+  `password authentication failed for user "postgres"` ergänzt (tritt
+  auf, wenn `docker compose up` vor dem Setzen von `LOCAL_PG_PASSWORD`
+  läuft oder ohne `--env-file .env.local` – PostgreSQL übernimmt das
+  Passwort nur beim allerersten Start auf leerem Datenverzeichnis).
+  `.env.example` warnt jetzt vor Sonderzeichen in `LOCAL_PG_PASSWORD`,
+  die beim `.env`-Parsing zu stillen Fehlern führen können.
+
 ## [1.6.0] – 2026-07-18
 
 ### Hinzugefügt

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

README.md

@@ -110,7 +110,7 @@ PostgreSQL müssen nicht installiert sein):
 ```bash
 docker compose --env-file .env.local up -d --build
 # App: Port 3000 (hinter Reverse-Proxy mit HTTPS betreiben)
-# PostgreSQL: Port 5433
+# PostgreSQL: kein Host-Port, nur intern im Compose-Netzwerk erreichbar
 ```
 
 Vor dem ersten Start: eine leere `ZUGANGSDATEN.md` im Projektverzeichnis

docker-compose.yml

@@ -50,10 +50,10 @@ services:
     environment:
       POSTGRES_DB: canteen_menu
       POSTGRES_PASSWORD: ${LOCAL_PG_PASSWORD:-canteen_menu}
-    ports:
-      # Host-Port 5433, da 5432 meist schon von einer nativen
-      # PostgreSQL-Installation belegt ist.
-      - "5433:5432"
+    # Bewusst kein "ports:"-Mapping: die Datenbank ist nur innerhalb des
+    # Compose-Netzwerks unter "db:5432" erreichbar (für app/dev), nicht
+    # vom Host oder von außen. Zugriff für Debugging/Backups über
+    # "docker compose exec db psql -U postgres canteen_menu".
     volumes:
       - pgdata:/var/lib/postgresql/data
     restart: unless-stopped

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "canteen-menu",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "canteen-menu",
-      "version": "1.6.0",
+      "version": "1.6.1",
       "dependencies": {
         "@simplewebauthn/browser": "^13.3.0",
         "@simplewebauthn/server": "^13.3.2",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "canteen-menu",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "private": true,
   "scripts": {
     "predev": "node --env-file-if-exists=.env.local db/migrate.mjs && node --env-file-if-exists=.env.local scripts/bootstrap-admin.mjs",