# Journal: Consul-Service-Discovery & Healthcheck Refactoring

**Datum:** 16. April 2026
**Agent:** 🏗️ [Lead Architect] & 👷 [Backend Developer]

## 1. Problemstellung

Obwohl die Services (`masterdata-service`, `events-service`, etc.) in Docker korrekt starteten und Actuator-Endpunkte
lokal erreichbar waren, meldete Consul "All service checks failing".

### Ursachen-Analyse:

1. **Port-Konflikt bei Mischbetrieb:** Services wie `masterdata-service` nutzen sowohl Spring Boot (Management/Actuator
   auf Port 8086) als auch Ktor (API auf Port 8091). Ohne explizite Angabe versuchte Consul teilweise den Ktor-Port für
   den Healthcheck zu nutzen.
2. **Docker-Networking:** In Docker-Umgebungen muss `prefer-ip-address: true` gesetzt sein, damit Consul die interne
   Container-IP registriert und nicht den (oft nicht auflösbaren) Hostnamen.
3. **Inkonsistente Konfiguration:** Die `instance-id` und `health-check-port` Definitionen unterschieden sich zwischen
   den Services.

## 2. Durchgeführte Änderungen

Alle Backend-Services (11 insgesamt) wurden auf eine einheitliche Consul-Konfiguration umgestellt.

### Zentrale Konfigurations-Änderungen (`application.yml`):

```yaml
spring:
  cloud:
    consul:
      discovery:
        enabled: true
        register: true
        prefer-ip-address: true
        health-check-path: /actuator/health
        health-check-interval: 10s
        health-check-port: ${server.port} # Explizite Nutzung des Tomcat/Management Ports
        instance-id: ${spring.application.name}:${server.port}:${random.uuid}
        service-name: ${spring.application.name}
```

### Betroffene Services:

- `api-gateway`
- `masterdata-service` (Ktor/Spring Mischbetrieb)
- `events-service`
- `ping-service`
- `zns-import-service`
- `billing-service`
- `entries-service`
- `identity-service`
- `mail-service`
- `results-service`
- `scheduling-service`
- `series-service`

## 3. Ergebnis

- Alle Services registrieren sich nun konsistent im Consul.
- Der Healthcheck erfolgt explizit über den Management-Port (Spring Boot Tomcat), unabhängig vom API-Port.
- Die Erreichbarkeit im Docker-Netzwerk ist durch IP-basierte Registrierung sichergestellt.
- Das API-Gateway kann nun zuverlässig auf alle Services via Service Discovery routen.

---
**🏗️ [Lead Architect]**: Infrastruktur-Vorgabe für Service-Discovery vereinheitlicht.
**👷 [Backend Developer]**: Alle 11 Microservices erfolgreich auf den neuen Standard migriert.