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
@@ -49,7 +49,7 @@ SPRING_DATA_VALKEY_PORT=6379
 SPRING_DATA_VALKEY_PASSWORD=valkey-password

 # --- KEYCLOAK ---
-KEYCLOAK_IMAGE_TAG=26.5.5
+KEYCLOAK_IMAGE_TAG=latest
 KC_HEAP_MIN=512M
 KC_HEAP_MAX=1024M
 # Lokale Entwicklung: start-dev (kein Pre-Build nötig, kein --optimized)
@@ -64,7 +64,7 @@ KC_DB_PASSWORD=meldestelle
 KC_HOSTNAME=localhost
 # false = kein Hostname-Strict-Check (empfohlen für Entwicklung und HTTP-only Server)
 KC_HOSTNAME_STRICT=false
-KC_HOSTNAME_STRICT_HTTPS=false
+# KC_HOSTNAME_STRICT_HTTPS wurde entfernt — deprecated in Keycloak 26.x (hostname v2), wird ignoriert
 KC_PORT=8180:8080
 KC_MANAGEMENT_PORT=9000:9000

@@ -14,6 +14,11 @@ services:
    ports:
      - "${MAILPIT_WEB_PORT:-8025:8025}" # Web UI
      - "${MAILPIT_SMTP_PORT:-1025:1025}" # SMTP Port
+    healthcheck:
+      test: [ "CMD", "wget", "--spider", "-q", "http://localhost:8025/" ]
+      interval: 30s
+      timeout: 10s
+      retries: 3
    networks:
      meldestelle-network:

@@ -30,6 +35,11 @@ services:
      PGADMIN_DEFAULT_PASSWORD: "${PGADMIN_PASSWORD:-pgadmin}"
    volumes:
      - "pgadmin-data:/var/lib/pgadmin"
+    healthcheck:
+      test: [ "CMD", "wget", "--spider", "-q", "http://localhost:80/" ]
+      interval: 30s
+      timeout: 10s
+      retries: 3
    networks:
      meldestelle-network:
        aliases:
@@ -46,6 +56,11 @@ services:
    depends_on:
      postgres:
        condition: "service_healthy"
+    healthcheck:
+      test: [ "CMD", "wget", "--spider", "-q", "http://localhost:9187/metrics" ]
+      interval: 30s
+      timeout: 10s
+      retries: 3
    networks:
      meldestelle-network:
        aliases:
@@ -55,13 +70,18 @@ services:
  alertmanager:
    image: "${ALERTMANAGER_IMAGE:-prom/alertmanager:v0.29.0}"
    container_name: "${PROJECT_NAME:-meldestelle}-alertmanager"
-    restart: no
+    restart: unless-stopped
    ports:
      - "${ALERTMANAGER_PORT:-9093:9093}"
    volumes:
-      - ./config/docker/monitoring/alertmanager/alertmanager.yaml:/etc/alertmanager/alertmanager.yaml
+      - "./config/docker/monitoring/alertmanager/alertmanager.yaml:/etc/alertmanager/alertmanager.yaml:Z"
    command:
      - --config.file=/etc/alertmanager/alertmanager.yaml
+    healthcheck:
+      test: [ "CMD", "wget", "--spider", "-q", "http://localhost:9093/-/healthy" ]
+      interval: 30s
+      timeout: 10s
+      retries: 3
    profiles: [ "ops", "all" ]
    networks:
      meldestelle-network:
@@ -72,7 +92,7 @@ services:
  prometheus:
    image: "${PROMETHEUS_IMAGE:-prom/prometheus:v3.7.3}"
    container_name: "${PROJECT_NAME:-meldestelle}-prometheus"
-    restart: no
+    restart: unless-stopped
    ports:
      - "${PROMETHEUS_PORT:-9090:9090}"
    volumes:
@@ -99,7 +119,7 @@ services:
  grafana:
    image: "${GF_IMAGE:-grafana/grafana:12.3}"
    container_name: "${PROJECT_NAME:-meldestelle}-grafana"
-    restart: no
+    restart: unless-stopped
    environment:
      GF_SECURITY_ADMIN_USER: "${GF_ADMIN_USER:-gf-admin}"
      GF_SECURITY_ADMIN_PASSWORD: "${GF_ADMIN_PASSWORD:-gf-password}"
@@ -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 |