meldestelle/docs/07_Infrastructure/runbooks/local-development.md

Runbook: Lokale Entwicklungsumgebung

Dieses Dokument beschreibt, wie die Docker-basierte lokale Entwicklungsumgebung für das Projekt "Meldestelle" verwendet wird.

1. Voraussetzungen

• Docker und Docker Compose müssen installiert sein.
• Eine .env-Datei muss im Projekt-Root vorhanden sein. Eine Vorlage befindet sich in .env.example.

2. Starten der Umgebung

Die Docker-Compose-Konfiguration verwendet Profile, um das Starten von verschiedenen Teilen des Systems zu ermöglichen.

2.1. Vollständiger Start (All-in-One)

Dieser Befehl startet alle definierten Services, einschließlich der Kerninfrastruktur, Backend-Services, Frontend und Monitoring-Tools.

docker-compose --profile all up --build -d

• --build: Baut die Images vor dem Start neu, falls Änderungen in den Dockerfiles oder im Quellcode vorliegen.
• -d: Startet die Container im "detached" Modus (im Hintergrund).

2.2. Nur Backend-Entwicklung

Wenn Sie nur an den Backend-Services arbeiten, können Sie die GUI- und Monitoring-Komponenten weglassen, um Ressourcen zu sparen.

docker-compose --profile backend --profile infra up --build -d

Dieser Befehl startet:

• Die Kerninfrastruktur (infra): postgres, redis, keycloak, consul.
• Alle Backend-Services (backend): api-gateway, ping-service, etc.

2.3. Nur Frontend-Entwicklung

Wenn Sie primär am Frontend arbeiten, benötigen Sie nur das API-Gateway und die Kerninfrastruktur.

docker-compose --profile gui --profile infra up --build -d

Dieser Befehl startet:

• Die Kerninfrastruktur (infra).
• Das api-gateway.
• Die web-app (Nginx-Server für das Frontend).

3. Stoppen der Umgebung

Um alle laufenden Container des Projekts zu stoppen:

docker-compose down

Um die Container zu stoppen und auch die benannten Volumes (Datenbankinhalte, etc.) zu löschen:

docker-compose down -v

4. Debugging eines Services

Alle Backend-Services sind so konfiguriert, dass sie im Debug-Modus gestartet werden können, wenn die Umgebungsvariable DEBUG=true gesetzt ist.

Beispiel: ping-service debuggen

1. Setzen der Umgebungsvariable: Öffnen Sie die docker-compose.yaml und finden Sie den ping-service. Fügen Sie unter environment die folgende Zeile hinzu oder passen Sie sie an:

   environment:
     # ... andere Variablen
     DEBUG: "true"
   

   Hinweis: In der docker-compose.yaml ist dies bereits über ${PING_DEBUG:-true} vorbereitet. Sie können also auch Ihre .env-Datei anpassen.

2. Port-Mapping: Der ping-service mappt den Debug-Port 5006 auf den Host.

3. Starten und Verbinden: Starten Sie die Umgebung neu (docker-compose up -d --build ping-service). Sie können nun einen Remote-Debugger Ihrer IDE mit dem Host localhost und dem Port 5006 verbinden.

5. Nützliche Endpunkte und Tools

Wenn die Umgebung mit dem all-Profil läuft, sind die folgenden Tools verfügbar:

• Keycloak Admin Console: http://localhost:8180
  • Login: kc-admin / kc-password (Standard, siehe .env)
• pgAdmin (Datenbank-Tool): http://localhost:8888
  • Login: meldestelle@mo-code.at / pgadmin (Standard, siehe .env)
• Grafana (Monitoring): http://localhost:3000
  • Login: gf-admin / gf-password (Standard, siehe .env)
• Consul UI (Service Discovery): http://localhost:8500
• API Gateway: http://localhost:8081
• Web App: http://localhost:4000
• Mailpit (E-Mail Testing): http://localhost:8025
  • Fängt alle E-Mails ab, die von Keycloak oder den Services gesendet werden.

6. Fortgeschrittene Anwendungsfälle: Override-Dateien

Im Projekt existieren leere Dateien wie docker-compose.frontend.yaml und docker-compose.services.yaml. Diese sind absichtlich leer und sollen nicht versioniert werden. Sie dienen als persönliche Override-Dateien für lokale Entwicklungsszenarien.

Zweck: Anstatt die zentrale docker-compose.yaml zu verändern, können Sie lokale Anpassungen in diesen Dateien vornehmen.

Beispiel: Frontend-Entwicklung mit Hot-Reload

Um Hot-Reload für die Nginx-Konfiguration zu aktivieren, können Sie die docker-compose.frontend.yaml mit folgendem Inhalt füllen:

# docker-compose.frontend.yaml
services:
  web-app:
    volumes:
      - ./config/docker/nginx/web-app/nginx.conf:/etc/nginx/nginx.conf:ro

Starten Sie die Umgebung dann mit beiden Dateien:

docker-compose -f docker-compose.yaml -f docker-compose.frontend.yaml up

Docker Compose wird die Konfigurationen zusammenführen, wobei die Definitionen in der docker-compose.frontend.yaml Vorrang haben.