infra: clean up Keycloak configuration, enforce consistency in .env, and improve health checks

Streamlined Keycloak configurations with defaults for development and production in `.env`. Added health checks and improved environment variable documentation with comments to differentiate local and server deployments. Ensured compatibility with pre-built registry images.
2026-03-06 11:23:24 +01:00
parent 6cb1f2d5ba
commit 09b0b1a462
75 changed files with 441 additions and 44 deletions
@@ -0,0 +1,37 @@
+# Journal - 2026-03-06
+
+## 📝 Zusammenfassung
+Keycloak funktionierte lokal einwandfrei, aber auf dem Meldestellen-Host war das Admin-Dashboard (`:8180`) nicht erreichbar und der Login schlug fehl — obwohl der Health-Port (`:9000`) grün war. Root Cause: Das pre-built Registry-Image wurde mit `start-dev` gestartet (Konflikt) und `KC_HOSTNAME=localhost` war auf dem Server falsch.
+
+## 🛠️ Änderungen
+
+### 1. `dc-infra.yaml` — Keycloak-Service bereinigt
+*   **Command:** `start-dev --import-realm` → `start --optimized --import-realm` (nutzt das pre-built Image korrekt).
+*   **Neu:** `KC_HOSTNAME_STRICT=false` und `KC_HOSTNAME_STRICT_HTTPS=false` — erlaubt HTTP-Betrieb ohne TLS-Zwang.
+*   **Neu:** `KC_HTTP_MANAGEMENT_PORT=9000` — Management-Interface explizit konfiguriert.
+*   **Fix:** `KC_DEBUG_PORT` → `KC_MANAGEMENT_PORT` umbenannt (war falsch benannt).
+*   **Fix:** Image-Pfad von `grandmo` → `mocode-software` korrigiert.
+*   **Neu:** Healthcheck auf `http://localhost:9000/health/ready` ergänzt.
+
+### 2. `.env` — Keycloak-Block erweitert
+*   `KC_HOSTNAME_STRICT=false`, `KC_HOSTNAME_STRICT_HTTPS=false`, `KC_MANAGEMENT_PORT=9000:9000` hinzugefügt.
+*   Erklärende Kommentare: LOKAL vs. SERVER für `KC_COMMAND` und `KC_HOSTNAME`.
+
+### 3. `.env.example` — Als Server-Vorlage optimiert
+*   Default `KC_COMMAND=start --optimized --import-realm` (Server-Default).
+*   `<PLACEHOLDER>`-Werte für alle Secrets (`KC_ADMIN_PASSWORD`, `KC_DB_PASSWORD`) und `KC_HOSTNAME`.
+*   `SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI` mit `<SERVER_IP_ODER_DOMAIN>`-Platzhalter.
+*   Klare LOKAL/SERVER-Kommentare bei allen kritischen Variablen.
+
+## 📚 Gelerntes
+*   **`kc.sh build` + `start-dev` = Konflikt:** Ein mit `kc.sh build` optimiertes Image muss mit `start --optimized` gestartet werden. `start-dev` ignoriert den Pre-Build und startet im Dev-Modus — das bricht das Registry-Image auf dem Server.
+*   **`KC_HOSTNAME` steuert den HTTP-Port, nicht den Management-Port:** Port `9000` (Health) ist immer auf `0.0.0.0` gebunden. Port `8080/8180` (HTTP) wird durch `KC_HOSTNAME` gesteuert — daher war Health grün, aber Admin-Dashboard nicht erreichbar.
+*   **`KC_HOSTNAME_STRICT=false` ist Pflicht für HTTP-only Server:** Ohne dieses Flag lehnt Keycloak alle Requests ab, deren Host-Header nicht exakt mit `KC_HOSTNAME` übereinstimmt.
+
+## 🔜 Nächste Schritte
+*   Auf dem Meldestellen-Host die `.env` anpassen:
+    *   `KC_HOSTNAME=<SERVER_IP>`
+    *   `KC_COMMAND=start --optimized --import-realm`
+    *   `SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI=http://<SERVER_IP>:8180/realms/meldestelle`
+*   Container neu starten und Admin-Dashboard + Login verifizieren.
+*   Langfristig: TLS/HTTPS einrichten, dann `KC_HOSTNAME_STRICT_HTTPS=true` setzen.