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
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # Frontend Architecture & Modularization Strategy

 **Status:** DRAFT
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # Architektur: Das Platform-Modul

 ## Überblick
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # Repository-Architektur (MP-22)

 **WARNUNG (Januar 2026): Dieses Dokument ist veraltet.** Die hier beschriebene "Soll"-Struktur wurde teilweise umgesetzt, aber wichtige strategische Änderungen sind in den Statusberichten vom Januar 2026 dokumentiert. Dieses Dokument dient nur noch als historischer Referenzpunkt.
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # Open-Source-Konformität & Lizenz-Checkliste

 Dieses Dokument dient der Überwachung und Sicherstellung der Open-Source-Konformität des Projekts **Meldestelle**. Es wird vom Lead Architect gepflegt.
@@ -1,3 +1,8 @@
+---
+type: Guide
+status: ACTIVE
+owner: DevOps Engineer
+---
 # Enable Gitea Actions Cache to Accelerate CI/CD

 [![](/gitea-text.svg)Gitea](/)
@@ -1,3 +1,8 @@
+---
+type: Guide
+status: ACTIVE
+owner: DevOps Engineer
+---
 # 💻 Client-Setup: Arbeitsplatz an "Das Biest" anbinden

 Diese Anleitung beschreibt die Einrichtung eines lokalen Rechners, um via SSH und Cloudflare-Tunnel auf die
@@ -1,3 +1,8 @@
+---
+type: Guide
+status: ACTIVE
+owner: DevOps Engineer
+---
 # Technisches Referenzhandbuch: MS-R1 "Das Biest"

 ## 1. System-Übersicht & Architektur
@@ -1,5 +1,7 @@
 ---
-Betriebsanleitung Minisforum MS-R1
+type: Reference
+status: ARCHIVED
+owner: DevOps Engineer
 ---

 # MINISFORUM MS-R1
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: DevOps Engineer
+---
 # SSoT Konfigurations-Masterplan für Zora (ARM64)

 ## 1. System-Umgebung (Infrastruktur)
@@ -1,3 +1,8 @@
+---
+type: Guide
+status: ACTIVE
+owner: DevOps Engineer
+---
 # Setup Guide: Host OS (Minisforum MS-R1)

 **Status:** DEPRECATED / HISTORIC
@@ -1,3 +1,8 @@
+---
+type: Guide
+status: ACTIVE
+owner: DevOps Engineer
+---
 # Setup Guide: Infrastructure Services (Minisforum MS-R1)

 **Status:** DEPRECATED / HISTORIC
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: DevOps Engineer
+---
 # Spezifikation

 | CPU                  | CP8180, 12 Cores/12 Threads, 2.6Ghz                                                                                                                                                                                                                                                                                                                                                                                        |
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: DevOps Engineer
+---
 # Dokumentation: Zentrales Mail-Relay (SSoT) auf Zora

 ## 1. Identität & Rollenverteilung
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # Roadmap: Finalisierung Gitea-Infrastruktur (MS-R1)

 ## Phase 1: Konnektivität & Erreichbarkeit 🌐
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 Hier ist der Quellcode des Berichts im Markdown-Format:

 # Architektonische Resilienz in verteilten Systemen: Ein umfassender Leitfaden zur Implementierung von Offline-First Kotlin Multiplatform Architekturen mit SQLDelight
@@ -1,5 +1,7 @@
 ---
-Datenblatt USV
+type: Reference
+status: ACTIVE
+owner: DevOps Engineer
 ---
 # Eaton 3S

@@ -1,3 +1,8 @@
+---
+type: ADR
+status: DRAFT
+owner: Lead Architect
+---
 # PENDING DECISIONS: Backend Infrastructure & Architecture

 **Status:** RESOLVED
@@ -1,3 +1,8 @@
+---
+type: ADR
+status: ACTIVE
+owner: Lead Architect
+---
 # ADR-0000: Vorlage für Architekturentscheidungsaufzeichnungen

 ## Status
@@ -1,3 +1,8 @@
+---
+type: ADR
+status: ACTIVE
+owner: Lead Architect
+---
 # ADR-0001: Modulare Architektur

 ## Status
@@ -1,3 +1,8 @@
+---
+type: ADR
+status: ACTIVE
+owner: Lead Architect
+---
 # ADR-0002: Domain-Driven Design

 ## Status
@@ -1,3 +1,8 @@
+---
+type: ADR
+status: ACTIVE
+owner: Lead Architect
+---
 # ADR-0003: Microservices-Architektur

 ## Status
@@ -1,3 +1,8 @@
+---
+type: ADR
+status: ACTIVE
+owner: Lead Architect
+---
 # ADR-0004: Ereignisgesteuerte Kommunikation

 ## Status
@@ -1,3 +1,8 @@
+---
+type: ADR
+status: ACTIVE
+owner: Lead Architect
+---
 # ADR-0005: Polyglotte Persistenz

 ## Status
@@ -1,3 +1,8 @@
+---
+type: ADR
+status: ACTIVE
+owner: Lead Architect
+---
 # ADR-0006: Authentifizierung und Autorisierung mit Keycloak

 ## Status
@@ -1,3 +1,8 @@
+---
+type: ADR
+status: ACTIVE
+owner: Lead Architect
+---
 # ADR-0007: API-Gateway-Muster

 ## Status
@@ -1,3 +1,8 @@
+---
+type: ADR
+status: ACTIVE
+owner: Lead Architect
+---
 # ADR-0008: Multiplatform-Client-Anwendungen

 ## Status
@@ -1,3 +1,8 @@
+---
+type: ADR
+status: ACTIVE
+owner: Lead Architect
+---
 # ADR-0009: Final KMP Architecture

 Status: Accepted
@@ -1,3 +1,8 @@
+---
+type: ADR
+status: ACTIVE
+owner: Lead Architect
+---
 # ADR 001: Backend Infrastructure & Architecture Decisions

 **Status:** ACCEPTED
@@ -1,3 +1,8 @@
+---
+type: ADR
+status: ACTIVE
+owner: Lead Architect
+---
 # ADR-0010: SQLDelight für Cross-Platform-Persistenz

 ## Status
@@ -1,3 +1,8 @@
+---
+type: ADR
+status: ACTIVE
+owner: Lead Architect
+---
 # ADR-0011: Koin für Dependency Injection

 ## Status
@@ -1,3 +1,8 @@
+---
+type: ADR
+status: ACTIVE
+owner: Lead Architect
+---
 # ADR-0012: Strukturierung der Domänen-Dokumentation

 * **Status:** Accepted
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 Architecture Decision Records (ADRs)

 Dieses Verzeichnis enthält Architekturentscheidungen in kurzer, überprüfbarer Form.
@@ -1,3 +1,8 @@
+---
+type: Guide
+status: ACTIVE
+owner: Frontend Expert
+---
 # SQLDelight Integration in Compose Multiplatform

 This guide shows how to integrate SQLDelight in a Compose Multiplatform project with Koin dependency injection.
@@ -1,3 +1,8 @@
+---
+type: Guide
+status: ACTIVE
+owner: Frontend Expert
+---
 # Architekturstrategien für Asynchrone Persistenz in Kotlin Multiplatform: Eine umfassende Analyse zur Integration von SQLDelight in Web-Umgebungen

 ## 1. Einleitung und Problemstellung
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # Glossar der Domäne "Meldestelle"

 Dieses Dokument definiert die **Ubiquitous Language** (allgegenwärtige Sprache) des Projekts. Alle Begriffe sind so zu verwenden, wie sie hier definiert sind – sowohl im Code als auch in der Kommunikation.
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # 01 - Core Domain Entities

 Dieses Dokument definiert die zentralen fachlichen Entitäten (Kern-Entitäten) des "Meldestelle"-Projekts. Diese Entitäten bilden das Fundament des Datenmodells und der gesamten Anwendungslogik.
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # Entitäten des Kern-Modells

 Dieses Verzeichnis enthält detaillierte Beschreibungen der zentralen fachlichen Entitäten des "Meldestelle"-Projekts.
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # Das Kern-Modell (Core Model)

 Dieses Verzeichnis ist die "Single Source of Truth" für das destillierte, fachliche Wissen des Projekts. Nur was hier beschrieben ist, gilt als vereinbarte Wahrheit für die Implementierung.
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # Analyse der Legacy-Spezifikation (OEPS Pflichtenheft 2021 V2.4)

 *   **Datum:** 2026-01-14
@@ -1,3 +1,8 @@
+---
+type: ADR
+status: DRAFT
+owner: Lead Architect
+---
 # Non-Functional Requirements (NFRs) - Phase 1

 *   **Status:** Draft
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # Anekdote Meldestelle

 Ich bin diesmal die Meldestelle für ein kleines Turnier, z.B. ein "CDN-C Neu" bzw. "CSN-C Neu" am "Musterhof".
@@ -1,3 +1,8 @@
+---
+type: ADR
+status: DRAFT
+owner: Lead Architect
+---
 # Use Cases Draft - Phase 1 (Core Domain)

 *   **Status:** Draft
@@ -1,3 +1,8 @@
+---
+type: ADR
+status: DRAFT
+owner: Lead Architect
+---
 # User Stories Draft - Phase 1 (Core Domain)

 *   **Status:** Draft
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # Playbook: Lead Architect (System & Build)

 ## Beschreibung
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # Playbook: Senior Backend Developer (Spring Boot & DDD)

 ## Beschreibung
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # Playbook: Infrastructure & DevOps Engineer

 ## Beschreibung
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # Playbook: Domain/Product Expert (optional, Diskussion/Sparring)

 ## Beschreibung
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # Playbook: KMP Frontend Expert

 ## Beschreibung
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # Playbook: Gemini (parallel/extern)

 ## Zweck
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # Playbook: Junie (IDE)

 ## Zweck
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # Playbook: QA & Testing Specialist

 ## Beschreibung
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+---
 # Agent Operating Model (AOM)

 Dieses Verzeichnis definiert, **wie** KI-Unterstützung im Projekt eingesetzt wird:
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Backend Developer
+---
 # Backend Dokumentation

 Dieses Verzeichnis enthält die spezifische Dokumentation für alle Backend-Komponenten, einschließlich der Microservices und der Infrastruktur-Module wie dem API-Gateway.
@@ -1,3 +1,8 @@
+---
+type: Report
+status: ARCHIVED
+owner: Frontend Expert
+---
 # 🧹 Troubleshooting Log: Frontend Docker Build & Runtime Config

 **Datum:** 02.02.2026
@@ -1,3 +1,8 @@
+---
+type: Report
+status: ARCHIVED
+owner: Frontend Expert
+---
 # 🧹 Troubleshooting Log: Gradle 9.x & KMP Docker Build (Part 2)

 **Datum:** 02.02.2026
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: Frontend Expert
+---
 # Offline-First-Architektur

 Dieses Dokument beschreibt die **Zielarchitektur** für die Offline-First-Strategie im KMP-Frontend.
@@ -1,3 +1,8 @@
+---
+type: Guide
+status: ACTIVE
+owner: Frontend Expert
+---
 # Web-Setup (Webpack & Worker)

 Dieses Dokument beschreibt die spezifische Konfiguration für das Web-Target (JS/Wasm) des KMP-Frontends.
@@ -1,4 +1,8 @@
-
+---
+type: Reference
+status: ACTIVE
+owner: DevOps Engineer
+---
 #  Heimnetzwerk

 ```mermaid
@@ -1,5 +1,7 @@
 ---
-Konfigurations-Matrix
+type: Reference
+status: ACTIVE
+owner: DevOps Engineer
 ---
 # Konfigurations-Matrix

@@ -15,15 +17,17 @@ Konfigurations-Matrix
 | **POSTGRES_DB**                   | `meldestelle`                                       | `meldestelle`                                 | Name der primären Datenbank-Instanz.                                              |
 | **POSTGRES_PORT**                 | `5432:5432`                                         | `5432:5432`                                   | Mapping vom Host zum Container.                                                   |
 | **PROJECT_NAME**                  | `meldestelle`                                       | `meldestelle`                                 | Präfix für Container-Namen auf dem Host.                                          |
-| **KC_HOSTNAME**                   | `localhost`                                         | `auth.mo-code.at`                             | Erreichbarkeit von Keycloak (wichtig für Tokens).                                 |
+| **KC_HOSTNAME**                   | `localhost`                                         | `<SERVER_IP_ODER_DOMAIN>`                     | Erreichbarkeit von Keycloak (wichtig für Tokens). Auf dem Server nie `localhost`! |
 | **KC_DB_URL**                     | `jdbc:postgresql://postgres:5432/pg-meldestelle-db` | `jdbc:postgresql://postgres:5432/meldestelle` | JDBC-String (muss zur POSTGRES_DB passen).                                        |
 | **VALKEY_MAXMEMORY** 	            | `256mb`                                             | 	`4gb` bis `8gb`	                             | Zora hat 64 GB RAM; hier können wir großzügig cachen.                             |
 | **VALKEY_POLICY** 	               | `allkeys-lru`                                       | 	`allkeys-lru`	                               | Wirft die am längsten nicht genutzten Schlüssel raus, wenn der Speicher voll ist. |
 | **VALKEY_PASSWORD**               | `leer` oder `dev`	                                  | `[STARKES_SECRET]`                            | 	SSoT-Geheimnis aus Gitea-Secrets.                                                |
 | **VALKEY_PORT**                   | `6379:6379`                                         | 	`6379:6379`                                  | 	Standard-Port-Mapping.                                                           |
 | **KC_HEAP_MAX**                   | `1024m`                                             | `4096m`                                       | Mehr Power für Zoras 64 GB RAM.                                                   |
-| **KC_COMMAND**                    | `start-dev --import-realm`                          | `start --optimized`                           | Nutzt das im Dockerfile vor-gebaute Image.                                        |
-| **KC_HOSTNAME**                   | `localhost`                                         | `auth.mo-code.at`                             | Wichtig für gültige Tokens im Web-Frontend.                                       |
+| **KC_COMMAND**                    | `start-dev --import-realm`                          | `start --optimized --import-realm`            | `start-dev` + pre-built Image = Konflikt! Server immer mit `--optimized`.         |
+| **KC_HOSTNAME_STRICT**            | `false`                                             | `false`                                       | `false` = beliebige Hostnamen erlaubt (Pflicht für HTTP-only Betrieb).            |
+| **KC_HOSTNAME_STRICT_HTTPS**      | `false`                                             | `false`                                       | `false` = kein HTTPS-Zwang. Bei TLS-Einrichtung auf `true` setzen.               |
+| **KC_MANAGEMENT_PORT**            | `9000:9000`                                         | `9000:9000`                                   | Health/Metrics-Port (immer auf 0.0.0.0 gebunden, unabhängig von KC_HOSTNAME).     |
 | **KC_DB_PASSWORD**                | `meldestelle`                                       | `[GEHEIM]`                                    | SSoT-Passwort aus den Gitea-Secrets.                                              |
 | **KEYCLOAK_IMAGE_TAG**            | `26.4`                                              | `26.4`                                        | Versionierung.                                                                    |
 | **ZIPKIN_HEAP**                   | `256m`                                              | `1024m`                                       | Mehr Puffer für Tracing-Daten auf Zora.                                           |
@@ -1,5 +1,7 @@
 ---
-Pangolin vs. Cloudflare Tunnel
+type: Reference
+status: ACTIVE
+owner: DevOps Engineer
 ---

 ## 🛡️ Pangolin vs. Cloudflare Tunnel
@@ -1,6 +1,7 @@
 ---
-owner: project-maintainers
-status: active
+type: Reference
+owner: DevOps Engineer
+status: ACTIVE
 review_cycle: 180d
 last_reviewed: 2025-10-31
 summary: "Übersicht der wichtigsten lokalen URLs und Ports. Quelle: docker-compose.yaml + config/env"
@@ -1,3 +1,8 @@
+---
+type: Reference
+status: ACTIVE
+owner: DevOps Engineer
+---
 # Zipkin Tracing

 ## Übersicht
@@ -1,8 +1,7 @@
 ---
-
-Hier ist eine strategische Roadmap für den Ausbau des „Empires“ auf **Zora**. Da du aktuell im „Mo’s Territory“ bist, dient dieser Plan als Vorbereitung für deine nächste Session am Gerät.
-
-:white_check_mark:
+type: Reference
+status: ACTIVE
+owner: DevOps Engineer
 ---

 # Roadmap: Zora Infrastructure & Deployment (Februar 2026)
@@ -1,4 +1,8 @@
-
+---
+type: Reference
+status: ACTIVE
+owner: DevOps Engineer
+---
 ## 🏗️ System-Architektur "Zora" (ARM64)

 **Stand: 05. März 2026**
@@ -1,3 +1,8 @@
+---
+type: Guide
+status: ACTIVE
+owner: DevOps Engineer
+---
 # Runbook: Lokale Entwicklungsumgebung

 Dieses Dokument beschreibt, wie die Docker-basierte lokale Entwicklungsumgebung für das Projekt "Meldestelle" verwendet wird.
@@ -1,8 +1,10 @@
 ---
+type: Report
+status: ACTIVE
+owner: Frontend Expert
 title: Frontend Cleanup & Architecture Status Report
 date: 2026-02-01
 author: Frontend Expert & Curator
-status: Final
 tags: [frontend, architecture, cleanup, kmp, compose]
 ---

@@ -1,8 +1,9 @@
 ---
 type: Report
+status: ACTIVE
+owner: Curator
 date: 2026-02-01
 author: Curator
-status: FINAL
 ---

 # Report: Fix Sync Type Mismatch (String vs Long)
@@ -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.