Merge fix/bootstrap-admin-file-permission: Admin-Passwort nicht mehr verlieren bei EACCES

bootstrap-admin.mjs verliert das generierte Admin-Passwort nicht mehr,
wenn ZUGANGSDATEN.md nicht beschreibbar ist (Fallback: Log statt
Absturz nach erfolgreichem DB-Insert). DEPLOYMENT.md ergänzt um
chmod 666 in Schritt 2 sowie Fehlerbehebung für ECONNREFUSED und
diesen EACCES-Fall.

.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,44 @@ 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.2] – 2026-07-18
+
+### Behoben
+- `scripts/bootstrap-admin.mjs`: Konnte `ZUGANGSDATEN.md` nicht
+  geschrieben werden (z. B. `EACCES`, weil die per Bind-Mount
+  eingebundene Host-Datei root gehört und der App-Container als
+  nicht-root läuft), brach das Skript ab, nachdem der Admin-Benutzer
+  bereits in der Datenbank angelegt war – das generierte Passwort war
+  dann nirgends mehr zu finden. Schreibt jetzt bei einem Fehler
+  stattdessen E-Mail/Passwort ins Log und beendet sich weiterhin
+  erfolgreich.
+- DEPLOYMENT.md: Schritt 2 fehlte `chmod 666 ZUGANGSDATEN.md` (der
+  eigentliche Auslöser des Bugs oben). Neue Fehlerbehebung-Einträge für
+  `ECONNREFUSED` beim Start (harmlose Start-Reihenfolge, löst sich
+  durch den automatischen Neustart von selbst) und für diesen
+  `EACCES`-Fall inkl. Recovery-Anleitung für einen bereits verwaisten
+  Admin-Account.
+
+## [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>` |
@@ -51,14 +51,25 @@ Docker-Compose-Start ignoriert.
 
 Zusätzlich eine leere Datei für die automatisch generierten
 Admin-Zugangsdaten anlegen, da sie per Bind-Mount in den Container
-eingebunden wird:
+eingebunden wird. Der App-Container läuft als nicht-root-Nutzer –
+damit er die Datei beschreiben darf, muss sie für alle schreibbar sein:
 
 ```bash
 touch ZUGANGSDATEN.md
+chmod 666 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 +149,71 @@ 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
+```
+
+### `Error: connect ECONNREFUSED ...:5432` beim Start
+
+Normal beim allerersten Start: Der App-Container versucht sich zu
+verbinden, bevor PostgreSQL im `db`-Container fertig hochgefahren ist.
+Dank `restart: unless-stopped` startet der App-Container automatisch
+neu und verbindet sich, sobald die Datenbank bereit ist (kann ein paar
+Sekunden bis wenige Minuten dauern). Mit `docker compose logs app -f`
+verfolgen – taucht der Fehler dauerhaft (mehrere Minuten) weiter auf,
+`docker compose ps` prüfen, ob der `db`-Container tatsächlich dauerhaft
+läuft.
+
+### `EACCES: permission denied, open '/app/ZUGANGSDATEN.md'`
+
+Die Datei wurde ohne Schreibrecht für alle angelegt (Schritt 2 oben,
+`chmod 666` fehlte). Der Admin-Benutzer wurde in diesem Fall trotzdem
+in der Datenbank angelegt, nur die Zugangsdaten konnten nicht in die
+Datei geschrieben werden – sie stehen dann stattdessen im Log
+(`docker compose logs app` nach `bootstrap-admin – Admin-Passwort:`
+durchsuchen). Für zukünftige Deployments zusätzlich die Berechtigung
+korrigieren:
+
+```bash
+chmod 666 ZUGANGSDATEN.md
+```
+
+Falls das Passwort auch im Log nicht mehr auffindbar ist (z. B. weil
+Logs schon rotiert wurden), Admin-Konto neu anlegen lassen:
+
+```bash
+docker compose exec db psql -U postgres -d canteen_menu -c "delete from users;"
+chmod 666 ZUGANGSDATEN.md
+docker compose restart app
+docker compose logs app --tail 20
+cat ZUGANGSDATEN.md
+```
+
 ## 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.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "canteen-menu",
-      "version": "1.6.0",
+      "version": "1.6.2",
       "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.2",
   "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",

scripts/bootstrap-admin.mjs

@@ -58,19 +58,36 @@ async function main() {
       [email, passwordHash]
     );
 
+    // Der Admin-Datensatz steht ab hier in der Datenbank – das darf durch
+    // ein Problem beim Ablegen der Zugangsdaten nicht mehr verloren gehen
+    // (sonst gibt es einen Benutzer, dessen Passwort niemand kennt).
+    // appendFileSync() also bewusst nicht mehr ungefangen werfen lassen,
+    // sondern im Fehlerfall die Zugangsdaten direkt ins Log schreiben.
     const zugangsdatenPath = join(
       dirname(dirname(fileURLToPath(import.meta.url))),
       "ZUGANGSDATEN.md"
     );
     const entry = `\n## Admin-Zugang (automatisch angelegt, ${new Date().toISOString().slice(0, 10)})\n\n- E-Mail: \`${email}\`\n- Passwort: \`${password}\`\n\nBitte nach dem ersten Login ändern.\n`;
+    let wroteFile = false;
+    try {
       if (existsSync(zugangsdatenPath)) {
         appendFileSync(zugangsdatenPath, entry);
+        wroteFile = true;
+      }
+    } catch (err) {
+      console.warn(`bootstrap-admin – Konnte ${zugangsdatenPath} nicht beschreiben: ${err.message}`);
+    }
+
+    if (wroteFile) {
+      console.log(`bootstrap-admin – Admin angelegt: ${email} (Passwort siehe ZUGANGSDATEN.md)`);
     } else {
       console.warn(
-        `bootstrap-admin – ${zugangsdatenPath} existiert nicht, Zugangsdaten werden nur geloggt:`
+        `bootstrap-admin – ${zugangsdatenPath} existiert nicht oder ist nicht beschreibbar. ` +
+          `Zugangsdaten NUR HIER im Log, bitte sofort notieren:`
       );
+      console.log(`bootstrap-admin – Admin-E-Mail:   ${email}`);
+      console.log(`bootstrap-admin – Admin-Passwort: ${password}`);
     }
-    console.log(`bootstrap-admin – Admin angelegt: ${email} (Passwort siehe ZUGANGSDATEN.md)`);
   } finally {
     await client.end();
   }