Dieses Runbook ist der zentrale Betriebszugang. Es ersetzt nicht die Einzel-Runbooks, sondern konsolidiert sie. Die Einzeldateien bleiben als Details erhalten.

Regel 1

Immer zuerst docker compose ps und die Logs prüfen.

Regel 2

Bei fachlichen Fehlern immer REST, DB, Outbox und Broker gemeinsam prüfen.

Regel 3

401 bedeutet Tokenproblem. 403 bedeutet Rollenproblem.

cd 04_PROJEKT
docker compose ps
docker compose logs --tail=100 postgres rabbitmq keycloak wiremock prometheus grafana

01. Lokaler Start und Container-Probleme

Fehlerbild

Container starten nicht, Ports sind belegt oder ein Service bleibt unhealthy.

Sofortcheck

cd 04_PROJEKT
docker compose ps
docker compose logs --tail=120 postgres rabbitmq keycloak wiremock

Diagnose

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
docker compose config
docker compose down
docker compose up -d
docker compose ps

Erwartete Ausgabe / Interpretation

Alle Container sollten `Up` sein. PostgreSQL und RabbitMQ haben Healthchecks. Keycloak braucht lokal länger, deshalb zuerst Discovery/Logs prüfen.

Lösung

Portkonflikte lösen, alte Container entfernen, dann Stack sauber neu starten. Bei Keycloak Geduld und Logs prüfen; Realm Import muss sichtbar sein.

Relevante Dateien

02. Maven Build und Modulgrenzen

Fehlerbild

Build bricht ab, Module werden nicht gefunden oder Tests schlagen an falscher Stelle fehl.

Sofortcheck

cd 04_PROJEKT/maven-project
mvn -q -DskipTests package
mvn -pl runtime -am test

Diagnose

mvn -q help:effective-pom -DskipTests
mvn -q -DskipTests dependency:tree
mvn -pl integration-tests -am verify

Erwartete Ausgabe / Interpretation

Root-POM muss alle Module enthalten. Domain darf keine Infrastrukturabhängigkeiten haben. Integrationstests laufen über Failsafe mit `*IT.java`.

Lösung

Fehlende Modulabhängigkeit im passenden POM ergänzen. Infrastruktur nicht in Domain/Application verschieben, sondern Adapter/Runtime nutzen.

Relevante Dateien

03. REST Flow Bestellung annehmen

Fehlerbild

REST Call liefert Fehler oder Bestellung erscheint nicht in der Datenbank.

Sofortcheck

curl -i -X POST http://localhost:8080/api/orders/ORD-RB-100/accept

Diagnose

curl -fsS http://localhost:8080/actuator/health
docker compose logs --tail=100 runtime
docker compose exec postgres psql -U order_user -d orderdb -c "select * from order_platform.orders order by created_at desc limit 5;"

Erwartete Ausgabe / Interpretation

Bei aktivierter Security brauchst du einen Bearer Token. Ohne Security-Bypass ist 401 erwartbar. Nach erfolgreichem POST muss ein Order-Datensatz sichtbar sein.

Lösung

Token über Keycloak holen oder Security-Testscript nutzen. Danach DB und Outbox gemeinsam prüfen.

Relevante Dateien

04. PostgreSQL, Flyway und Datenbankbetrieb

Fehlerbild

Tabellen fehlen, Migration schlägt fehl, Seed-Daten fehlen oder Restore ist unklar.

Sofortcheck

cd 04_PROJEKT
docker compose exec postgres psql -U order_user -d orderdb -c "\dn"
docker compose exec postgres psql -U order_user -d orderdb -c "select * from flyway_schema_history order by installed_rank;"

Diagnose

docker compose exec postgres psql -U order_user -d orderdb -c "select count(*) from order_platform.orders;"
docker compose exec postgres psql -U order_user -d orderdb -c "select status, count(*) from outbox.events group by status;"
./scripts/database/check-flyway-history.sh
./scripts/database/check-outbox-backlog.sh

Erwartete Ausgabe / Interpretation

Schemas `order_platform` und `outbox` müssen existieren. Flyway History muss erfolgreiche Einträge zeigen. Outbox Backlog darf nicht unkontrolliert wachsen.

Lösung

Bei Migrationen zuerst History prüfen. Keine manuelle Tabellen-Reparatur ohne Runbook. Für Backup/Restore die Scripts verwenden.

Relevante Dateien

05. Outbox bleibt auf NEW

Fehlerbild

Bestellung ist gespeichert, aber Outbox Events bleiben auf `NEW` und werden nicht veröffentlicht.

Sofortcheck

docker compose exec postgres psql -U order_user -d orderdb -c "select event_id,event_type,status,created_at,published_at from outbox.events order by event_id desc limit 20;"

Diagnose

docker compose logs --tail=200 runtime | grep -i -E "outbox|rabbit|publish|error"
curl -fsS http://localhost:8080/actuator/health
curl -fsS http://localhost:8080/actuator/prometheus | grep -i outbox

Erwartete Ausgabe / Interpretation

`OutboxRelayJob` läuft per Scheduler. Nach erfolgreichem Publish wechselt Status auf `PUBLISHED`. Bei Brokerfehler kann Status `FAILED` werden.

Lösung

Runtime prüfen, Scheduler prüfen, RabbitMQ erreichbar machen. Danach Event erneut erzeugen oder für Laborzwecke Status kontrolliert zurücksetzen.

Relevante Dateien

06. RabbitMQ Queue leer oder Consumer reagiert nicht

Fehlerbild

Outbox ist PUBLISHED, aber in RabbitMQ ist keine Nachricht sichtbar oder Billing Consumer loggt nichts.

Sofortcheck

curl -u order_user:order_pass http://localhost:15672/api/queues/%2F/billing.order-accepted
docker compose logs --tail=200 rabbitmq runtime

Diagnose

curl -u order_user:order_pass http://localhost:15672/api/exchanges/%2F/order.events
curl -u order_user:order_pass http://localhost:15672/api/bindings/%2F/e/order.events/q/billing.order-accepted

Erwartete Ausgabe / Interpretation

Exchange `order.events`, Queue `billing.order-accepted` und Routing Key `order.accepted` müssen zusammenpassen.

Lösung

RabbitMQ Definitions laden lassen, Routing Key im Relay prüfen, Consumer-Annotation prüfen, Runtime neu starten.

Relevante Dateien

07. WireMock Payment Provider

Fehlerbild

Payment-Autorisierung schlägt fehl, WireMock antwortet nicht oder Mapping passt nicht.

Sofortcheck

curl -fsS http://localhost:8089/__admin/mappings
curl -i -X POST http://localhost:8089/payment/authorize -H "Content-Type: application/json" -d "{"orderId":"ORD-RB","amount":"19.90"}"

Diagnose

docker compose logs --tail=100 wiremock
curl -fsS http://localhost:8089/__admin/requests

Erwartete Ausgabe / Interpretation

WireMock muss Mapping `/payment/authorize` kennen und JSON mit `AUTHORIZED` liefern.

Lösung

Mapping-Datei prüfen, Container neu starten, Request Body und URL exakt prüfen.

Relevante Dateien

08. Keycloak 401 / 403 Diagnose

Fehlerbild

API liefert 401 oder 403. Benutzer versteht nicht, ob Token oder Rolle fehlt.

Sofortcheck

./scripts/security/get-keycloak-token.sh order-admin admin
./scripts/security/call-secured-order-flow.sh

Diagnose

curl -fsS http://localhost:8082/realms/order-platform/.well-known/openid-configuration
docker compose logs --tail=150 keycloak
TOKEN=$(./scripts/security/get-keycloak-token.sh order-reader reader | python -c "import sys,json; print(json.load(sys.stdin).get('access_token',''))")
echo "$TOKEN" | cut -d. -f2

Erwartete Ausgabe / Interpretation

401 = kein gültiger Token oder Issuer/Signatur falsch. 403 = Token gültig, aber Rolle reicht nicht.

Lösung

Realm Import prüfen, `realm_access.roles` prüfen, Converter `RealmRoleJwtAuthenticationConverter` prüfen, Endpunktregel prüfen.

Relevante Dateien

09. Observability: Prometheus und Grafana zeigen keine Daten

Fehlerbild

Grafana ist leer, Prometheus scraped nicht oder Metriken fehlen.

Sofortcheck

curl -fsS http://localhost:8080/actuator/prometheus | head
curl -fsS http://localhost:9090/api/v1/targets | python -m json.tool

Diagnose

docker compose logs --tail=100 prometheus grafana
curl -fsS http://localhost:8080/actuator/health
curl -fsS http://localhost:8080/actuator/prometheus | grep -E "http_server|outbox|resilience"

Erwartete Ausgabe / Interpretation

Prometheus Target muss UP sein. Runtime muss `/actuator/prometheus` bereitstellen. Grafana Datasource muss auf Prometheus zeigen.

Lösung

Actuator Exposure prüfen, Prometheus Config prüfen, Container-Netzwerk/host.docker.internal prüfen, Grafana Datasource reloaden.

Relevante Dateien

10. Resilience: Timeout, Retry, Circuit Breaker

Fehlerbild

Payment Provider ist langsam/fehlerhaft und Runtime reagiert instabil.

Sofortcheck

./scripts/resilience/call-payment-flow-repeatedly.sh
./scripts/resilience/check-resilience-metrics.sh

Diagnose

curl -fsS http://localhost:8080/actuator/prometheus | grep resilience4j
docker compose logs --tail=200 runtime | grep -i -E "timeout|retry|circuit|bulkhead|payment"

Erwartete Ausgabe / Interpretation

Bei wiederholten Providerfehlern müssen Retry/Circuit-Breaker-Metriken sichtbar werden. Fehlerantworten sollen stabil bleiben.

Lösung

WireMock Fehlerfall aktivieren, Resilience4j-Konfiguration prüfen, Timeouts passend setzen, Bulkhead nicht überdimensionieren.

Relevante Dateien

11. Testcontainers und E2E Tests

Fehlerbild

Integrationstests starten nicht, Docker fehlt oder Failsafe findet Tests nicht.

Sofortcheck

./scripts/tests/run-phase4-e2e.sh

Diagnose

cd 04_PROJEKT/maven-project
mvn -pl integration-tests -am verify
docker ps
docker logs $(docker ps -q --filter ancestor=postgres:16-alpine | head -1)

Erwartete Ausgabe / Interpretation

`*IT.java` Tests werden durch Failsafe ausgeführt. Docker muss laufen. Testcontainers zieht Images bei Bedarf.

Lösung

Docker Engine starten, Failsafe-Konfiguration prüfen, Testklassen nach `*IT.java` benennen.

Relevante Dateien

12. CI/CD und Quality Gates

Fehlerbild

Pipeline bricht ab, SBOM/Lizenzprüfung fehlt oder Docker Build läuft lokal nicht.

Sofortcheck

./scripts/quality/run-quality-gates.sh

Diagnose

cd 04_PROJEKT/maven-project
mvn verify
cd ..
./scripts/quality/check-release-package.sh
sed -n "1,220p" .github/workflows/ci.yml

Erwartete Ausgabe / Interpretation

Quality Gates prüfen Build, Tests, SBOM, Lizenzbericht, Docker Build und Release-Struktur.

Lösung

Fehler nach Gate trennen: Build/Tests zuerst, danach SBOM/Lizenzen, danach Docker/Release. Nie alles gleichzeitig reparieren.

Relevante Dateien

13. Deployment: Docker, Kubernetes, OpenShift, Helm

Fehlerbild

Container Image baut nicht, Kustomize rendert fehlerhaft oder Pod startet nicht.

Sofortcheck

./scripts/deploy/build-runtime-image.sh
./scripts/deploy/check-deployment.sh

Diagnose

kubectl kustomize deployment/kubernetes/base
kubectl kustomize deployment/kubernetes/overlays/local
helm template order-runtime deployment/helm/order-runtime
kubectl describe pod -n order-platform
kubectl logs -n order-platform deploy/order-runtime

Erwartete Ausgabe / Interpretation

Manifeste müssen rendern. Deployment braucht Config, Secret, Service und Health Probes.

Lösung

Image/Tag, ConfigMap, Secret, Probes und Security Context prüfen. Bei OpenShift Route/SCC-Patches beachten.

Relevante Dateien

14. Backup, Restore und Datenrettung

Fehlerbild

Daten sollen gesichert oder wiederhergestellt werden. Risiko: falsche DB oder unvollständige Sicherung.

Sofortcheck

./scripts/database/backup-postgres.sh

Diagnose

ls -lh backups/
./scripts/database/check-flyway-history.sh
./scripts/database/check-outbox-backlog.sh

Erwartete Ausgabe / Interpretation

Backup-Datei muss vorhanden und plausibel groß sein. Vor Restore immer Zielumgebung und DB-Name prüfen.

Lösung

Restore nur bewusst ausführen. Danach Flyway History, Orders und Outbox prüfen.

Relevante Dateien

15. Incident Response und Produktionsreife

Fehlerbild

Ein Fehler betrifft mehrere Systeme: API, DB, Broker, Security oder Observability.

Sofortcheck

date
docker compose ps
docker compose logs --tail=200 > incident-logs.txt
./scripts/operations/dr-smoke-check.sh

Diagnose

curl -i http://localhost:8080/actuator/health
curl -fsS http://localhost:9090/api/v1/alerts | python -m json.tool
docker compose exec postgres psql -U order_user -d orderdb -c "select status,count(*) from outbox.events group by status;"

Erwartete Ausgabe / Interpretation

Incident-Diagnose muss Zustand sichern, betroffene Komponente isolieren, Kundenwirkung einschätzen und Wiederherstellungsschritt dokumentieren.

Lösung

Nicht blind neu starten. Erst Zustand erfassen, dann kleinsten wirksamen Fix anwenden, danach Postmortem und Runbook verbessern.

Relevante Dateien

16. Einzel-Runbooks bleiben erhalten

Dieses Master-Runbook fasst zusammen. Die ursprünglichen Einzel-Runbooks bleiben verlinkt:

Thema	Datei
Lokaler Start	docs/runbooks/local-start.html
Outbox/RabbitMQ	docs/runbooks/outbox-rabbitmq-flow.html
Keycloak	docs/runbooks/keycloak-security-flow.html
E2E Tests	docs/runbooks/phase4-e2e-tests.html
Observability	docs/runbooks/observability-runbook.html
Resilience	docs/runbooks/phase6-resilience.html
CI/CD	docs/runbooks/phase7-ci-cd-quality-gates.html
Deployment	docs/runbooks/phase8-deployment.html
Backup/Restore	docs/runbooks/database-backup-restore.html
Incident Response	docs/runbooks/incident-response.html