refactoring Single Source of Truth
This commit is contained in:
@@ -0,0 +1,247 @@
|
||||
# Docker-Architektur und Services
|
||||
|
||||
---
|
||||
guideline_type: "technology"
|
||||
scope: "docker-architecture"
|
||||
audience: ["developers", "ai-assistants", "devops"]
|
||||
last_updated: "2025-09-13"
|
||||
dependencies: ["docker-overview.md", "master-guideline.md"]
|
||||
related_files: ["docker-compose.yml", "docker/versions.toml", "scripts/docker-versions-update.sh"]
|
||||
ai_context: "Docker container architecture, service definitions, and centralized version management"
|
||||
---
|
||||
|
||||
## 🏗️ Architektur-Überblick
|
||||
|
||||
### Container-Kategorien
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Infrastructure Services"
|
||||
PG[PostgreSQL]
|
||||
RD[Redis]
|
||||
KC[Keycloak]
|
||||
KF[Kafka+Zookeeper]
|
||||
CS[Consul]
|
||||
end
|
||||
|
||||
subgraph "Application Services"
|
||||
GW[API Gateway]
|
||||
AS[Auth Server]
|
||||
MS[Monitoring Server]
|
||||
PS[Ping Service]
|
||||
end
|
||||
|
||||
subgraph "Client Applications"
|
||||
WA[Web App]
|
||||
DA[Desktop App - Native]
|
||||
end
|
||||
|
||||
subgraph "Monitoring Stack"
|
||||
PR[Prometheus]
|
||||
GR[Grafana]
|
||||
ZK[Zipkin]
|
||||
NX[Nginx - Prod]
|
||||
end
|
||||
|
||||
Infrastructure --> Application
|
||||
Application --> Client
|
||||
Monitoring --> Infrastructure
|
||||
Monitoring --> Application
|
||||
```
|
||||
|
||||
### Service-Ports Matrix
|
||||
|
||||
| Service | Development | Production | Health Check | Debug Port | Version |
|
||||
|---------|------------|------------|--------------|------------|---------|
|
||||
| PostgreSQL | 5432 | Internal | pg_isready -U meldestelle -d meldestelle | - | 16-alpine |
|
||||
| Redis | 6379 | Internal | redis-cli ping | - | 7-alpine |
|
||||
| Keycloak | 8180 | 8443 (HTTPS) | /health/ready | - | 26.0.7 |
|
||||
| Kafka | 9092 | Internal | kafka-topics --bootstrap-server localhost:9092 --list | - | 7.4.0 |
|
||||
| Zookeeper | 2181 | Internal | nc -z localhost 2181 | - | 7.4.0 |
|
||||
| Consul | 8500 | Internal | /v1/status/leader | - | 1.15 |
|
||||
| Auth Server | 8081 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
|
||||
| Ping Service | 8082 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
|
||||
| Monitoring Server | 8083 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
|
||||
| Prometheus | 9090 | Internal | /-/healthy | - | v2.54.1 |
|
||||
| Grafana | 3000 | 3443 (HTTPS) | /api/health | - | 11.3.0 |
|
||||
| Nginx | - | 80/443 | /health | - | 1.25-alpine |
|
||||
|
||||
## 🎯 Zentrale Docker-Versionsverwaltung
|
||||
|
||||
> **🤖 AI-Assistant Hinweis:**
|
||||
> Das Versionssystem folgt dem Single Source of Truth Prinzip:
|
||||
> - **Zentrale Datei:** `docker/versions.toml` definiert alle Versionen
|
||||
> - **Build-Args:** Automatisch generierte `.env`-Dateien in `docker/build-args/`
|
||||
> - **Updates:** Via `./scripts/docker-versions-update.sh`
|
||||
|
||||
### Überblick und Motivation
|
||||
|
||||
**Version 3.0.0** führt eine revolutionäre Änderung in der Docker-Versionsverwaltung ein: die **zentrale Verwaltung aller Build-Argumente** analog zum bewährten `gradle/libs.versions.toml` System.
|
||||
|
||||
#### Das Problem vor Version 3.0.0
|
||||
|
||||
```dockerfile
|
||||
# BEFORE: Redundante Hardcodierung in 12+ Dockerfiles
|
||||
ARG GRADLE_VERSION=9.0.0
|
||||
ARG GRADLE_VERSION=9.0.0
|
||||
ARG GRADLE_VERSION=9.0.0
|
||||
# ... 9 weitere Male identisch wiederholt!
|
||||
```
|
||||
|
||||
#### Die Lösung: Single Source of Truth
|
||||
|
||||
```toml
|
||||
# docker/versions.toml - SINGLE SOURCE OF TRUTH
|
||||
[versions]
|
||||
gradle = "9.0.0"
|
||||
java = "21"
|
||||
node = "20.12.0"
|
||||
nginx = "1.25-alpine"
|
||||
prometheus = "v2.54.1"
|
||||
grafana = "11.3.0"
|
||||
keycloak = "26.0.7"
|
||||
```
|
||||
|
||||
### 🏗️ Architektur der zentralen Versionsverwaltung
|
||||
|
||||
```
|
||||
docker/
|
||||
├── versions.toml # 🎯 Single Source of Truth
|
||||
├── build-args/ # Auto-generierte Environment Files
|
||||
│ ├── global.env # Globale Build-Argumente
|
||||
│ ├── services.env # dockerfiles/services/*
|
||||
│ ├── clients.env # dockerfiles/clients/*
|
||||
│ └── infrastructure.env # dockerfiles/infrastructure/*
|
||||
└── README.md # Dokumentation
|
||||
```
|
||||
|
||||
### 📊 Hierarchische Versionsverwaltung
|
||||
|
||||
#### 1. **Globale Versionen** (`docker/build-args/global.env`)
|
||||
Verwendet von **allen** Dockerfiles:
|
||||
```bash
|
||||
# --- Build Tools ---
|
||||
GRADLE_VERSION=9.0.0
|
||||
JAVA_VERSION=21
|
||||
|
||||
# --- Build Metadata ---
|
||||
BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ')
|
||||
VERSION=1.0.0
|
||||
|
||||
# --- Common Base Images ---
|
||||
ALPINE_VERSION=3.19
|
||||
ECLIPSE_TEMURIN_JDK_VERSION=21-jdk-alpine
|
||||
ECLIPSE_TEMURIN_JRE_VERSION=21-jre-alpine
|
||||
|
||||
# --- Monitoring & Infrastructure Services ---
|
||||
DOCKER_PROMETHEUS_VERSION=v2.54.1
|
||||
DOCKER_GRAFANA_VERSION=11.3.0
|
||||
DOCKER_KEYCLOAK_VERSION=26.0.7
|
||||
```
|
||||
|
||||
#### 2. **Kategorie-spezifische Versionen**
|
||||
|
||||
**Services** (`docker/build-args/services.env`):
|
||||
```bash
|
||||
SPRING_PROFILES_ACTIVE=docker
|
||||
SERVICE_PORT=8080
|
||||
PING_SERVICE_PORT=8082
|
||||
MEMBERS_SERVICE_PORT=8083
|
||||
```
|
||||
|
||||
**Clients** (`docker/build-args/clients.env`):
|
||||
```bash
|
||||
NODE_VERSION=20.11.0
|
||||
NGINX_VERSION=1.25-alpine
|
||||
WEB_APP_PORT=4000
|
||||
DESKTOP_APP_VNC_PORT=5901
|
||||
```
|
||||
|
||||
**Infrastructure** (`docker/build-args/infrastructure.env`):
|
||||
```bash
|
||||
SPRING_PROFILES_ACTIVE=default
|
||||
GATEWAY_PORT=8081
|
||||
AUTH_SERVER_PORT=8087
|
||||
```
|
||||
|
||||
### 🛠️ Verwendung der zentralen Versionsverwaltung
|
||||
|
||||
#### Automatisierte Builds mit `scripts/docker-build.sh`
|
||||
|
||||
```bash
|
||||
# Alle Services mit zentralen Versionen bauen
|
||||
./scripts/docker-build.sh services
|
||||
|
||||
# Client-Anwendungen bauen
|
||||
./scripts/docker-build.sh clients
|
||||
|
||||
# Komplettes System bauen
|
||||
./scripts/docker-build.sh all
|
||||
|
||||
# Aktuelle Versionen anzeigen
|
||||
./scripts/docker-build.sh --versions
|
||||
```
|
||||
|
||||
#### Versionen aktualisieren mit `scripts/docker-versions-update.sh`
|
||||
|
||||
```bash
|
||||
# Aktuelle Versionen anzeigen
|
||||
./scripts/docker-versions-update.sh show
|
||||
|
||||
# Java auf Version 22 upgraden
|
||||
./scripts/docker-versions-update.sh update java 22
|
||||
|
||||
# Gradle auf 9.1.0 upgraden
|
||||
./scripts/docker-versions-update.sh update gradle 9.1.0
|
||||
|
||||
# Prometheus auf neueste Version upgraden
|
||||
./scripts/docker-versions-update.sh update prometheus v2.54.1
|
||||
|
||||
# Grafana auf neueste Version upgraden
|
||||
./scripts/docker-versions-update.sh update grafana 11.3.0
|
||||
|
||||
# Keycloak auf neueste Version upgraden
|
||||
./scripts/docker-versions-update.sh update keycloak 26.0.7
|
||||
|
||||
# Alle Environment-Dateien synchronisieren
|
||||
./scripts/docker-versions-update.sh sync
|
||||
```
|
||||
|
||||
## 🎯 Für AI-Assistenten: Architektur-Schnellreferenz
|
||||
|
||||
### Service-Kategorien
|
||||
- **Infrastructure:** PostgreSQL, Redis, Keycloak, Kafka, Zookeeper, Consul
|
||||
- **Application:** API Gateway, Auth Server, Monitoring Server, Ping Service
|
||||
- **Clients:** Web App (Port 3000), Desktop App
|
||||
- **Monitoring:** Prometheus (9090), Grafana (3000), Zipkin, Nginx
|
||||
|
||||
### Wichtige Befehle
|
||||
```bash
|
||||
# Service-Status prüfen
|
||||
docker-compose ps
|
||||
|
||||
# Logs eines Services anzeigen
|
||||
docker-compose logs <service-name>
|
||||
|
||||
# Versionen aktualisieren
|
||||
./scripts/docker-versions-update.sh show
|
||||
./scripts/docker-versions-update.sh update <component> <version>
|
||||
|
||||
# Services neu starten
|
||||
docker-compose restart <service-name>
|
||||
```
|
||||
|
||||
### Zentrale Konfigurationsdateien
|
||||
- `docker/versions.toml` - Alle Versionen
|
||||
- `docker-compose.yml` - Haupt-Services
|
||||
- `docker-compose.clients.yml` - Client-Anwendungen
|
||||
- `docker/build-args/*.env` - Generierte Build-Argumente
|
||||
|
||||
---
|
||||
|
||||
**Navigation:**
|
||||
- [Docker-Overview](./docker-overview.md) - Grundlagen und Philosophie
|
||||
- [Docker-Development](./docker-development.md) - Entwicklungsworkflow
|
||||
- [Docker-Production](./docker-production.md) - Production-Deployment
|
||||
- [Docker-Monitoring](./docker-monitoring.md) - Observability
|
||||
- [Docker-Troubleshooting](./docker-troubleshooting.md) - Problemlösung
|
||||
@@ -0,0 +1,181 @@
|
||||
# Docker-Development Workflow
|
||||
|
||||
---
|
||||
guideline_type: "technology"
|
||||
scope: "docker-development"
|
||||
audience: ["developers", "ai-assistants"]
|
||||
last_updated: "2025-09-13"
|
||||
dependencies: ["docker-overview.md", "docker-architecture.md"]
|
||||
related_files: ["docker-compose.yml", "docker-compose.override.yml", "Makefile"]
|
||||
ai_context: "Development workflow, debugging, and local development setup with Docker"
|
||||
---
|
||||
|
||||
## 🛠️ Development-Workflow
|
||||
|
||||
### Schnellstart-Befehle
|
||||
|
||||
```bash
|
||||
# 🚀 Komplettes Development-Setup
|
||||
make dev-up # Startet alle Development-Services
|
||||
make dev-down # Stoppt alle Services
|
||||
make dev-logs # Zeigt Logs aller Services
|
||||
make dev-restart # Neustart aller Services
|
||||
|
||||
# 🔧 Service-spezifische Befehle
|
||||
make service-build SERVICE=ping-service # Service neu bauen
|
||||
make service-logs SERVICE=ping-service # Service-Logs anzeigen
|
||||
make service-restart SERVICE=ping-service # Service neustarten
|
||||
```
|
||||
|
||||
> **🤖 AI-Assistant Hinweis:**
|
||||
> Für Development verwende die Makefile-Befehle oder direkt docker-compose:
|
||||
> - **Alles starten:** `make dev-up` oder `docker-compose up -d`
|
||||
> - **Logs ansehen:** `make dev-logs` oder `docker-compose logs -f`
|
||||
> - **Service debuggen:** `docker-compose exec <service> sh`
|
||||
|
||||
**Makefile-Beispiel:**
|
||||
|
||||
```makefile
|
||||
# Development commands
|
||||
.PHONY: dev-up dev-down dev-logs dev-restart
|
||||
|
||||
dev-up:
|
||||
docker-compose -f docker-compose.yml -f docker-compose.services.yml up -d
|
||||
@echo "🚀 Development environment started"
|
||||
@echo "📊 Grafana: http://localhost:3000 (admin/admin)"
|
||||
@echo "🔍 Prometheus: http://localhost:9090"
|
||||
@echo "🚪 API Gateway: http://localhost:8080"
|
||||
|
||||
dev-down:
|
||||
docker-compose -f docker-compose.yml -f docker-compose.services.yml down
|
||||
|
||||
dev-logs:
|
||||
docker-compose -f docker-compose.yml -f docker-compose.services.yml logs -f
|
||||
|
||||
dev-restart:
|
||||
$(MAKE) dev-down
|
||||
$(MAKE) dev-up
|
||||
|
||||
# Service-specific commands
|
||||
service-build:
|
||||
@test -n "$(SERVICE)" || (echo "❌ SERVICE parameter required"; exit 1)
|
||||
docker-compose -f docker-compose.yml -f docker-compose.services.yml build $(SERVICE)
|
||||
|
||||
service-logs:
|
||||
@test -n "$(SERVICE)" || (echo "❌ SERVICE parameter required"; exit 1)
|
||||
docker-compose logs -f $(SERVICE)
|
||||
|
||||
service-restart:
|
||||
@test -n "$(SERVICE)" || (echo "❌ SERVICE parameter required"; exit 1)
|
||||
docker-compose -f docker-compose.yml -f docker-compose.services.yml restart $(SERVICE)
|
||||
```
|
||||
|
||||
### Hot-Reload Development
|
||||
|
||||
**docker-compose.override.yml** für optimierte Entwicklung:
|
||||
|
||||
```yaml
|
||||
# Development overrides für Hot-Reload
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
web-client:
|
||||
volumes:
|
||||
- ./client/web-app/src:/app/src:ro
|
||||
- ./client/common-ui/src:/app/common-ui/src:ro
|
||||
environment:
|
||||
- NODE_ENV=development
|
||||
command: npm run dev
|
||||
|
||||
ping-service:
|
||||
environment:
|
||||
- DEBUG=true
|
||||
- SPRING_DEVTOOLS_RESTART_ENABLED=true
|
||||
ports:
|
||||
- "5005:5005" # Debug-Port
|
||||
volumes:
|
||||
- ./temp/ping-service/src:/workspace/src:ro
|
||||
```
|
||||
|
||||
### Debugging von Services
|
||||
|
||||
```bash
|
||||
# Service im Debug-Modus starten
|
||||
docker-compose -f docker-compose.yml up -d ping-service
|
||||
docker-compose exec ping-service sh
|
||||
|
||||
# Logs in Echtzeit verfolgen
|
||||
docker-compose logs -f ping-service api-gateway
|
||||
|
||||
# Health-Check Status prüfen
|
||||
curl -s http://localhost:8082/actuator/health | jq
|
||||
curl -s http://localhost:8080/actuator/health | jq
|
||||
```
|
||||
|
||||
## 🎯 AI-Assistenten: Development-Schnellreferenz
|
||||
|
||||
### Häufige Entwicklungsaufgaben
|
||||
|
||||
| Aufgabe | Befehl | Beschreibung |
|
||||
|---------|---------|--------------|
|
||||
| Umgebung starten | `make dev-up` | Alle Services für Development |
|
||||
| Service debuggen | `docker-compose exec <service> sh` | Shell im Container |
|
||||
| Logs verfolgen | `docker-compose logs -f <service>` | Live-Logs anzeigen |
|
||||
| Service neu bauen | `make service-build SERVICE=<name>` | Einzelnen Service rebuilden |
|
||||
| Health-Check | `curl localhost:<port>/actuator/health` | Service-Status prüfen |
|
||||
|
||||
### Development-URLs
|
||||
- **Grafana:** http://localhost:3000 (admin/admin)
|
||||
- **Prometheus:** http://localhost:9090
|
||||
- **API Gateway:** http://localhost:8080
|
||||
- **Consul:** http://localhost:8500
|
||||
- **Keycloak:** http://localhost:8180
|
||||
|
||||
### Debug-Ports
|
||||
- **Spring-Services:** 5005 (Standard Java Debug)
|
||||
- **Web-App:** Hot-Reload über Volume-Mapping
|
||||
- **Client-Apps:** Port 4000 (Web), 5901 (Desktop VNC)
|
||||
|
||||
### Troubleshooting Development
|
||||
|
||||
#### Container startet nicht
|
||||
```bash
|
||||
# Container-Status prüfen
|
||||
docker-compose ps
|
||||
|
||||
# Container-Logs anzeigen
|
||||
docker-compose logs <service-name>
|
||||
|
||||
# Container neu starten
|
||||
docker-compose restart <service-name>
|
||||
|
||||
# Image neu bauen
|
||||
docker-compose build --no-cache <service-name>
|
||||
```
|
||||
|
||||
#### Port-Konflikte
|
||||
```bash
|
||||
# Ports prüfen
|
||||
netstat -tulpn | grep :<port>
|
||||
|
||||
# Service mit anderem Port starten
|
||||
docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d
|
||||
```
|
||||
|
||||
#### Volume-Probleme
|
||||
```bash
|
||||
# Volumes prüfen
|
||||
docker volume ls
|
||||
|
||||
# Volume-Inhalt anzeigen
|
||||
docker-compose exec <service> ls -la /path/to/volume
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Navigation:**
|
||||
- [Docker-Overview](./docker-overview.md) - Grundlagen und Philosophie
|
||||
- [Docker-Architecture](./docker-architecture.md) - Container-Services und Struktur
|
||||
- [Docker-Production](./docker-production.md) - Production-Deployment
|
||||
- [Docker-Monitoring](./docker-monitoring.md) - Observability
|
||||
- [Docker-Troubleshooting](./docker-troubleshooting.md) - Problemlösung
|
||||
@@ -0,0 +1,252 @@
|
||||
# Docker-Monitoring und Observability
|
||||
|
||||
---
|
||||
guideline_type: "technology"
|
||||
scope: "docker-monitoring"
|
||||
audience: ["developers", "devops", "ai-assistants"]
|
||||
last_updated: "2025-09-13"
|
||||
dependencies: ["docker-overview.md", "docker-architecture.md"]
|
||||
related_files: ["docker-compose.yml", "config/monitoring/*", "config/grafana/*", "config/prometheus/*"]
|
||||
ai_context: "Monitoring setup, Prometheus metrics, Grafana dashboards, health checks, and log aggregation"
|
||||
---
|
||||
|
||||
## 📊 Monitoring und Observability
|
||||
|
||||
### Prometheus Metrics
|
||||
|
||||
Alle Services exposieren standardisierte Metrics:
|
||||
|
||||
```yaml
|
||||
# Service-Labels für Prometheus Autodiscovery
|
||||
labels:
|
||||
- "prometheus.scrape=true"
|
||||
- "prometheus.port=8080"
|
||||
- "prometheus.path=/actuator/prometheus"
|
||||
- "prometheus.service=${SERVICE_NAME}"
|
||||
```
|
||||
|
||||
> **🤖 AI-Assistant Hinweis:**
|
||||
> Monitoring-Stack Zugriff:
|
||||
> - **Grafana:** http://localhost:3000 (admin/admin)
|
||||
> - **Prometheus:** http://localhost:9090
|
||||
> - **Metrics-Endpoints:** `/actuator/prometheus` für Spring-Services
|
||||
> - **Health-Checks:** `/actuator/health` für Readiness-Probes
|
||||
|
||||
### Grafana Dashboards
|
||||
|
||||
**Vorgefertigte Dashboards:**
|
||||
|
||||
- **Infrastructure Overview**: CPU, Memory, Disk, Network
|
||||
- **Spring Boot Services**: JVM Metrics, HTTP Requests, Circuit Breaker
|
||||
- **Database Performance**: PostgreSQL Connections, Query Performance
|
||||
- **Message Queue**: Kafka Consumer Lag, Throughput
|
||||
- **Business Metrics**: Application-spezifische KPIs
|
||||
|
||||
### Health Check Matrix
|
||||
|
||||
| Service | Endpoint | Erwartung | Timeout |
|
||||
|---------|----------|-----------|---------|
|
||||
| API Gateway | `/actuator/health` | `{"status":"UP"}` | 15s |
|
||||
| Ping Service | `/actuator/health/readiness` | HTTP 200 | 3s |
|
||||
| PostgreSQL | `pg_isready` | Connection OK | 5s |
|
||||
| Redis | `redis-cli ping` | PONG | 5s |
|
||||
| Keycloak | `/health/ready` | HTTP 200 | 5s |
|
||||
|
||||
### Log Aggregation
|
||||
|
||||
```bash
|
||||
# Centralized logging mit ELK Stack (optional)
|
||||
docker-compose -f docker-compose.yml -f docker-compose.logging.yml up -d
|
||||
|
||||
# Log-Parsing für strukturierte Logs
|
||||
docker-compose logs --follow --tail=100 api-gateway | jq -r '.message'
|
||||
```
|
||||
|
||||
## 🎯 AI-Assistenten: Monitoring-Schnellreferenz
|
||||
|
||||
### Monitoring-URLs
|
||||
- **Grafana Dashboard:** http://localhost:3000 (admin/admin)
|
||||
- **Prometheus Targets:** http://localhost:9090/targets
|
||||
- **Prometheus Metrics:** http://localhost:9090/metrics
|
||||
- **Service Health:** http://localhost:<port>/actuator/health
|
||||
|
||||
### Wichtige Metrics
|
||||
|
||||
| Metric-Typ | Beispiel | Beschreibung |
|
||||
|------------|----------|--------------|
|
||||
| JVM Memory | `jvm_memory_used_bytes` | Speicherverbrauch Java-Services |
|
||||
| HTTP Requests | `http_requests_total` | API-Request-Zähler |
|
||||
| Database Connections | `hikaricp_connections` | Pool-Verbindungen |
|
||||
| Kafka Lag | `kafka_consumer_lag` | Consumer-Verzögerung |
|
||||
| Custom Business | `meldestelle_registrations_total` | Fachliche KPIs |
|
||||
|
||||
### Health-Check Befehle
|
||||
|
||||
```bash
|
||||
# Alle Services prüfen
|
||||
docker-compose ps
|
||||
|
||||
# Service-spezifische Health-Checks
|
||||
curl -s http://localhost:8082/actuator/health | jq '.status'
|
||||
curl -s http://localhost:8081/actuator/health | jq '.status'
|
||||
|
||||
# Infrastructure Health-Checks
|
||||
docker-compose exec postgres pg_isready -U meldestelle -d meldestelle
|
||||
docker-compose exec redis redis-cli ping
|
||||
curl -s http://localhost:8180/health/ready
|
||||
```
|
||||
|
||||
### Log-Analyse
|
||||
|
||||
```bash
|
||||
# Service-Logs in Echtzeit
|
||||
docker-compose logs -f <service-name>
|
||||
|
||||
# Error-Logs filtern
|
||||
docker-compose logs <service-name> | grep ERROR
|
||||
|
||||
# JSON-Logs strukturiert anzeigen
|
||||
docker-compose logs api-gateway | jq -r '. | select(.level=="ERROR") | .message'
|
||||
|
||||
# Performance-Logs analysieren
|
||||
docker-compose logs api-gateway | grep -i "took\|duration\|time"
|
||||
```
|
||||
|
||||
### Dashboard-Setup
|
||||
|
||||
#### Infrastructure-Dashboard
|
||||
```json
|
||||
{
|
||||
"dashboard": {
|
||||
"title": "Meldestelle Infrastructure",
|
||||
"panels": [
|
||||
{
|
||||
"title": "CPU Usage",
|
||||
"targets": [
|
||||
{
|
||||
"expr": "rate(container_cpu_usage_seconds_total[5m]) * 100"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Memory Usage",
|
||||
"targets": [
|
||||
{
|
||||
"expr": "container_memory_usage_bytes / container_spec_memory_limit_bytes * 100"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Application-Dashboard
|
||||
```json
|
||||
{
|
||||
"dashboard": {
|
||||
"title": "Meldestelle Services",
|
||||
"panels": [
|
||||
{
|
||||
"title": "HTTP Requests/sec",
|
||||
"targets": [
|
||||
{
|
||||
"expr": "rate(http_requests_total[1m])"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Response Time",
|
||||
"targets": [
|
||||
{
|
||||
"expr": "histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Alerting-Regeln
|
||||
|
||||
```yaml
|
||||
# prometheus/alerts.yml
|
||||
groups:
|
||||
- name: meldestelle.rules
|
||||
rules:
|
||||
- alert: ServiceDown
|
||||
expr: up == 0
|
||||
for: 1m
|
||||
labels:
|
||||
severity: critical
|
||||
annotations:
|
||||
summary: "Service {{ $labels.instance }} is down"
|
||||
|
||||
- alert: HighMemoryUsage
|
||||
expr: (container_memory_usage_bytes / container_spec_memory_limit_bytes) > 0.8
|
||||
for: 5m
|
||||
labels:
|
||||
severity: warning
|
||||
annotations:
|
||||
summary: "High memory usage on {{ $labels.instance }}"
|
||||
|
||||
- alert: DatabaseConnectionsFull
|
||||
expr: hikaricp_connections_active >= hikaricp_connections_max * 0.8
|
||||
for: 2m
|
||||
labels:
|
||||
severity: warning
|
||||
annotations:
|
||||
summary: "Database connection pool nearly exhausted"
|
||||
```
|
||||
|
||||
### Monitoring-Wartung
|
||||
|
||||
```bash
|
||||
# Prometheus-Konfiguration neu laden
|
||||
curl -X POST http://localhost:9090/-/reload
|
||||
|
||||
# Grafana-Dashboards exportieren
|
||||
curl -s -H "Authorization: Bearer <token>" \
|
||||
http://localhost:3000/api/dashboards/uid/<dashboard-uid> > dashboard_backup.json
|
||||
|
||||
# Monitoring-Data bereinigen
|
||||
docker-compose exec prometheus rm -rf /prometheus/data
|
||||
docker-compose restart prometheus
|
||||
|
||||
# Log-Rotation für Monitoring-Services
|
||||
docker-compose exec grafana find /var/log -name "*.log" -exec truncate -s 0 {} \;
|
||||
```
|
||||
|
||||
### Performance-Tuning
|
||||
|
||||
```yaml
|
||||
# prometheus.yml - Optimierte Konfiguration
|
||||
global:
|
||||
scrape_interval: 15s
|
||||
evaluation_interval: 15s
|
||||
|
||||
rule_files:
|
||||
- "/etc/prometheus/alerts.yml"
|
||||
|
||||
scrape_configs:
|
||||
- job_name: 'spring-boot'
|
||||
metrics_path: '/actuator/prometheus'
|
||||
static_configs:
|
||||
- targets: ['api-gateway:8080', 'ping-service:8082']
|
||||
scrape_interval: 10s
|
||||
|
||||
- job_name: 'infrastructure'
|
||||
static_configs:
|
||||
- targets: ['postgres:5432', 'redis:6379']
|
||||
scrape_interval: 30s
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Navigation:**
|
||||
- [Docker-Overview](./docker-overview.md) - Grundlagen und Philosophie
|
||||
- [Docker-Architecture](./docker-architecture.md) - Container-Services und Struktur
|
||||
- [Docker-Development](./docker-development.md) - Entwicklungsworkflow
|
||||
- [Docker-Production](./docker-production.md) - Production-Deployment
|
||||
- [Docker-Troubleshooting](./docker-troubleshooting.md) - Problemlösung
|
||||
@@ -0,0 +1,68 @@
|
||||
# Docker-Overview und Philosophie
|
||||
|
||||
---
|
||||
guideline_type: "technology"
|
||||
scope: "docker-overview"
|
||||
audience: ["developers", "ai-assistants"]
|
||||
last_updated: "2025-09-13"
|
||||
dependencies: ["master-guideline.md"]
|
||||
related_files: ["docker-compose.yml", "docker/versions.toml"]
|
||||
ai_context: "Docker philosophy and general principles for Meldestelle project"
|
||||
---
|
||||
|
||||
## 🚀 Überblick und Philosophie
|
||||
|
||||
Das Meldestelle-Projekt implementiert eine **moderne, sicherheitsorientierte Containerisierungsstrategie** basierend auf bewährten DevOps-Praktiken und Production-Ready-Standards. Unsere Docker-Architektur ist darauf ausgelegt:
|
||||
|
||||
- **Sicherheit first**: Alle Container laufen als Non-Root-User
|
||||
- **Optimale Performance**: Multi-stage Builds mit Layer-Caching
|
||||
- **Observability**: Umfassendes Monitoring und Health-Checks
|
||||
- **Skalierbarkeit**: Microservices-ready mit Service Discovery
|
||||
- **Wartbarkeit**: Standardisierte Templates und klare Konventionen
|
||||
|
||||
## 🎯 Für AI-Assistenten: Wichtige Konzepte
|
||||
|
||||
> **🤖 AI-Assistant Hinweis:**
|
||||
> Diese Sektion enthält die Grundphilosophie des Docker-Setups.
|
||||
> - Alle Versionsinformationen sind in `docker/versions.toml` zentralisiert
|
||||
> - Services sind in `docker-compose.yml` definiert
|
||||
> - Monitoring läuft unter `http://localhost:3001` (Grafana)
|
||||
|
||||
### Zentrale Dateien für AI-Referenz
|
||||
- `docker/versions.toml` - Single Source of Truth für alle Versionen
|
||||
- `docker-compose.yml` - Haupt-Service-Orchestrierung
|
||||
- `scripts/docker-versions-update.sh` - Automatische Version-Updates
|
||||
- `scripts/validate-docker-consistency.sh` - Konsistenz-Validierung
|
||||
|
||||
## 📋 Docker-Guidelines Navigation
|
||||
|
||||
Für spezifische Docker-Themen siehe:
|
||||
- [Docker-Architektur](./docker-architecture.md) - Container-Services und Struktur
|
||||
- [Docker-Development](./docker-development.md) - Entwicklungsworkflow
|
||||
- [Docker-Production](./docker-production.md) - Production-Deployment
|
||||
- [Docker-Monitoring](./docker-monitoring.md) - Observability und Überwachung
|
||||
- [Docker-Troubleshooting](./docker-troubleshooting.md) - Problemlösung
|
||||
|
||||
## Grundprinzipien
|
||||
|
||||
### Sicherheitsaspekte
|
||||
- **Non-Root-Container**: Alle Container laufen mit dediziertem User
|
||||
- **Minimale Base-Images**: Verwendung schlanker Images (Alpine, Distroless)
|
||||
- **Security-Scans**: Regelmäßige Vulnerability-Checks
|
||||
- **Network-Segmentierung**: Isolierte Docker-Networks
|
||||
|
||||
### Performance-Optimierung
|
||||
- **Multi-Stage-Builds**: Schlanke Production-Images
|
||||
- **Layer-Caching**: Optimale Build-Performance
|
||||
- **Resource-Limits**: Definierte CPU/Memory-Constraints
|
||||
- **Health-Checks**: Proaktive Service-Überwachung
|
||||
|
||||
### Wartbarkeit
|
||||
- **Standardisierte Templates**: Konsistente Dockerfile-Struktur
|
||||
- **Zentrale Konfiguration**: Environment-basierte Konfiguration
|
||||
- **Dokumentation**: Umfassende README-Dateien pro Service
|
||||
- **Versionierung**: Semantische Versionierung aller Images
|
||||
|
||||
---
|
||||
|
||||
> **Basis-Prinzipien:** Diese Guidelines erweitern die [Master-Guideline](../../master-guideline.md) um Docker-spezifische Aspekte und folgen den allgemeinen Projektstandards.
|
||||
@@ -0,0 +1,226 @@
|
||||
# Docker-Production Deployment
|
||||
|
||||
---
|
||||
guideline_type: "technology"
|
||||
scope: "docker-production"
|
||||
audience: ["developers", "devops", "ai-assistants"]
|
||||
last_updated: "2025-09-13"
|
||||
dependencies: ["docker-overview.md", "docker-architecture.md"]
|
||||
related_files: ["docker-compose.yml", "config/nginx/nginx.prod.conf", "config/ssl/*"]
|
||||
ai_context: "Production deployment, security hardening, SSL/TLS configuration, and resource management"
|
||||
---
|
||||
|
||||
## 🚀 Production-Deployment
|
||||
|
||||
### Security Hardening
|
||||
|
||||
Unsere Production-Konfiguration implementiert umfassende Sicherheitsmaßnahmen:
|
||||
|
||||
#### 🔒 SSL/TLS Everywhere
|
||||
|
||||
```bash
|
||||
# TLS-Zertifikate vorbereiten
|
||||
mkdir -p config/ssl/{postgres,redis,keycloak,grafana,prometheus,nginx}
|
||||
|
||||
# Let's Encrypt Zertifikate generieren
|
||||
certbot certonly --dns-route53 -d api.meldestelle.at
|
||||
certbot certonly --dns-route53 -d auth.meldestelle.at
|
||||
certbot certonly --dns-route53 -d monitor.meldestelle.at
|
||||
```
|
||||
|
||||
#### 🛡️ Environment Variables
|
||||
|
||||
> **🤖 AI-Assistant Hinweis:**
|
||||
> Alle Passwörter werden in der Produktion mit starker Verschlüsselung generiert:
|
||||
> - **PostgreSQL/Redis:** `openssl rand -base64 32`
|
||||
> - **Keycloak:** Separate Admin-Credentials
|
||||
> - **Monitoring:** Grafana/Prometheus Admin-Access
|
||||
|
||||
**Erforderliche Production-Variablen:**
|
||||
|
||||
```bash
|
||||
# Datenschutz und Sicherheit
|
||||
export POSTGRES_USER=meldestelle_prod
|
||||
export POSTGRES_PASSWORD=$(openssl rand -base64 32)
|
||||
export POSTGRES_DB=meldestelle_prod
|
||||
export REDIS_PASSWORD=$(openssl rand -base64 32)
|
||||
|
||||
# Keycloak Admin
|
||||
export KEYCLOAK_ADMIN=admin
|
||||
export KEYCLOAK_ADMIN_PASSWORD=$(openssl rand -base64 32)
|
||||
export KC_DB_PASSWORD=${POSTGRES_PASSWORD}
|
||||
export KC_HOSTNAME=auth.meldestelle.at
|
||||
|
||||
# Monitoring
|
||||
export GF_SECURITY_ADMIN_USER=admin
|
||||
export GF_SECURITY_ADMIN_PASSWORD=$(openssl rand -base64 32)
|
||||
export GRAFANA_HOSTNAME=monitor.meldestelle.at
|
||||
export PROMETHEUS_HOSTNAME=metrics.meldestelle.at
|
||||
|
||||
# Kafka Security
|
||||
export KAFKA_BROKER_ID=1
|
||||
export KAFKA_ZOOKEEPER_CONNECT=zookeeper:2181
|
||||
```
|
||||
|
||||
#### 🌐 Reverse Proxy Configuration
|
||||
|
||||
**nginx.prod.conf** Beispiel:
|
||||
|
||||
```nginx
|
||||
upstream api_backend {
|
||||
server api-gateway:8080;
|
||||
keepalive 32;
|
||||
}
|
||||
|
||||
upstream auth_backend {
|
||||
server keycloak:8443;
|
||||
keepalive 32;
|
||||
}
|
||||
|
||||
upstream monitoring_backend {
|
||||
server grafana:3443;
|
||||
keepalive 32;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name api.meldestelle.at;
|
||||
|
||||
ssl_certificate /etc/ssl/nginx/api.meldestelle.at.crt;
|
||||
ssl_certificate_key /etc/ssl/nginx/api.meldestelle.at.key;
|
||||
|
||||
# Security headers
|
||||
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
|
||||
add_header X-Frame-Options DENY always;
|
||||
add_header X-Content-Type-Options nosniff always;
|
||||
add_header Referrer-Policy strict-origin-when-cross-origin always;
|
||||
|
||||
location / {
|
||||
proxy_pass http://api_backend;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Resource Limits
|
||||
|
||||
Alle Production-Services haben definierte Resource-Limits:
|
||||
|
||||
```yaml
|
||||
# Beispiel für Resource-Management
|
||||
services:
|
||||
postgres:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 1G
|
||||
cpus: '0.5'
|
||||
reservations:
|
||||
memory: 512M
|
||||
cpus: '0.25'
|
||||
|
||||
api-gateway:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 512M
|
||||
cpus: '0.5'
|
||||
reservations:
|
||||
memory: 256M
|
||||
cpus: '0.25'
|
||||
```
|
||||
|
||||
## 🎯 AI-Assistenten: Production-Schnellreferenz
|
||||
|
||||
### Production-Domains
|
||||
- **API:** api.meldestelle.at (HTTPS)
|
||||
- **Auth:** auth.meldestelle.at (HTTPS)
|
||||
- **Monitoring:** monitor.meldestelle.at (HTTPS)
|
||||
- **Metrics:** metrics.meldestelle.at (HTTPS)
|
||||
|
||||
### Security-Checkliste
|
||||
- [ ] SSL/TLS-Zertifikate installiert und gültig
|
||||
- [ ] Alle Passwörter mit `openssl rand -base64 32` generiert
|
||||
- [ ] Nginx Security Headers konfiguriert
|
||||
- [ ] Resource Limits für alle Services definiert
|
||||
- [ ] Firewall-Regeln nur für notwendige Ports
|
||||
- [ ] Container laufen als non-root User
|
||||
|
||||
### Production-Befehle
|
||||
|
||||
| Aufgabe | Befehl | Beschreibung |
|
||||
|---------|---------|--------------|
|
||||
| Zertifikat erneuern | `certbot renew` | Let's Encrypt Zertifikate |
|
||||
| SSL-Status prüfen | `openssl s_client -connect api.meldestelle.at:443` | SSL-Verbindung testen |
|
||||
| Resource-Usage | `docker stats` | Container-Ressourcen |
|
||||
| Security-Scan | `docker scan <image>` | Vulnerability Check |
|
||||
| Log-Rotation | `docker system prune -f` | Alte Logs bereinigen |
|
||||
|
||||
### Environment-Variablen Validierung
|
||||
|
||||
```bash
|
||||
# Production-Variablen prüfen
|
||||
echo "Postgres User: $POSTGRES_USER"
|
||||
echo "Keycloak Hostname: $KC_HOSTNAME"
|
||||
echo "Grafana Hostname: $GRAFANA_HOSTNAME"
|
||||
|
||||
# Passwort-Stärke prüfen (sollte 32+ Zeichen haben)
|
||||
echo ${#POSTGRES_PASSWORD} # Sollte 44+ ausgeben
|
||||
echo ${#KEYCLOAK_ADMIN_PASSWORD} # Sollte 44+ ausgeben
|
||||
```
|
||||
|
||||
### Deployment-Workflow
|
||||
|
||||
```bash
|
||||
# 1. Environment-Variablen setzen
|
||||
source .env.production
|
||||
|
||||
# 2. SSL-Zertifikate prüfen
|
||||
certbot certificates
|
||||
|
||||
# 3. Services mit Production-Konfiguration starten
|
||||
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
|
||||
|
||||
# 4. Health-Checks durchführen
|
||||
curl -f https://api.meldestelle.at/actuator/health
|
||||
curl -f https://auth.meldestelle.at/health/ready
|
||||
curl -f https://monitor.meldestelle.at/api/health
|
||||
|
||||
# 5. SSL-Konfiguration validieren
|
||||
curl -I https://api.meldestelle.at | grep -i security
|
||||
```
|
||||
|
||||
### Backup-Strategie
|
||||
|
||||
```bash
|
||||
# Datenbank-Backup
|
||||
docker-compose exec postgres pg_dump -U $POSTGRES_USER $POSTGRES_DB > backup_$(date +%Y%m%d).sql
|
||||
|
||||
# Konfigurationsdateien sichern
|
||||
tar -czf config_backup_$(date +%Y%m%d).tar.gz config/
|
||||
|
||||
# Docker-Volumes sichern
|
||||
docker run --rm -v postgres_data:/data -v $(pwd):/backup alpine tar czf /backup/postgres_backup_$(date +%Y%m%d).tar.gz /data
|
||||
```
|
||||
|
||||
### Monitoring-Integration
|
||||
|
||||
```bash
|
||||
# Prometheus-Targets prüfen
|
||||
curl -s https://metrics.meldestelle.at/api/v1/targets | jq '.data.activeTargets[].health'
|
||||
|
||||
# Grafana-Dashboard Status
|
||||
curl -s https://monitor.meldestelle.at/api/health | jq '.database'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Navigation:**
|
||||
- [Docker-Overview](./docker-overview.md) - Grundlagen und Philosophie
|
||||
- [Docker-Architecture](./docker-architecture.md) - Container-Services und Struktur
|
||||
- [Docker-Development](./docker-development.md) - Entwicklungsworkflow
|
||||
- [Docker-Monitoring](./docker-monitoring.md) - Observability
|
||||
- [Docker-Troubleshooting](./docker-troubleshooting.md) - Problemlösung
|
||||
@@ -0,0 +1,299 @@
|
||||
# Docker-Troubleshooting und Best Practices
|
||||
|
||||
---
|
||||
guideline_type: "technology"
|
||||
scope: "docker-troubleshooting"
|
||||
audience: ["developers", "devops", "ai-assistants"]
|
||||
last_updated: "2025-09-13"
|
||||
dependencies: ["docker-overview.md", "docker-architecture.md", "docker-development.md"]
|
||||
related_files: ["docker-compose.yml", "scripts/validate-docker-consistency.sh", "scripts/docker-versions-update.sh"]
|
||||
ai_context: "Troubleshooting common Docker issues, debug commands, and comprehensive best practices"
|
||||
---
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### Häufige Probleme und Lösungen
|
||||
|
||||
#### 🚫 Port-Konflikte
|
||||
|
||||
```bash
|
||||
# Überprüfe, welche Ports verwendet werden
|
||||
netstat -tulpn | grep :8080
|
||||
lsof -i :8080
|
||||
|
||||
# Stoppe konfligierende Services
|
||||
docker-compose down
|
||||
sudo systemctl stop apache2 # Falls Apache läuft
|
||||
```
|
||||
|
||||
#### 🐌 Langsame Startup-Zeiten
|
||||
|
||||
```bash
|
||||
# Überprüfe Container-Ressourcen
|
||||
docker stats
|
||||
|
||||
# Health-Check Logs analysieren
|
||||
docker-compose logs ping-service | grep health
|
||||
|
||||
# Java Startup optimieren
|
||||
export JAVA_OPTS="$JAVA_OPTS -XX:TieredStopAtLevel=1 -noverify"
|
||||
```
|
||||
|
||||
#### 💾 Disk-Space Probleme
|
||||
|
||||
```bash
|
||||
# Docker-Cleanup
|
||||
docker system prune -a --volumes
|
||||
docker volume prune
|
||||
|
||||
# Log-Rotation für Container
|
||||
docker-compose logs --tail=1000 > /dev/null # Truncate logs
|
||||
```
|
||||
|
||||
#### 🌐 Service Discovery Issues
|
||||
|
||||
```bash
|
||||
# Consul Status prüfen
|
||||
curl -s http://localhost:8500/v1/health/state/any | jq
|
||||
|
||||
# Service Registration überprüfen
|
||||
curl -s http://localhost:8500/v1/catalog/services | jq
|
||||
|
||||
# DNS-Resolution testen
|
||||
docker-compose exec api-gateway nslookup ping-service
|
||||
```
|
||||
|
||||
### Debug-Kommandos
|
||||
|
||||
```bash
|
||||
# Container introspection
|
||||
docker-compose exec SERVICE_NAME sh
|
||||
docker-compose exec postgres psql -U meldestelle -d meldestelle
|
||||
|
||||
# Live-Monitoring
|
||||
docker-compose top
|
||||
watch -n 1 'docker-compose ps'
|
||||
|
||||
# Memory und CPU-Usage
|
||||
docker stats $(docker-compose ps -q)
|
||||
|
||||
# Detailed service logs
|
||||
docker-compose logs -f --tail=50 SERVICE_NAME
|
||||
```
|
||||
|
||||
## 🎯 AI-Assistenten: Troubleshooting-Schnellreferenz
|
||||
|
||||
### Häufige Befehle
|
||||
|
||||
| Problem | Befehl | Beschreibung |
|
||||
|---------|---------|--------------|
|
||||
| Port belegt | `netstat -tulpn \| grep :<port>` | Port-Nutzung prüfen |
|
||||
| Service startet nicht | `docker-compose logs <service>` | Service-Logs anzeigen |
|
||||
| Container hängt | `docker stats` | Ressourcenverbrauch |
|
||||
| DNS-Probleme | `docker-compose exec <service> nslookup <target>` | DNS-Resolution testen |
|
||||
| Disk voll | `docker system prune -a --volumes` | Cleanup durchführen |
|
||||
|
||||
### Debug-Workflows
|
||||
|
||||
#### Service startet nicht
|
||||
1. `docker-compose ps` - Status prüfen
|
||||
2. `docker-compose logs <service>` - Logs analysieren
|
||||
3. `docker-compose exec <service> sh` - Container inspizieren
|
||||
4. Health-Check-Endpoint testen
|
||||
|
||||
#### Performance-Probleme
|
||||
1. `docker stats` - Ressourcenverbrauch
|
||||
2. `docker-compose top` - Prozess-Übersicht
|
||||
3. JVM-Parameter optimieren
|
||||
4. Resource-Limits anpassen
|
||||
|
||||
#### Netzwerk-Probleme
|
||||
1. `docker network ls` - Netzwerke auflisten
|
||||
2. `docker-compose exec <service> ping <target>` - Connectivity testen
|
||||
3. Consul Service-Discovery prüfen
|
||||
4. DNS-Resolution validieren
|
||||
|
||||
## ✅ Best Practices
|
||||
|
||||
### 🔐 Security Best Practices
|
||||
|
||||
1. **Non-Root Users**: Alle Container laufen mit dedizierten Non-Root-Usern
|
||||
2. **Minimal Base Images**: Alpine Linux für kleinste Angriffsfläche
|
||||
3. **Secrets Management**: Externe Secret-Stores für Production
|
||||
4. **Network Isolation**: Dedizierte Docker-Networks
|
||||
5. **Regular Updates**: Automatische Security-Updates für Base Images
|
||||
|
||||
### ⚡ Performance Best Practices
|
||||
|
||||
1. **Multi-Stage Builds**: Minimale Runtime-Images
|
||||
2. **Layer Caching**: Optimale COPY-Reihenfolge in Dockerfiles
|
||||
3. **Resource Limits**: Definierte Memory und CPU-Limits
|
||||
4. **Health Checks**: Proaktive Container-Health-Überwachung
|
||||
5. **JVM Tuning**: Container-aware JVM-Settings
|
||||
|
||||
### 🧹 Wartung Best Practices
|
||||
|
||||
1. **Version Pinning**: Explizite Image-Versionen in Production
|
||||
2. **Backup Strategies**: Automatische Volume-Backups
|
||||
3. **Log Rotation**: Begrenzte Log-Datei-Größen
|
||||
4. **Documentation**: Aktuelle README-Dateien pro Service
|
||||
5. **Testing**: Automatisierte Container-Tests
|
||||
|
||||
### 🎯 Zentrale Verwaltung Best Practices
|
||||
|
||||
#### Single Source of Truth Prinzipien
|
||||
|
||||
```bash
|
||||
# ✅ RICHTIG - Zentrale Version-Updates
|
||||
./scripts/docker-versions-update.sh update java 22
|
||||
./scripts/docker-versions-update.sh sync
|
||||
|
||||
# ❌ FALSCH - Manuelle Bearbeitung von Dockerfiles
|
||||
vim dockerfiles/services/ping-service/Dockerfile # Version hardcoden
|
||||
```
|
||||
|
||||
> **🤖 AI-Assistant Hinweis:**
|
||||
> Verwende immer das zentrale Versionssystem:
|
||||
> - **Updates:** `./scripts/docker-versions-update.sh update <component> <version>`
|
||||
> - **Validierung:** `./scripts/validate-docker-consistency.sh`
|
||||
> - **Template-Updates:** `./scripts/generate-compose-files.sh`
|
||||
|
||||
#### Port-Verwaltung Richtlinien
|
||||
|
||||
1. **Immer zentrale Port-Registry verwenden**:
|
||||
```toml
|
||||
# docker/versions.toml - Port-Definitionen
|
||||
[service-ports]
|
||||
new-service = 8089 # Nächster verfügbarer Port
|
||||
```
|
||||
|
||||
2. **Port-Konflikte vor Deployment prüfen**:
|
||||
```bash
|
||||
./scripts/validate-docker-consistency.sh
|
||||
```
|
||||
|
||||
3. **Port-Ranges einhalten**:
|
||||
- Infrastructure: 8081-8088
|
||||
- Services: 8082-8099
|
||||
- Monitoring: 9090-9099
|
||||
- Clients: 4000-4099
|
||||
|
||||
#### Environment-Overrides Standards
|
||||
|
||||
1. **Environment-spezifische Konfigurationen nutzen**:
|
||||
```bash
|
||||
# Development
|
||||
export DOCKER_ENVIRONMENT=development
|
||||
|
||||
# Production
|
||||
export DOCKER_ENVIRONMENT=production
|
||||
```
|
||||
|
||||
2. **Konsistente Health-Check-Konfigurationen**:
|
||||
```toml
|
||||
[environments.production]
|
||||
health-check-interval = "15s"
|
||||
health-check-timeout = "3s"
|
||||
health-check-retries = 3
|
||||
```
|
||||
|
||||
#### Template-System Richtlinien
|
||||
|
||||
1. **Compose-Files aus Templates generieren**:
|
||||
```bash
|
||||
# Automatische Generierung bevorzugen
|
||||
./scripts/generate-compose-files.sh
|
||||
|
||||
# Manuelle Bearbeitung nur bei spezifischen Anpassungen
|
||||
```
|
||||
|
||||
2. **Service-Kategorien korrekt zuordnen**:
|
||||
- `services/`: Domain-Services (ping, members, horses)
|
||||
- `infrastructure/`: Platform-Services (gateway, auth, monitoring)
|
||||
- `clients/`: Frontend-Anwendungen (web-app, desktop-app)
|
||||
|
||||
#### Validierung und Konsistenz
|
||||
|
||||
1. **Regelmäßige Konsistenz-Prüfungen**:
|
||||
```bash
|
||||
# Bei jedem Build
|
||||
./scripts/validate-docker-consistency.sh
|
||||
|
||||
# In CI/CD Pipeline integrieren
|
||||
```
|
||||
|
||||
2. **Build-Args Konsistenz**:
|
||||
```dockerfile
|
||||
# ✅ RICHTIG - Zentrale Referenz
|
||||
ARG GRADLE_VERSION
|
||||
ARG JAVA_VERSION
|
||||
|
||||
# ❌ FALSCH - Hardcodierte Versionen
|
||||
ARG GRADLE_VERSION=9.0.0
|
||||
```
|
||||
|
||||
#### IDE-Integration Best Practices
|
||||
|
||||
1. **JSON Schema für Validierung aktivieren**:
|
||||
```json
|
||||
{
|
||||
"yaml.schemas": {
|
||||
"./docker/schemas/versions-schema.json": "docker/versions.toml"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Automatisierte Tasks nutzen**:
|
||||
- Docker: Show Versions
|
||||
- Docker: Validate Consistency
|
||||
- Docker: Build All Services
|
||||
|
||||
### 🚀 Entwickler-Workflow Best Practices
|
||||
|
||||
#### Neuen Service hinzufügen
|
||||
|
||||
```bash
|
||||
# 1. Port in versions.toml reservieren
|
||||
echo "new-service = 8089" >> docker/versions.toml
|
||||
|
||||
# 2. Template-basierten Service erstellen
|
||||
./scripts/generate-compose-files.sh
|
||||
|
||||
# 3. Dockerfile aus Template erstellen
|
||||
cp dockerfiles/templates/spring-boot-service.Dockerfile \
|
||||
dockerfiles/services/new-service/Dockerfile
|
||||
|
||||
# 4. Build-Args und Environment synchronisieren
|
||||
./scripts/docker-versions-update.sh sync
|
||||
|
||||
# 5. Konsistenz validieren
|
||||
./scripts/validate-docker-consistency.sh
|
||||
```
|
||||
|
||||
#### Version-Updates durchführen
|
||||
|
||||
```bash
|
||||
# 1. Aktuelle Versionen prüfen
|
||||
./scripts/docker-versions-update.sh show
|
||||
|
||||
# 2. Spezifische Version aktualisieren
|
||||
./scripts/docker-versions-update.sh update java 22
|
||||
|
||||
# 3. Alle Build-Args synchronisieren
|
||||
./scripts/docker-versions-update.sh sync
|
||||
|
||||
# 4. Services neu bauen
|
||||
docker-compose build --no-cache
|
||||
|
||||
# 5. System-Tests durchführen
|
||||
docker-compose up -d && make test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Navigation:**
|
||||
- [Docker-Overview](./docker-overview.md) - Grundlagen und Philosophie
|
||||
- [Docker-Architecture](./docker-architecture.md) - Container-Services und Struktur
|
||||
- [Docker-Development](./docker-development.md) - Entwicklungsworkflow
|
||||
- [Docker-Production](./docker-production.md) - Production-Deployment
|
||||
- [Docker-Monitoring](./docker-monitoring.md) - Observability
|
||||
@@ -0,0 +1,198 @@
|
||||
# Client-App-Richtlinie (Compose Multiplatform)
|
||||
|
||||
---
|
||||
guideline_type: "technology"
|
||||
scope: "web-app-multiplatform"
|
||||
audience: ["developers", "ai-assistants", "frontend-developers"]
|
||||
last_updated: "2025-09-13"
|
||||
dependencies: ["master-guideline.md", "architecture-principles.md"]
|
||||
related_files: ["client/build.gradle.kts", "client/src/commonMain/**", "client/src/wasmJsMain/**", "client/src/jvmMain/**"]
|
||||
ai_context: "Compose Multiplatform development, MVVM pattern, KMP architecture, desktop and web client development"
|
||||
---
|
||||
|
||||
## 1. Einleitung
|
||||
|
||||
Diese Richtlinie beschreibt die Architektur und die Best Practices für die Entwicklung der Client-Anwendungen für das "Meldestelle"-Projekt. Die Client-Anwendungen werden mit **Compose Multiplatform** für Desktop und Web entwickelt.
|
||||
|
||||
Das Hauptziel ist die maximale Wiederverwendung von Code zwischen den Desktop- und Web-Plattformen durch die konsequente Nutzung des `commonMain`-Source-Sets von Kotlin Multiplatform (KMP). Die Anwendung läuft sowohl als native Desktop-Anwendung (JVM) als auch als Web-Anwendung (WebAssembly).
|
||||
|
||||
> **🤖 AI-Assistant Hinweis:**
|
||||
> Compose Multiplatform Entwicklung folgt diesen Kernprinzipien:
|
||||
> - **commonMain:** Geteilte UI-Logik und Business-Logic
|
||||
> - **MVVM-Pattern:** ViewModels in commonMain, UI-Components plattformübergreifend
|
||||
> - **@Composable-Funktionen:** Deklarative UI mit State Hoisting
|
||||
> - **expect/actual:** Plattformspezifische Implementierungen nur wo nötig
|
||||
|
||||
## 2. Grundprinzipien
|
||||
|
||||
### Deklarative UI mit Composables
|
||||
|
||||
Die gesamte Benutzeroberfläche wird als Baum von `@Composable`-Funktionen deklariert. Dies ist derselbe Ansatz, der auch bei Jetpack Compose für Android verwendet wird.
|
||||
|
||||
- **Zustandslosigkeit:** Composables sollten bevorzugt zustandslos sein. Sie erhalten Daten als Parameter und geben Ereignisse über Lambda-Funktionen (Callbacks) nach oben weiter.
|
||||
- **Wiederverwendbarkeit:** Erstellen Sie kleine, spezialisierte und wiederverwendbare Composables. Vermeiden Sie monolithische UI-Funktionen.
|
||||
- **Vorschau:** Nutzen Sie `@Preview`-Annotationen (sofern von der IDE unterstützt), um UI-Komponenten isoliert zu entwickeln und zu visualisieren.
|
||||
|
||||
### State Management
|
||||
|
||||
Der UI-Zustand (State) wird explizit verwaltet.
|
||||
|
||||
- **`mutableStateOf` und `remember`**: Für einfachen, temporären UI-Zustand innerhalb einer Composable-Funktion.
|
||||
- **State Hoisting**: Der Zustand sollte so weit wie möglich nach oben in der Komponentenhierarchie verschoben werden ("State Hoisting"), idealerweise in eine ViewModel- oder Presenter-Klasse in `commonMain`.
|
||||
- **ViewModels/Presenters**: Komplexe Logik zur Zustandsverwaltung gehört in Klassen (z. B. `ExampleViewModel`) im `commonMain`-Modul. Diese Klassen sind plattformunabhängig und können von der UI (im `jsMain`-Modul) genutzt werden.
|
||||
|
||||
### Styling
|
||||
|
||||
Das Styling erfolgt plattformspezifisch, aber mit gemeinsamen Prinzipien:
|
||||
|
||||
#### Gemeinsame Styling-Prinzipien (commonMain)
|
||||
- **Compose Material Design**: Nutzen Sie Material3-Komponenten und Theming für konsistente UI.
|
||||
- **Gemeinsame Designsystem**: Definieren Sie gemeinsame Farben, Typografie und Spacing in `commonMain`.
|
||||
- **Responsive Design**: Berücksichtigen Sie verschiedene Bildschirmgrößen (Desktop-Fenster vs. Browser-Viewports).
|
||||
|
||||
#### Web-spezifisches Styling (wasmJsMain)
|
||||
- **CSS-Integration**: Web-spezifische Styling-Anforderungen können über CSS in den Resources behandelt werden.
|
||||
- **Browser-Kompatibilität**: Berücksichtigen Sie Web-spezifische Rendering-Unterschiede.
|
||||
|
||||
#### Desktop-spezifisches Styling (jvmMain)
|
||||
- **Native Look & Feel**: Desktop-Anwendungen sollten sich nativ anfühlen.
|
||||
- **Fenster-Management**: Berücksichtigen Sie Desktop-spezifische UI-Patterns (Menüleisten, etc.).
|
||||
|
||||
```kotlin
|
||||
// Beispiel für gemeinsames Theming in commonMain
|
||||
@Composable
|
||||
fun AppTheme(content: @Composable () -> Unit) {
|
||||
MaterialTheme(
|
||||
colorScheme = if (isSystemInDarkTheme()) darkColorScheme() else lightColorScheme(),
|
||||
typography = AppTypography,
|
||||
content = content
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Navigation
|
||||
Die Navigation wird plattformunabhängig in `commonMain` implementiert:
|
||||
- **ViewModel-basierte Navigation**: Ein `StateFlow` oder `mutableState` im ViewModel repräsentiert die aktuelle Route/Screen.
|
||||
- **Gemeinsamer Router**: Ein zentraler `Router`-Composable in `commonMain` reagiert auf Zustandsänderungen und rendert den entsprechenden Screen.
|
||||
- **Plattformspezifische Einstiegspunkte**: Desktop und Web haben separate `main.kt`-Dateien, aber nutzen denselben gemeinsamen App-Composable.
|
||||
|
||||
## 3. Projekt- und Code-Struktur
|
||||
Die Codebasis ist klar zwischen plattformunabhängiger Logik (`commonMain`) und plattformspezifischer Implementation (`jvmMain`, `wasmJsMain`) getrennt.
|
||||
|
||||
### Source Sets
|
||||
|
||||
- **`client/src/commonMain`**:
|
||||
- **UI-Code**: Alle `@Composable`-Funktionen, die zwischen Desktop und Web geteilt werden.
|
||||
- **Business-Logik**: ViewModels/Presenters, die den UI-Zustand verwalten.
|
||||
- **Data-Klassen**: Modelle, die Daten repräsentieren.
|
||||
- **Common Dependencies**: Shared Compose-Dependencies (runtime, foundation, material3, ui).
|
||||
|
||||
- **`client/src/jvmMain`** (Desktop-Plattform):
|
||||
- **`main.kt`**: Der Einstiegspunkt der Desktop-Anwendung.
|
||||
- **Desktop-spezifische Code**: Plattformspezifische Implementierungen und Integrationen.
|
||||
- **Desktop Dependencies**: `compose.desktop.currentOs`, Coroutines für Swing.
|
||||
|
||||
- **`client/src/wasmJsMain`** (Web-Plattform):
|
||||
- **`main.kt`**: Der Einstiegspunkt der Web-Anwendung (WebAssembly).
|
||||
- **Web-spezifische Code**: Browser-spezifische Implementierungen.
|
||||
- **Platform-spezifische Implementierungen**: Web-APIs und Browser-Integrationen.
|
||||
|
||||
- **`client/src/wasmJsMain/resources`**:
|
||||
- **`index.html`**: Das Host-HTML-Dokument für die Compose-Anwendung.
|
||||
- **Statische Assets**: Bilder, Schriftarten und andere statische Dateien für die Web-Version.
|
||||
|
||||
### Shared Module Integration
|
||||
- **`core/commonMain`** (oder äquivalente `shared`-Module):
|
||||
- **Repositories/Services**: Code für den Datenzugriff (z.B. Ktor-HTTP-Clients zum Aufrufen des Backends).
|
||||
- **Business-Logik**: Plattformunabhängige Geschäftslogik, die von allen Client-Plattformen genutzt wird.
|
||||
|
||||
## 4. Entwicklung und Ausführung
|
||||
|
||||
### Desktop-Entwicklung
|
||||
Für die Desktop-Anwendung stehen folgende Gradle-Tasks zur Verfügung:
|
||||
|
||||
```shell script
|
||||
# Desktop-Anwendung direkt ausführen
|
||||
./gradlew :client:run
|
||||
|
||||
# Desktop-Distribution erstellen (DMG, MSI, DEB)
|
||||
./gradlew :client:createDistributable
|
||||
./gradlew :client:packageDmg # macOS
|
||||
./gradlew :client:packageMsi # Windows
|
||||
./gradlew :client:packageDeb # Linux
|
||||
```
|
||||
|
||||
### Web-Entwicklung mit Hot-Reload
|
||||
Für die Web-Anwendung mit automatischer Neuladung bei Änderungen:
|
||||
|
||||
```shell script
|
||||
# Web-App mit Hot-Reload starten
|
||||
./gradlew :client:wasmJsBrowserDevelopmentRun
|
||||
```
|
||||
|
||||
#### Docker-Setup für Web-Entwicklung
|
||||
Das Docker-Setup ist spezifisch für die Web-Entwicklung konfiguriert (wie in `README-DOCKER.md` beschrieben):
|
||||
|
||||
```shell script
|
||||
# Startet die Web-App mit Hot-Reload
|
||||
docker-compose -f docker-compose.yml \
|
||||
-f docker-compose.clients.yml up -d web-app
|
||||
```
|
||||
|
||||
Der Dienst ist dann unter dem in der `docker-compose.clients.yml` konfigurierten Port (z.B. Port `3000`) erreichbar.
|
||||
|
||||
### Produktions-Builds
|
||||
|
||||
#### Desktop-Distribution
|
||||
```shell script
|
||||
# Erstellt native Distributionen für alle konfigurierten Plattformen
|
||||
./gradlew :client:packageDistributionForCurrentOS
|
||||
```
|
||||
|
||||
#### Web-Distribution
|
||||
```shell script
|
||||
# Erstellt optimierte WebAssembly-Artefakte für die Produktion
|
||||
./gradlew :client:wasmJsBrowserDistribution
|
||||
```
|
||||
|
||||
Das Docker-Image für die Web-Produktion (`Dockerfile` im `client`-Verzeichnis) sollte den `wasmJsBrowserDistribution`-Task nutzen, um die finalen Artefakte zu bauen.
|
||||
## 5. Plattformspezifische Besonderheiten
|
||||
|
||||
### Desktop (jvmMain)
|
||||
- **Fenster-Management**: Nutzen Sie Compose Desktop-APIs für Fensteroperationen.
|
||||
- **System-Integration**: Zugriff auf Desktop-spezifische Features (Dateisystem, Notifications, etc.).
|
||||
- **Performance**: Desktop-Apps können mehr Ressourcen nutzen als Web-Apps.
|
||||
|
||||
### Web (wasmJsMain)
|
||||
- **Browser-APIs**: Zugriff auf Web-APIs erfolgt über `external`-Deklarationen.
|
||||
- **Bundle-Size**: Achten Sie auf die Größe der WebAssembly-Bundles für optimale Ladezeiten.
|
||||
- **SEO und Accessibility**: Berücksichtigen Sie Web-spezifische Anforderungen.
|
||||
|
||||
## 6. Dos and Don'ts
|
||||
|
||||
### Multiplatform Best Practices
|
||||
- **DO**: Die gesamte UI-Logik (State-Management, Datenabruf, Validierung) in `commonMain` implementieren.
|
||||
- **DO**: Kleine, wiederverwendbare und zustandslose Composables in `commonMain` erstellen.
|
||||
- **DO**: Material3 und gemeinsames Theming für konsistente UI zwischen Plattformen verwenden.
|
||||
- **DO**: Events von der UI über Lambda-Funktionen an die ViewModels in `commonMain` weiterleiten.
|
||||
- **DO**: Plattformspezifische Features über `expect`/`actual`-Mechanismus abstrahieren.
|
||||
|
||||
### Platform-Specific Guidelines
|
||||
- **DO** (Desktop): Native Look & Feel und Desktop-UI-Patterns verwenden.
|
||||
- **DO** (Web): Web-Standards und Accessibility-Guidelines befolgen.
|
||||
|
||||
### Don'ts
|
||||
- **DON'T**: Geschäftslogik, API-Aufrufe oder komplexe Zustandsmanipulationen direkt in `@Composable`-Funktionen schreiben.
|
||||
- **DON'T**: Plattformspezifische Code direkt in `commonMain` verwenden ohne `expect`/`actual`.
|
||||
- **DON'T** (Web): Den DOM direkt manipulieren. Compose Multiplatform verwaltet das Rendering. Falls Interaktion mit externen Bibliotheken nötig ist, nutzen Sie `external`-Mechanismen sauber gekapselt.
|
||||
- **DON'T**: Annahmen über die Zielplattform in `commonMain` machen.
|
||||
|
||||
---
|
||||
|
||||
**Navigation:**
|
||||
- [Master-Guideline](../master-guideline.md) - Übergeordnete Projektrichtlinien
|
||||
- [Architecture-Principles](../project-standards/architecture-principles.md) - Architektur-Grundsätze
|
||||
- [Coding-Standards](../project-standards/coding-standards.md) - Code-Qualitätsstandards
|
||||
- [Testing-Standards](../project-standards/testing-standards.md) - Test-Qualitätssicherung
|
||||
- [Trace-Bullet-Guideline](../process-guides/trace-bullet-guideline.md) - Entwicklungszyklus
|
||||
|
||||
Reference in New Issue
Block a user