From 0335de7654ef513c74fc6b931c6d3da28ae11e0b Mon Sep 17 00:00:00 2001 From: Stefan Mogeritsch Date: Tue, 13 Jan 2026 16:30:00 +0100 Subject: [PATCH] docs: add runbook for local development setup and update docker-related configurations Added a comprehensive runbook detailing the local Docker-based development setup. Updated Dockerfile paths for Nginx and Keycloak to simplify configuration and improve clarity. --- config/docker/keycloak/Dockerfile | 3 +- config/docker/nginx/web-app/Dockerfile | 4 +- .../runbooks/local-development.md | 125 ++++++++++++++++++ 3 files changed, 128 insertions(+), 4 deletions(-) create mode 100644 docs/06_Infrastructure/runbooks/local-development.md diff --git a/config/docker/keycloak/Dockerfile b/config/docker/keycloak/Dockerfile index 464074ae..70181bd8 100644 --- a/config/docker/keycloak/Dockerfile +++ b/config/docker/keycloak/Dockerfile @@ -6,7 +6,6 @@ # Features: # - Pre-built optimized image (faster startup) # - Security hardening -# - Custom theme support # - Health monitoring # =================================================================== ARG KEYCLOAK_IMAGE_TAG @@ -25,7 +24,7 @@ ENV KC_DB=postgres WORKDIR /opt/keycloak # Pre-build Keycloak for faster startup -RUN /opt/keycloak/bin/kc.sh build \ +RUN /opt/keykeycloak/bin/kc.sh build \ --db=postgres \ --health-enabled=true \ --metrics-enabled=true diff --git a/config/docker/nginx/web-app/Dockerfile b/config/docker/nginx/web-app/Dockerfile index 82343caf..4fb5806d 100644 --- a/config/docker/nginx/web-app/Dockerfile +++ b/config/docker/nginx/web-app/Dockerfile @@ -96,9 +96,9 @@ RUN apk add --no-cache curl && \ mkdir -p /usr/share/nginx/html/downloads # Copy Artifacts -COPY config/frontends/web-app/nginx.conf /etc/nginx/nginx.conf +COPY nginx.conf /etc/nginx/nginx.conf COPY --from=builder /app/dist/ /usr/share/nginx/html/ -COPY config/frontends/web-app/downloads/ /usr/share/nginx/html/downloads/ +COPY downloads/ /usr/share/nginx/html/downloads/ # Permissions RUN chown -R nginx:nginx /usr/share/nginx/html && \ diff --git a/docs/06_Infrastructure/runbooks/local-development.md b/docs/06_Infrastructure/runbooks/local-development.md new file mode 100644 index 00000000..e330ada7 --- /dev/null +++ b/docs/06_Infrastructure/runbooks/local-development.md @@ -0,0 +1,125 @@ +# 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](https://docs.docker.com/compose/profiles/), 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. + +```bash +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. + +```bash +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. + +```bash +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: + +```bash +docker-compose down +``` + +Um die Container zu stoppen und auch die benannten Volumes (Datenbankinhalte, etc.) zu löschen: + +```bash +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: + ```yaml + 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](http://localhost:8180) + - Login: `kc-admin` / `kc-password` (Standard, siehe `.env`) +- **pgAdmin (Datenbank-Tool):** [http://localhost:8888](http://localhost:8888) + - Login: `meldestelle@mo-code.at` / `pgadmin` (Standard, siehe `.env`) +- **Grafana (Monitoring):** [http://localhost:3000](http://localhost:3000) + - Login: `gf-admin` / `gf-password` (Standard, siehe `.env`) +- **Consul UI (Service Discovery):** [http://localhost:8500](http://localhost:8500) +- **API Gateway:** [http://localhost:8081](http://localhost:8081) +- **Web App:** [http://localhost:4000](http://localhost:4000) + +## 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: + +```yaml +# 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: + +```bash +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. +```