From b625bc208be514f143c81ebb34505006fe54c36b Mon Sep 17 00:00:00 2001
From: Pascal Scholz <p.scholz@larpaso.de>
Date: Mon, 21 Sep 2026 22:45:54 +0200
Subject: [PATCH] Fix B6/B7 in deploy guide: escape $ for docker compose
 env_file parsing

Docker Compose interpolates $VAR references within env_file values (not
just docker-compose.yml), so a raw bcrypt hash like $2a$12$... gets
partially swallowed as undefined variables - exactly the truncation
Pascal hit. Pipe hash-password.js output through `sed 's/\$/$$/g'` and
store the escaped hash; document the 63-char (60 + 3 escaped $) length
check to verify it went in correctly.
---
 DEPLOYMENT_ADMIN.md | 45 +++++++++++++++++++++++++++++++--------------
 1 file changed, 31 insertions(+), 14 deletions(-)

diff --git a/DEPLOYMENT_ADMIN.md b/DEPLOYMENT_ADMIN.md
index c0567cf..e9f3392 100644
--- a/DEPLOYMENT_ADMIN.md
+++ b/DEPLOYMENT_ADMIN.md
@@ -145,37 +145,54 @@ Jetzt mit dem gerade gebauten Image statt einem Wegwerf-Container – robuster a
 Ad-hoc-`npm install` (das kann mit dem bekannten npm-Fehler „Tracker 'idealTree' already
 exists" fehlschlagen):
 ```bash
-docker compose run --rm admin node admin/hash-password.js "dein-neues-passwort"
+docker compose run --rm admin node admin/hash-password.js "dein-neues-passwort" | sed 's/\$/$$/g'
 ```
-Gibt einen bcrypt-Hash aus (beginnt mit `$2a$` oder `$2b$`) – merken/kopieren.
-Zufälliges Session-Secret erzeugen:
+Gibt einen bcrypt-Hash aus, bei dem jedes `$` bereits verdoppelt ist (`$$2a$$12$$...`) –
+**genau so, mit den doppelten `$`, in B7 einfügen.** Docker Compose interpretiert einzelne
+`$` in `env_file`-Werten nämlich selbst als Variablen (siehe Warnung weiter unten, falls
+das schiefgeht) – `$$` ist Compose' eigene Escape-Regel dafür, kein Tippfehler.
+
+Zufälliges Session-Secret erzeugen (rein hexadezimal, kein `$` enthalten, keine
+Verdopplung nötig):
 ```bash
 docker compose run --rm admin node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
 ```
 Auch kopieren.
 
 **Optional – zweiten Benutzer anlegen** (z. B. für Lara): denselben Hash-Befehl nochmal
-mit ihrem Passwort ausführen und den Hash ebenfalls kopieren. Ein Session-Secret reicht
-für alle Benutzer, das muss nicht nochmal erzeugt werden.
+mit ihrem Passwort ausführen und den (verdoppelten) Hash ebenfalls kopieren. Ein
+Session-Secret reicht für alle Benutzer, das muss nicht nochmal erzeugt werden.
 ```bash
-docker compose run --rm admin node admin/hash-password.js "ihr-neues-passwort"
+docker compose run --rm admin node admin/hash-password.js "ihr-neues-passwort" | sed 's/\$/$$/g'
 ```
 
 ### B7. `~/stack/admin.env` mit echten Werten befüllen
+Am einfachsten mit `nano` (kein Heredoc nötig):
 ```bash
-cat > ~/stack/admin.env <<'EOF'
+nano ~/stack/admin.env
+```
+Inhalt (Beispiel – deine Werte aus B6 einsetzen, die Hashes **mit den doppelten `$`**
+genau so wie von `sed` ausgegeben, nicht die ursprüngliche, unverdoppelte Variante):
+```
 NODE_ENV=production
 ADMIN_USERNAME=pascal
-ADMIN_PASSWORD_HASH=<bcrypt-Hash aus B6 hier einfügen>
-SESSION_SECRET=<Hex-String aus B6 hier einfügen>
-EOF
-chmod 600 ~/stack/admin.env
+ADMIN_PASSWORD_HASH=$$2a$$12$$dein.eigentlicher.hash.hier
+SESSION_SECRET=dein-hex-string-hier
 ```
-**Nur falls du einen zweiten Benutzer angelegt hast:** vor dem `EOF` noch zwei weitere
-Zeilen einfügen (Muster lässt sich mit `_3`, `_4`, ... beliebig fortsetzen):
+**Nur falls du einen zweiten Benutzer angelegt hast**, zwei weitere Zeilen ergänzen
+(Muster lässt sich mit `_3`, `_4`, ... beliebig fortsetzen):
 ```
 ADMIN_USERNAME_2=lara
-ADMIN_PASSWORD_HASH_2=<zweiter Hash aus B6 hier einfügen>
+ADMIN_PASSWORD_HASH_2=$$2a$$12$$laras.hash.hier
+```
+Speichern: `Strg+O`, `Enter`, `Strg+X`. Danach:
+```bash
+chmod 600 ~/stack/admin.env
+```
+**Kontrolle** (jeder Hash muss inklusive der verdoppelten `$` **63 Zeichen** lang sein –
+60 für den eigentlichen bcrypt-Hash + 3 zusätzliche `$`):
+```bash
+grep HASH ~/stack/admin.env | awk -F= '{print $1": "length($2)" Zeichen"}'
 ```
 
 ### B8. DNS bei IONOS