docs: enhance local dev docs, update Docker Compose, and archive old journals

Added Mailpit setup and updated Keycloak configuration in local development runbooks. Improved Docker Compose stability with updated service dependencies and configurations. Archived outdated journal entries and documents for better organization.
2026-01-20 14:00:09 +01:00
parent 5dc8f18201
commit 46361185d0
56 changed files with 596 additions and 1832 deletions
@@ -1,46 +1,10 @@
-# Journal: Inbetriebnahme Backend-Services
+---
+type: Journal
+status: ARCHIVED
+owner: Backend Developer
+last_update: 2026-01-20
+---

-**Datum:** 2026-01-13
-**Beteiligte:** Senior Backend Developer
-**Ziel:** Erfolgreicher Start des `api-gateway` und des `ping-service` in der Docker-Umgebung.
+# Backend Troubleshooting (13.01.2026)

-## Zusammenfassung
-
-Beim Versuch, die Kern-Backend-Dienste über `docker compose up` zu starten, sind mehrere aufeinanderfolgende Build- und Konfigurationsfehler aufgetreten. Die Fehler deuten auf eine Desynchronisation zwischen der Projektstruktur, den Docker-Build-Skripten und den Spring-Cloud-Konfigurationen hin.
-
-Diese Sitzung konzentrierte sich auf die iterative Identifizierung und Behebung dieser Probleme.
-
-## Gelöste Probleme
-
-1.  **Fehlerhafte `COPY`-Anweisungen in Dockerfiles:**
-    *   **Problem:** Die Dockerfiles für `ping-service` und `api-gateway` enthielten veraltete `COPY`-Pfade, die auf eine alte Modulstruktur (`backend/services/ping/ping-api`) verwiesen. Dies führte zu "file not found"-Fehlern während des Docker-Builds.
-    *   **Lösung:** Die Pfade wurden korrigiert, um die aktuelle Projektstruktur (`contracts/ping-api`) widerzuspiegeln. Die relevanten Dockerfiles waren:
-        *   `backend/services/ping/Dockerfile`
-        *   `backend/infrastructure/gateway/Dockerfile`
-
-2.  **Tippfehler in Keycloak-Dockerfile:**
-    *   **Problem:** Ein Tippfehler im Pfad (`/opt/keykeycloak/` statt `/opt/keycloak/`) verhinderte den Build des Keycloak-Images.
-    *   **Lösung:** Der Pfad wurde in `config/docker/keycloak/Dockerfile` korrigiert.
-
-3.  **Parallele Gradle-Builds mit Cache-Konflikt:**
-    *   **Problem:** Der parallele Build von `api-gateway` und `ping-service` führte zu einem Lock-Konflikt im geteilten Gradle-Cache (`Timeout waiting to lock journal cache`).
-    *   **Lösung:** Die Dockerfiles wurden angepasst, um benannte und getrennte Cache-Mounts für jeden Service zu verwenden (`id=gradle-cache-ping` und `id=gradle-cache-gateway`), was den Konflikt behob.
-
-## Offene Probleme & Nächste Schritte
-
-Nach den oben genannten Korrekturen tritt nun ein neuer Fehler während des Starts des `api-gateway`-Containers auf:
-
-```
-java.lang.IllegalArgumentException: Unable to find GatewayFilterFactory with name CircuitBreaker
-```
-
-**Analyse:**
-*   Das Spring Cloud Gateway versucht, eine Route zu laden, die einen `CircuitBreaker`-Filter verwendet.
-*   Die notwendige `GatewayFilterFactory` für diesen Filter scheint zur Laufzeit nicht im Klassenpfad des Gateways verfügbar zu sein, obwohl die Abhängigkeit `spring-cloud-starter-circuitbreaker-resilience4j` in der `build.gradle.kts` deklariert ist.
-
-**Hypothese:**
-Das Problem liegt wahrscheinlich in der Konfiguration des Gateways. Eine der Konfigurationsquellen (vermutlich eine `.yaml`-Datei) definiert eine Route mit einem Circuit-Breaker-Filter, aber die dafür notwendige Spring-Cloud-Komponente wird nicht korrekt initialisiert.
-
-**Nächste Schritte:**
-1.  Die Konfigurationsquellen des `api-gateway` müssen systematisch analysiert werden, um die Stelle zu finden, an der die fehlerhafte `CircuitBreaker`-Filter-Route definiert wird.
-2.  Es muss sichergestellt werden, dass die korrekte Spring-Cloud-Abhängigkeit für den Resilience4j-Gateway-Filter im `api-gateway` vorhanden und korrekt konfiguriert ist.
+**MOVED:** This file has been archived to `_archive/2026-01-13_backend-startup-troubleshooting.md`.