docs: document Keycloak hostname fix, session log analysis, and healthcheck updates

- Added detailed session log (2026-03-10) to document Keycloak hostname root cause and resolution, Git push network issue analysis, and Alertmanager permission fix. - Updated `.env` to fix Keycloak hostname configuration (`KC_HOSTNAME`) and remove deprecated `KC_HOSTNAME_STRICT_HTTPS`. - Enhanced Docker Compose healthchecks for multiple services (e.g., Mailpit, PgAdmin, Alertmanager). Signed-off-by: Stefan Mogeritsch <stefan.mo.co@gmail.com>
2026-03-10 12:51:46 +01:00
parent e8b5569893
commit 4da1306e0e
7 changed files with 188 additions and 6 deletions
@@ -0,0 +1,162 @@
+# Session Log — 2026-03-10: Keycloak Hostname Fix & Git Push Analyse
+
+**Datum:** Di. 10. März 2026  
+**Agent:** 🧹 Curator / 👷 Backend Developer  
+**Kontext:** Folge-Session zu Keycloak-Härtung vom 09.03.2026
+
+---
+
+## Übersicht
+
+| # | Problem                                                          | Status                          |
+|---|------------------------------------------------------------------|---------------------------------|
+| 1 | Git Push fehlgeschlagen                                          | ✅ Analysiert (Netzwerkfehler)   |
+| 2 | Keycloak Admin-Dashboard auf `meldestelle-host` nicht erreichbar | ✅ Root Cause + Fix dokumentiert |
+| 3 | Alertmanager Permission-Fehler                                   | ✅ Identifiziert                 |
+
+---
+
+## Problem 1: Git Push fehlgeschlagen
+
+**Zeitpunkt:** 2026-03-09 ~15:50 (aus Vortagslogs)
+
+### Symptom
+
+```
+fatal: unable to access 'https://git.mo-code.at/mocode-software/meldestelle/'
+Failed to connect to git.mo-code.at port 443 after 133648 ms: Could not connect to server
+```
+
+### Analyse
+
+Zwei separate Ereignisse wurden fälschlicherweise als ein Problem wahrgenommen:
+
+1. **15:50 — Push rejected** (`fetch first`): Normaler Git-Fehler, Remote hatte neue Commits.
+  - Korrekt gelöst durch: `fetch` + `rebase` → `Successfully rebased and updated refs/heads/main`
+2. **15:51 — Push nach Rebase fehlgeschlagen**: Netzwerkfehler — `git.mo-code.at:443` war nicht erreichbar (
+   Pangolin-Tunnel kurzzeitig down).
+
+### Lösung
+
+Kein Code-Fix nötig. Sobald der Server wieder erreichbar ist:
+
+```bash
+curl -I https://git.mo-code.at   # Erreichbarkeit prüfen
+git push origin main              # Einfach erneut pushen
+```
+
+### Gelernt
+
+> Der Rebase war korrekt und vollständig. Kein `--force`, kein `git reset` nötig.
+> Pangolin-Tunnel-Ausfälle sind transient — immer zuerst Netzwerk prüfen, bevor Git-Befehle wiederholt werden.
+
+---
+
+## Problem 2: Keycloak Admin-Dashboard auf `meldestelle-host` nicht erreichbar
+
+**Zeitpunkt:** 2026-03-10 ~10:17
+
+### Symptom
+
+- Lokal (`localhost:8180/admin`): ✅ funktioniert
+- Auf `meldestelle-host` (`10.0.0.50:8180/admin`): ❌ nicht erreichbar
+- Management-Port (`10.0.0.50:9000`): ✅ erreichbar
+
+### Root Cause: `KC_HOSTNAME` ohne Port
+
+In der `.env` auf `meldestelle-host`:
+
+```env
+KC_HOSTNAME=10.0.0.50   # ← Port fehlt!
+```
+
+Keycloak 26.x (hostname v2) interpretiert `KC_HOSTNAME` als kanonische Basis-URL.
+Ohne Port-Angabe erwartet Keycloak Requests auf Port **80** (HTTP-Standard).
+Der tatsächliche Host-Port ist aber **8180** → Mismatch → Admin-Interface antwortet nicht.
+
+**Warum Port 9000 funktioniert:**
+Der Management-Port (`KC_HTTP_MANAGEMENT_PORT=9000`) ist **nicht** an `KC_HOSTNAME` gebunden
+und antwortet unabhängig vom Hostname-Mapping immer.
+
+**Warum lokal alles funktioniert:**
+
+```env
+KC_HOSTNAME=localhost   # Port 8180 → Container-intern 8080 → passt
+```
+
+`localhost` ohne Port funktioniert, weil der Browser/curl den Port aus der URL übernimmt
+und Keycloak bei `KC_HOSTNAME_STRICT=false` toleranter ist.
+
+### Zusätzliches Problem: Deprecated Variable
+
+```env
+KC_HOSTNAME_STRICT_HTTPS=false   # deprecated seit Keycloak 26.x (hostname v2)
+```
+
+Diese Variable wird in Keycloak 26.x ignoriert — kann zu unerwartetem Verhalten führen.
+
+### Fix für `.env` auf `meldestelle-host`
+
+```env
+# VORHER:
+KC_HOSTNAME=10.0.0.50
+KC_HOSTNAME_STRICT=false
+KC_HOSTNAME_STRICT_HTTPS=false   # deprecated
+
+# NACHHER:
+KC_HOSTNAME=10.0.0.50:8180
+KC_HOSTNAME_STRICT=false
+# KC_HOSTNAME_STRICT_HTTPS entfernt (deprecated in Keycloak 26.x)
+```
+
+### Anwendung des Fixes
+
+```bash
+# Auf meldestelle-host:
+nano .env
+# KC_HOSTNAME=10.0.0.50  →  KC_HOSTNAME=10.0.0.50:8180
+# KC_HOSTNAME_STRICT_HTTPS=false  →  Zeile entfernen
+
+docker compose -f dc-infra.yaml up -d keycloak
+
+# Test nach ~30s:
+curl -s http://10.0.0.50:8180/admin/
+```
+
+### Gelernt
+
+> `KC_HOSTNAME` in Keycloak 26.x (hostname v2) muss den **vollständigen** Hostnamen inkl. Port
+> enthalten, wenn kein Standard-Port (80/443) verwendet wird.
+> `KC_HOSTNAME_STRICT_HTTPS` ist seit Keycloak 26.x deprecated und sollte aus allen `.env`-Dateien
+> entfernt werden — es wird stillschweigend ignoriert.
+
+---
+
+## Problem 3: Alertmanager Permission-Fehler (Nebenbefund)
+
+### Symptom (aus Docker-Logs)
+
+```
+err="open /etc/alertmanager/alertmanager.yaml: permission denied"
+```
+
+### Root Cause
+
+Die `alertmanager.yaml` auf dem Host hat falsche Dateiberechtigungen.
+
+### Fix
+
+```bash
+chmod 644 config/docker/alertmanager/alertmanager.yaml
+docker compose -f dc-ops.yaml restart alertmanager
+```
+
+---
+
+## Offene Punkte
+
+| Punkt                                 | Priorität  | Beschreibung                                           |
+|---------------------------------------|------------|--------------------------------------------------------|
+| Keycloak Hostname Fix anwenden        | 🔴 Hoch    | `.env` auf `meldestelle-host` korrigieren              |
+| Alertmanager Permission Fix           | 🟡 Mittel  | `chmod 644` auf alertmanager.yaml                      |
+| `KC_HOSTNAME_STRICT_HTTPS` bereinigen | 🟢 Niedrig | Deprecated Variable aus allen `.env`-Dateien entfernen |