meldestelle/docs/99_Journal/2026-01-13_backend-startup-troubleshooting.md

Journal: Inbetriebnahme Backend-Services

Datum: 2026-01-13 Beteiligte: Senior Backend Developer Ziel: Erfolgreicher Start des api-gateway und des ping-service in der Docker-Umgebung.

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.