133 lines
4.9 KiB
Markdown
133 lines
4.9 KiB
Markdown
---
|
|
type: Guide
|
|
status: ACTIVE
|
|
owner: DevOps Engineer
|
|
last_update: 2026-03-15
|
|
---
|
|
# 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)
|
|
- **Mailpit (E-Mail Testing):** [http://localhost:8025](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:
|
|
|
|
```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.
|