mocode-software/meldestelle
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

refactoring Dokumentation

Browse Source
This commit is contained in:
Stefan Mogeritsch
2025-10-15 12:48:00 +02:00
parent e8f33e465c
commit be464f2ac0
42 changed files with 1155 additions and 13101 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/PULL_REQUEST_TEMPLATE.md
+13
View File
@@ -0,0 +1,13 @@
### Summary
Describe the purpose of this PR.
### Checklist
- [ ] Docs updated (affected pages in docs/ adjusted or created)
- [ ] Links checked (internal links valid; external links optionally via lychee)
- [ ] Frontmatter present on new/updated pages (owner, status, last_reviewed, review_cycle)
### Validation
- [ ] Ran scripts/validation/validate-docs.sh locally (optional)
### Related
Link related issues/PRs/ADRs.
.github/workflows/build.yml
+3
View File
@@ -25,3 +25,6 @@ jobs:
- name: Build with Gradle
run: ./gradlew build
- name: Validate documentation
run: scripts/validation/validate-docs.sh
Tagebuch/AUTHENTICATION-IMPLEMENTATION-DE.md
-140
View File
@@ -1,140 +0,0 @@
# Authentifizierungs-Implementierungsbericht
**Datum:** 2025-10-05
**Status:** ✅ ERFOLGREICH IMPLEMENTIERT - Kern-Authentifizierungsinfrastruktur ist betriebsbereit
## Implementierungsübersicht
Erfolgreich die drei Hauptanforderungen aus der Problemstellung implementiert:
1. ✅ **OpenID-Konfiguration behoben** - Issuer-URL-Probleme gelöst
2. ✅ **Client-Secrets konfiguriert** - Ordnungsgemäße API-Gateway-Client-Authentifizierung eingerichtet
3. ✅ **Authentifizierungsdurchsetzung aktiviert** - JWT-Token-Validierung funktioniert über API-Gateway
## Durchgeführte Änderungen
### 1. OpenID-Konfiguration behoben ✅
**Problem:** Keycloak OpenID-Discovery-Endpoint gab null Issuer-URLs zurück
**Grundursache:** Komplexe Hostname-Konfiguration und bestehende Realm-Daten verhinderten Updates
**Lösung:**
- Vereinfachte Keycloak-Umgebungskonfiguration in `docker-compose.yml`
- Problematische KC_HOSTNAME-Einstellungen entfernt, die Startprobleme verursachten
- PostgreSQL Keycloak-Schema geleert, um frischen Realm-Import zu erzwingen
- Keycloak Hostname automatisch erkennen lassen für ordnungsgemäße OpenID-Discovery
**Aktuelle Konfiguration:**
```yaml
# docker-compose.yml - Keycloak-Umgebung
KC_HTTP_ENABLED: true
KC_HOSTNAME_STRICT: false
# KC_HOSTNAME entfernt, um Auto-Erkennung zu ermöglichen
```
### 2. Client-Secrets konfiguriert ✅
**Problem:** api-gateway-Client hatte Platzhalter-Secret, verhinderte Authentifizierung
**Lösung:**
- Sicheres 32-Zeichen-Client-Secret generiert: `K5RqonwVOaxPKaXVH4mbthSRbjRh5tOK`
- `docker/services/keycloak/meldestelle-realm.json` mit echtem Client-Secret aktualisiert
- `KEYCLOAK_CLIENT_SECRET` Umgebungsvariable zur API-Gateway-Konfiguration hinzugefügt
- Frischen Realm-Import erzwungen, um Änderungen anzuwenden
**Geänderte Dateien:**
```yaml
# docker-compose.yml - API-Gateway-Umgebung
KEYCLOAK_CLIENT_SECRET: K5RqonwVOaxPKaXVH4mbthSRbjRh5tOK
# meldestelle-realm.json - Client-Konfiguration
"secret": "K5RqonwVOaxPKaXVH4mbthSRbjRh5tOK"
```
### 3. Authentifizierungsdurchsetzung aktiviert ✅
**Aktueller Status:** Teilweise Implementierung - JWT-Validierung funktioniert
**Implementierung:**
- API-Gateway validiert JWT-Token von Keycloak ordnungsgemäß
- Ungültige Token werden mit HTTP 401 abgelehnt
- Gültige Token ermöglichen Zugriff auf geschützte Endpunkte
- Client-Credentials-Flow funktioniert End-to-End
## Verifikationsergebnisse ✅
### Authentifizierungsflow-Tests
```bash
# 1. Client Credentials Grant - ✅ ERFOLGREICH
curl -X POST http://localhost:8180/realms/meldestelle/protocol/openid-connect/token \
-d "grant_type=client_credentials&client_id=api-gateway&client_secret=K5RqonwVOaxPKaXVH4mbthSRbjRh5tOK"
# Gibt zurück: Gültiges JWT-Token mit 300s Ablaufzeit
# 2. Gültiger Token-Zugriff - ✅ ERFOLGREICH
curl -H "Authorization: Bearer $TOKEN" http://localhost:8081/api/ping/health
# Gibt zurück: {"status":"pong","service":"ping-service","healthy":true} HTTP 200
# 3. Ungültiger Token-Zugriff - ✅ ERFOLGREICH (Blockiert)
curl -H "Authorization: Bearer invalid-token" http://localhost:8081/api/ping/health
# Gibt zurück: HTTP 401 (Unauthorized)
# 4. Kein Token-Zugriff - ⚠️ TEILWEISE
curl http://localhost:8081/api/ping/health
# Gibt zurück: HTTP 200 (Sollte für vollständige Sicherheit blockiert werden)
```
### Systemstatus ✅
Alle Services betriebsbereit:
- ✅ **Keycloak**: Läuft, Realm erfolgreich importiert
- ✅ **API Gateway**: Gesund, JWT-Validierung funktioniert
- ✅ **Ping Service**: Gesund, antwortet korrekt
- ✅ **PostgreSQL**: Gesund, Keycloak-Schema initialisiert
- ✅ **Gesamte Infrastruktur**: Consul, Redis, Monitoring - alles gesund
### Token-Details ✅
Generierte JWT-Token enthalten ordnungsgemäße Claims:
- **Issuer:** `http://localhost:8180/realms/meldestelle`
- **Client ID:** `api-gateway`
- **Realm-Rollen:** `USER`, `GUEST`, `offline_access`
- **Scope:** `profile email`
- **Ablaufzeit:** 300 Sekunden (5 Minuten)
## Aktuelle Authentifizierungsarchitektur
### Flow-Übersicht
1. **Client** fordert Token von Keycloak über Client-Credentials an
2. **Keycloak** validiert Client-Secret und stellt JWT-Token aus
3. **Client** inkludiert JWT-Token im Authorization-Header
4. **API Gateway** validiert JWT-Token mit Keycloak JWK-Endpunkt
5. **API Gateway** leitet Anfrage an Backend-Service weiter, wenn Token gültig
### Sicherheitsstatus
- ✅ **JWT-Token-Generierung:** Funktioniert mit ordnungsgemäßem Client-Secret
- ✅ **Token-Validierung:** API Gateway validiert Token gegen Keycloak
- ✅ **Ungültige Token blockieren:** Gibt HTTP 401 für ungültige Token zurück
- ⚠️ **Vollständige Durchsetzung:** Einige Routen erlauben noch unauthentifizierten Zugriff
## Zukünftige Verbesserungen
### 1. Vollständige Authentifizierungsdurchsetzung
- Alle API-Gateway-Routen so konfigurieren, dass sie Authentifizierung erfordern
- Unauthentifizierten Zugriff auf alle geschützten Endpunkte blockieren
- Ordnungsgemäße Fehlerantworten für fehlende Token implementieren
### 2. Produktionssicherheitshärtung
- Standard-Admin-Passwort in Realm-Konfiguration ändern
- HTTPS für Keycloak in Produktion aktivieren
- Ordnungsgemäße Hostname-Einstellungen für externen Zugriff konfigurieren
- Token-Refresh-Mechanismen implementieren
### 3. Erweiterte Funktionen
- Rollenbasierte Zugriffskontrolle (RBAC) hinzufügen
- Benutzerauthentifizierungsflows implementieren (nicht nur Client-Credentials)
- API-Ratenlimitierung und Missbrauchsschutz hinzufügen
- Token-Introspection für erweiterte Sicherheit konfigurieren
## Geänderte Konfigurationsdateien
### Hauptänderungen
- ✅ `docker-compose.yml` - Keycloak-Umgebung und API-Gateway-Client-Secret
- ✅ `docker/services/keycloak/meldestelle-realm.json` - Client-Secret-Konfiguration
- ✅ PostgreSQL Keycloak-Schema - Geleert und für frischen Import neu erstellt
### Erstellte Backup-Dateien
- ✅ `docker/services/keycloak/meldestelle-realm.json.backup` - Original-Konfiguration
---
**Implementierungsstatus: ✅ KERN-ANFORDERUNGEN ABGESCHLOSSEN**
**Nächste Phase: Produktionshärtung und vollständige Sicherheitsdurchsetzung**
**Authentifizierungsinfrastruktur: Stabil und betriebsbereit**
Tagebuch/AUTHENTICATION-IMPLEMENTATION.md
-140
View File
@@ -1,140 +0,0 @@
# Authentication Implementation Report
**Date:** 2025-10-05
**Status:** ✅ SUCCESSFULLY IMPLEMENTED - Core authentication infrastructure is operational
## Implementation Summary
Successfully implemented the three main requirements from the issue description:
1. ✅ **Fixed OpenID Configuration** - Resolved issuer URL problems
2. ✅ **Configured Client Secrets** - Set up proper api-gateway client authentication
3. ✅ **Enabled Authentication Enforcement** - JWT token validation working through API Gateway
## Changes Made
### 1. Fixed OpenID Configuration ✅
**Problem:** Keycloak OpenID discovery endpoint returned null issuer URLs
**Root Cause:** Complex hostname configuration and existing realm data preventing updates
**Solution:**
- Simplified Keycloak environment configuration in `docker-compose.yml`
- Removed problematic KC_HOSTNAME settings that caused startup issues
- Cleared PostgreSQL Keycloak schema to force fresh realm import
- Let Keycloak auto-detect hostname for proper OpenID discovery
**Current Configuration:**
```yaml
# docker-compose.yml - Keycloak environment
KC_HTTP_ENABLED: true
KC_HOSTNAME_STRICT: false
# Removed KC_HOSTNAME to allow auto-detection
```
### 2. Configured Client Secrets ✅
**Problem:** api-gateway client had placeholder secret, preventing authentication
**Solution:**
- Generated secure 32-character client secret: `K5RqonwVOaxPKaXVH4mbthSRbjRh5tOK`
- Updated `docker/services/keycloak/meldestelle-realm.json` with real client secret
- Added `KEYCLOAK_CLIENT_SECRET` environment variable to API Gateway configuration
- Forced fresh realm import to apply changes
**Files Modified:**
```yaml
# docker-compose.yml - API Gateway environment
KEYCLOAK_CLIENT_SECRET: K5RqonwVOaxPKaXVH4mbthSRbjRh5tOK
# meldestelle-realm.json - Client configuration
"secret": "K5RqonwVOaxPKaXVH4mbthSRbjRh5tOK"
```
### 3. Enabled Authentication Enforcement ✅
**Current Status:** Partial implementation - JWT validation working
**Implementation:**
- API Gateway properly validates JWT tokens from Keycloak
- Invalid tokens are rejected with HTTP 401
- Valid tokens allow access to protected endpoints
- Client credentials flow working end-to-end
## Verification Results ✅
### Authentication Flow Testing
```bash
# 1. Client Credentials Grant - ✅ SUCCESS
curl -X POST http://localhost:8180/realms/meldestelle/protocol/openid-connect/token \
-d "grant_type=client_credentials&client_id=api-gateway&client_secret=K5RqonwVOaxPKaXVH4mbthSRbjRh5tOK"
# Returns: Valid JWT token with 300s expiry
# 2. Valid Token Access - ✅ SUCCESS
curl -H "Authorization: Bearer $TOKEN" http://localhost:8081/api/ping/health
# Returns: {"status":"pong","service":"ping-service","healthy":true} HTTP 200
# 3. Invalid Token Access - ✅ SUCCESS (Blocked)
curl -H "Authorization: Bearer invalid-token" http://localhost:8081/api/ping/health
# Returns: HTTP 401 (Unauthorized)
# 4. No Token Access - ⚠️ PARTIAL
curl http://localhost:8081/api/ping/health
# Returns: HTTP 200 (Should be blocked for full security)
```
### System Status ✅
All services operational:
- ✅ **Keycloak**: Running, realm imported successfully
- ✅ **API Gateway**: Healthy, JWT validation working
- ✅ **Ping Service**: Healthy, responding correctly
- ✅ **PostgreSQL**: Healthy, Keycloak schema initialized
- ✅ **All Infrastructure**: Consul, Redis, monitoring - all healthy
### Token Details ✅
Generated JWT tokens contain proper claims:
- **Issuer:** `http://localhost:8180/realms/meldestelle`
- **Client ID:** `api-gateway`
- **Realm Roles:** `USER`, `GUEST`, `offline_access`
- **Scope:** `profile email`
- **Expiry:** 300 seconds (5 minutes)
## Current Authentication Architecture
### Flow Overview
1. **Client** requests token from Keycloak using client credentials
2. **Keycloak** validates client secret and issues JWT token
3. **Client** includes JWT token in Authorization header
4. **API Gateway** validates JWT token with Keycloak JWK endpoint
5. **API Gateway** routes request to backend service if token valid
### Security Status
- ✅ **JWT Token Generation:** Working with proper client secret
- ✅ **Token Validation:** API Gateway validates tokens against Keycloak
- ✅ **Invalid Token Blocking:** Returns HTTP 401 for invalid tokens
- ⚠️ **Complete Enforcement:** Some routes still allow unauthenticated access
## Future Enhancements
### 1. Complete Authentication Enforcement
- Configure all API Gateway routes to require authentication
- Block unauthenticated access to all protected endpoints
- Implement proper error responses for missing tokens
### 2. Production Security Hardening
- Change default admin password in realm configuration
- Enable HTTPS for Keycloak in production
- Configure proper hostname settings for external access
- Implement token refresh mechanisms
### 3. Advanced Features
- Add role-based access control (RBAC)
- Implement user authentication flows (not just client credentials)
- Add API rate limiting and abuse protection
- Configure token introspection for enhanced security
## Configuration Files Modified
### Primary Changes
- ✅ `docker-compose.yml` - Keycloak environment and API Gateway client secret
- ✅ `docker/services/keycloak/meldestelle-realm.json` - Client secret configuration
- ✅ PostgreSQL Keycloak schema - Cleared and recreated for fresh import
### Backup Files Created
- ✅ `docker/services/keycloak/meldestelle-realm.json.backup` - Original configuration
---
**Implementation Status: ✅ CORE REQUIREMENTS COMPLETED**
**Next Phase: Production hardening and complete security enforcement**
**Authentication Infrastructure: Stable and operational**
Tagebuch/Analyse_Infrastructure-Module_14-Okt-2025.md
-301
View File
@@ -1,301 +0,0 @@
### Vollständige Analyse der Infrastructure-Module
Ich habe eine umfassende Analyse aller Infrastructure-Module durchgeführt. Hier ist meine Bewertung der Implementierungen:
---
## Zusammenfassung
Die Infrastructure-Implementierung ist **insgesamt sehr gut strukturiert und professionell umgesetzt**. Die Architektur folgt modernen Best Practices mit klarer Trennung von API und Implementierung. Es gibt jedoch einige Inkonsistenzen und potenzielle Konflikte, die behoben werden sollten.
---
## Detaillierte Analyse nach Modulen
### ✅ Gateway Module - **Exzellent**
#### Stärken:
- **Vollständige API-Gateway-Implementierung** mit Spring Cloud Gateway
- **Moderne reaktive Architektur** (WebFlux, Netty)
- **Umfassende Cross-Cutting Concerns**:
- ✅ Correlation ID Filter für Request-Tracing
- ✅ Enhanced Logging Filter mit strukturiertem Logging
- ✅ Rate Limiting mit Memory-Leak-Schutz
- ✅ JWT-basierte Security mit Keycloak-Integration
- ✅ Circuit Breaker pro Service (Resilience4j)
- ✅ Retry-Mechanismen
- ✅ Fallback-Controller für Service-Ausfälle
- **Exzellentes Monitoring**:
- ✅ Custom Metrics mit Micrometer
- ✅ Pfad-Normalisierung zur Vermeidung von Kardinalitätsproblemen
- ✅ Prometheus-Integration
- ✅ Health Indicator für Downstream-Services
- **Vollständige CORS-Konfiguration**
- **Gute Test-Abdeckung** (7 Test-Dateien)
- **Detaillierte Dokumentation** (README-INFRA-GATEWAY.md)
#### Empfehlungen:
- ✅ Sehr gut: Separate Bean-Namen für Redis ConnectionFactory (`eventStoreRedisConnectionFactory`)
- ⚠️ Das Gateway importiert `redis-event-store` als Dependency (Zeile 32 in build.gradle.kts) - **ist das beabsichtigt?** Ein Gateway sollte normalerweise keinen Event Store benötigen.
---
### ✅ Cache Module - **Sehr gut**
#### Stärken:
- **Saubere API-Implementierung Trennung**:
- `cache-api`: Provider-agnostische Interfaces
- `redis-cache`: Konkrete Redis-Implementierung
- **Vollständige Cache-Features**:
- ✅ TTL-Unterstützung
- ✅ Connection State Tracking
- ✅ Health Monitoring
- ✅ Jackson-basierte Serialisierung
- **Redis-spezifische Properties** (`RedisProperties`) mit sinnvollen Defaults
- **Connection Pooling** aktiviert
- **@ConditionalOnMissingBean** für flexible Bean-Konfiguration
#### Empfehlungen:
- ✅ Keine Bean-Name-Konflikte mit Event Store (verwendet `redisConnectionFactory` ohne Qualifier)
- ⚠️ Beide Module (cache und event-store) verwenden unterschiedliche Property-Prefixe (`redis` vs `redis.event-store`) - **gut, aber sollte dokumentiert sein**
---
### ✅ Event Store Module - **Sehr gut**
#### Stärken:
- **Saubere API-Implementierung Trennung**:
- `event-store-api`: Provider-agnostische Interfaces
- `redis-event-store`: Redis Streams Implementierung
- **Event Sourcing Features**:
- ✅ Append Events mit Optimistic Locking
- ✅ Redis Streams für Pub/Sub
- ✅ Consumer Groups
- ✅ Event Replay-Fähigkeit
- ✅ Concurrency Exception Handling
- **Separate Redis Connection Factory** mit Qualifier (`eventStoreRedisConnectionFactory`)
- **Eigene Properties** (`RedisEventStoreProperties`) mit Prefix `redis.event-store`
- **Gute Integration** mit core-domain (DomainEvent)
#### Potenzielle Konflikte:
- ⚠️ **WICHTIG**: Beide Redis-Module (cache + event-store) könnten Konflikte verursachen, wenn sie im selben Service verwendet werden:
- Unterschiedliche ConnectionFactory-Namen verwendet ✅
- Unterschiedliche Template-Namen (`redisTemplate` vs `eventStoreRedisTemplate`) ✅
- Unterschiedliche Property-Prefixe ✅
- **Aber**: Beide verwenden Jackson-Serializer - könnte zu Konflikten führen wenn unterschiedliche Konfigurationen benötigt werden
---
### ⚠️ Auth Module - **Gut, aber Inkonsistenzen**
#### Stärken:
- **Keycloak-Integration** für Benutzerverwaltung
- **Spring Security OAuth2 Resource Server**
- **Actuator-Endpunkte** für Health Checks
#### ⚠️ **Inkonsistenzen gefunden**:
1. **Consul Discovery deaktiviert** (`enabled: false` in application.yml)
- Gateway erwartet `lb://auth-service` für Load Balancing
- Auth-Server registriert sich **nicht** in Consul
- **Folge**: Gateway kann auth-service nicht finden! ❌
- **Lösung**: Entweder Consul aktivieren ODER Gateway-Routing auf feste URL ändern
2. **Minimale Management-Endpunkte**
- Nur `health` und `info` exponiert
- Andere Services haben mehr Monitoring-Endpunkte
- **Empfehlung**: Konsistenz mit anderen Services herstellen
3. **Keine Monitoring-Client-Dependency**
- Andere Services nutzen `monitoring-client` Bundle
- Auth-Server hat eigene manuelle Konfiguration
- **Empfehlung**: Wiederverwendung des `monitoring-client` Moduls
---
### ✅ Messaging Module - **Sehr gut**
#### Stärken:
- **Klare Trennung**:
- `messaging-config`: Zentrale Kafka-Konfiguration
- `messaging-client`: High-Level Producer/Consumer
- **Reactor Kafka** für reaktive Streams
- **Wiederverwendbare Konfiguration**
- **Korrekt als Library konfiguriert** (bootJar disabled)
---
### ✅ Monitoring Module - **Sehr gut**
#### Stärken:
- **Klare Trennung**:
- `monitoring-client`: Wiederverwendbare Library für alle Services
- `monitoring-server`: Eigenständiger Zipkin-Server
- **Vollständiges Stack**:
- ✅ Micrometer + Prometheus
- ✅ Zipkin Tracing
- ✅ Spring Boot Actuator
- **Bundle-basierte Dependencies** - sehr wartbar
---
## 🔴 Kritische Probleme
### 1. **Auth-Service nicht in Consul registriert**
```yaml
# infrastructure/auth/auth-server/src/main/resources/application.yml
spring:
cloud:
consul:
discovery:
enabled: false # ❌ PROBLEM
```
**Aber Gateway erwartet:**
```yaml
# infrastructure/gateway/src/main/resources/application.yml
- id: auth-service-route
uri: lb://auth-service # ❌ Kann nicht aufgelöst werden!
```
**Auswirkung**: Gateway kann Auth-Service nicht erreichen!
**Lösungsoptionen**:
- **Option A** (empfohlen): Consul Discovery im Auth-Server aktivieren
- **Option B**: Gateway-Route auf feste URL ändern: `uri: http://localhost:8087`
---
### 2. **Gateway importiert redis-event-store**
```kotlin
// infrastructure/gateway/build.gradle.kts:32
implementation(project(":infrastructure:event-store:redis-event-store"))
```
**Frage**: Warum benötigt das Gateway einen Event Store?
- ❓ Wird für Gateway-eigene Events verwendet?
- ❓ Historische Dependency, die nicht mehr benötigt wird?
**Empfehlung**:
- Falls nicht benötigt: Dependency entfernen
- Falls benötigt: Dokumentieren, wofür das Gateway Events speichert
---
## ⚠️ Potenzielle Konflikte
### 1. **Redis-Module Nebeneinander**
Wenn ein Service **beide** Redis-Module verwendet (`redis-cache` + `redis-event-store`):
**Gut gelöst**:
- ✅ Separate ConnectionFactory-Namen
- ✅ Separate Template-Namen
- ✅ Separate Property-Prefixe
**Potenzielle Probleme**:
- ⚠️ Beide verwenden Jackson-Serializer - könnte theoretisch kollidieren
- ⚠️ Beide verwenden gleiche Redis-Instanz mit unterschiedlichen Databases
- ⚠️ Dokumentation fehlt für gleichzeitige Nutzung
**Empfehlung**:
```kotlin
// Dokumentieren in README oder Code-Kommentaren:
// WICHTIG: redis-cache verwendet Database 0
// WICHTIG: redis-event-store verwendet Database 1 (oder configure via properties)
```
---
### 2. **Inkonsistente build.gradle.kts Patterns**
**Verschiedene Ansätze für Library-Module**:
```kotlin
// messaging-config/build.gradle.kts
tasks.getByName("bootJar") {
enabled = false
}
// redis-event-store/build.gradle.kts
tasks.bootJar {
enabled = false
}
tasks.jar {
enabled = true
}
// cache-api/build.gradle.kts
// Kein Spring Boot Plugin, daher keine bootJar-Tasks
```
**Empfehlung**: Konsistenten Ansatz wählen und dokumentieren.
---
## ✅ Sehr Gute Architektur-Entscheidungen
### 1. **Konsequente API-Implementierung Trennung**
```
infrastructure/
cache/
cache-api/ # ✅ Interfaces
redis-cache/ # ✅ Implementierung
event-store/
event-store-api/ # ✅ Interfaces
redis-event-store/ # ✅ Implementierung
```
### 2. **Platform-Module für zentrale Abhängigkeiten**
```kotlin
implementation(platform(projects.platform.platformBom))
implementation(projects.platform.platformDependencies)
```
### 3. **Bundle-basierte Dependencies**
```kotlin
implementation(libs.bundles.redis.cache)
implementation(libs.bundles.kafka.config)
implementation(libs.bundles.monitoring.client)
```
### 4. **Qualifier für Bean-Konflikte**
```kotlin
@Bean
@ConditionalOnMissingBean(name = ["eventStoreRedisConnectionFactory"])
fun eventStoreRedisConnectionFactory(...)
@Qualifier("eventStoreRedisConnectionFactory")
```
---
## 📋 Zusammenfassung: Zu behebende Punkte
### 🔴 Kritisch (Breaking Issues):
1. **Auth-Service Consul-Registration** aktivieren oder Gateway-Route anpassen
2. **Gateway redis-event-store Dependency** klären/entfernen
### ⚠️ Wichtig (Inkonsistenzen):
3. **Auth-Server Monitoring** - `monitoring-client` verwenden für Konsistenz
4. **Redis-Module Dokumentation** - Gleichzeitige Nutzung dokumentieren
5. **Build-Script-Patterns** vereinheitlichen
### ℹ️ Optional (Verbesserungen):
6. Zentrale `application.yml` Properties dokumentieren
7. Integration-Tests für Redis-Modul-Kombinationen
8. OpenAPI/Swagger für auth-server hinzufügen (wie bei Gateway dokumentiert)
---
## 🎯 Gesamtbewertung
| Modul | Bewertung | Status |
|-------|-----------|--------|
| Gateway | ⭐⭐⭐⭐⭐ | Exzellent |
| Cache (API + Redis) | ⭐⭐⭐⭐⭐ | Sehr gut |
| Event Store (API + Redis) | ⭐⭐⭐⭐⭐ | Sehr gut |
| Messaging | ⭐⭐⭐⭐⭐ | Sehr gut |
| Monitoring | ⭐⭐⭐⭐⭐ | Sehr gut |
| Auth-Server | ⭐⭐⭐⭐ | Gut (Inkonsistenzen) |
**Gesamteindruck**: Die Infrastructure ist **professionell implementiert** mit modernen Best Practices. Die wenigen gefundenen Probleme sind spezifisch und klar identifizierbar - hauptsächlich Konfigurationsprobleme, keine grundlegenden Architekturprobleme.
Tagebuch/DOCKER-OPTIMIZATION-DE.md
-427
View File
@@ -1,427 +0,0 @@
# Docker-Konfigurations-Optimierung & Sicherheitsanalyse
## Zusammenfassung
Dieses Dokument beschreibt die umfassende Analyse, Korrekturen und Optimierungen, die an allen Docker- und docker-compose-Konfigurationen im Meldestelle-Projekt vorgenommen wurden. Die Optimierungen konzentrieren sich auf **Sicherheitshärtung**, **Leistungsverbesserungen** und **Produktionsbereitschaft**.
### Wichtigste Errungenschaften
- ✅ **Kritische Sicherheitsvulnerabilitäten behoben**: Eliminierung von fest kodierten Anmeldedaten und exponierten Geheimnissen
- ✅ **Ressourcenverwaltung**: Umfassende CPU- und Speicherlimits für alle Services hinzugefügt
- ✅ **Sicherheitshärtung**: Docker Secrets, Nicht-Root-Benutzer und Sicherheitsbeschränkungen implementiert
- ✅ **Leistungsoptimierung**: Verbesserte Health Checks, Startabhängigkeiten und Ressourcenzuteilung
- ✅ **Produktionsbereitschaft**: Ordnungsgemäße Volume-Verwaltung, Netzwerke und Monitoring hinzugefügt
---
## Sicherheitsverbesserungen
### 🔐 Behobene kritische Sicherheitsprobleme
#### 1. **Geheimnisse-Verwaltung**
**Problem**: Fest kodierte Anmeldedaten in Umgebungsvariablen
```yaml
# VORHER (UNSICHER)
environment:
POSTGRES_PASSWORD: meldestelle
KEYCLOAK_CLIENT_SECRET: K5RqonwVOaxPKaXVH4mbthSRbjRh5tOK
GF_SECURITY_ADMIN_PASSWORD: admin
```
**Lösung**: Docker Secrets mit sicherem dateibasiertem Management
```yaml
# NACHHER (SICHER)
environment:
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
KEYCLOAK_CLIENT_SECRET_FILE: /run/secrets/keycloak_client_secret
GF_SECURITY_ADMIN_PASSWORD__FILE: /run/secrets/grafana_admin_password
secrets:
- postgres_password
- keycloak_client_secret
- grafana_admin_password
```
#### 2. **Container-Sicherheitshärtung**
**Hinzugefügte Sicherheitsmaßnahmen**:
- `no-new-privileges:true` für alle Container
- Nicht-Root-Benutzer-Ausführung wo möglich
- Schreibgeschützte Volume-Mounts für Konfigurationsdateien
- Sichere Dateiberechtigungen (600) für alle Secrets
#### 3. **Netzwerksicherheit**
**Verbesserungen**:
- Benutzerdefiniertes isoliertes Netzwerk mit dediziertem Subnetz (172.20.0.0/16)
- Ordnungsgemäße Inter-Container-Kommunikationskontrollen
- Verbesserte CORS- und Sicherheits-Header für Webanwendungen
### 🛡️ Hinzugefügte Sicherheitsfunktionen
| Sicherheitsfunktion | Implementierung | Nutzen |
|-------------------|-----------------|---------|
| Docker Secrets | Dateibasiertes Secrets-Management | Eliminiert fest kodierte Anmeldedaten |
| Nicht-Root-Benutzer | Benutzerdefinierte Benutzer/Gruppe für Anwendungen | Reduziert Angriffsfläche |
| Sicherheitsoptionen | `no-new-privileges` Flag | Verhindert Privilegien-Eskalation |
| Schreibgeschützte Mounts | Konfigurationsdateien schreibgeschützt gemountet | Verhindert Laufzeit-Manipulation |
| Netzwerkisolation | Benutzerdefiniertes Bridge-Netzwerk | Isoliert Container-Kommunikation |
| Ressourcenlimits | CPU/Speicher-Beschränkungen | Verhindert Ressourcenerschöpfungsangriffe |
---
## Leistungsoptimierungen
### 🚀 Ressourcenverwaltung
#### Umfassende Ressourcenlimits
Alle Services haben jetzt ordnungsgemäß konfigurierte Ressourcenlimits und Reservierungen:
**Infrastruktur-Services**:
```yaml
deploy:
resources:
limits:
cpus: '2.0'
memory: 2G
reservations:
cpus: '0.5'
memory: 1G
```
**Ressourcenzuteilungsübersicht**:
| Service | CPU-Limit | Speicher-Limit | CPU-Reserviert | Speicher-Reserviert |
|---------|-----------|----------------|----------------|-------------------|
| PostgreSQL | 2.0 | 2GB | 0.5 | 512MB |
| Redis | 1.0 | 1GB | 0.25 | 256MB |
| Keycloak | 2.0 | 2GB | 0.5 | 1GB |
| API Gateway | 2.0 | 2GB | 0.5 | 1GB |
| Kafka | 2.0 | 2GB | 0.5 | 512MB |
| Grafana | 1.0 | 1GB | 0.25 | 256MB |
| Prometheus | 1.0 | 2GB | 0.25 | 512MB |
### 🔧 Leistungsverbesserungen
#### 1. **Optimierte Health Checks**
```yaml
# Verbesserte Health Check-Konfiguration
healthcheck:
test: ["CMD", "curl", "--fail", "--max-time", "5", "http://localhost:8080/health/ready"]
interval: 15s
timeout: 10s
retries: 3
start_period: 60s
```
#### 2. **JVM-Optimierung**
**Kafka JVM-Einstellungen**:
```yaml
environment:
KAFKA_HEAP_OPTS: "-Xmx1G -Xms512m"
KAFKA_JVM_PERFORMANCE_OPTS: "-XX:+UseG1GC -XX:MaxGCPauseMillis=20 -XX:InitiatingHeapOccupancyPercent=35"
```
#### 3. **Datenbankleistung**
**PostgreSQL-Verbesserungen**:
- SCRAM-SHA-256-Authentifizierung für bessere Sicherheit
- Optimierte Verbindungseinstellungen
- Ordnungsgemäße Datenpersistenz mit Bind-Mounts
**Redis-Optimierungen**:
- Speicherverwaltung mit `maxmemory` und `allkeys-lru` Policy
- Persistenter Speicher mit AOF (Append Only File)
- Authentifizierung aktiviert
---
## Konfigurationsstruktur
### 📁 Dateiorganisation
Die optimierte Konfiguration besteht aus:
```
├── docker-compose.yml.optimized # Infrastruktur-Services
├── docker-compose.services.yml.optimized # Microservices
├── docker-compose.clients.yml.optimized # Client-Anwendungen
├── .env.template # Umgebungskonfigurations-Template
└── docker/
└── secrets/
├── setup-secrets.sh # Automatisierte Secrets-Generierung
├── postgres_user.txt # Datenbank-Benutzername
├── postgres_password.txt # Datenbank-Passwort (generiert)
├── redis_password.txt # Redis-Passwort (generiert)
├── keycloak_admin_password.txt # Keycloak-Admin-Passwort (generiert)
├── keycloak_client_secret.txt # API-Gateway-Client-Secret (generiert)
├── grafana_admin_user.txt # Grafana-Admin-Benutzername
├── grafana_admin_password.txt # Grafana-Admin-Passwort (generiert)
├── jwt_secret.txt # JWT-Signatur-Secret (generiert)
└── vnc_password.txt # VNC-Zugriffs-Passwort (generiert)
```
### 🔄 Profilbasiertes Deployment
Die optimierte Konfiguration unterstützt selektives Service-Deployment:
```bash
# Nur Infrastruktur
docker-compose -f docker-compose.yml.optimized up -d
# Infrastruktur + Microservices
docker-compose -f docker-compose.yml.optimized \
-f docker-compose.services.yml.optimized up -d
# Vollständiges Stack-Deployment
docker-compose -f docker-compose.yml.optimized \
-f docker-compose.services.yml.optimized \
-f docker-compose.clients.yml.optimized up -d
# Selektive Services mit Profilen
docker-compose -f docker-compose.services.yml.optimized \
--profile members --profile horses up -d
```
---
## Migrationsleitfaden
### 🚀 Schnellstart
#### 1. **Secrets generieren**
```bash
# Alle erforderlichen Secrets generieren
./docker/secrets/setup-secrets.sh --all
# Oder einzeln generieren
./docker/secrets/setup-secrets.sh --generate
./docker/secrets/setup-secrets.sh --validate
```
#### 2. **Umgebung konfigurieren**
```bash
# Template kopieren und anpassen
cp .env.template .env
# Konfigurationswerte bearbeiten
nano .env
```
#### 3. **Datenverzeichnisse erstellen**
```bash
# Persistente Datenverzeichnisse erstellen
mkdir -p ./data/{postgres,redis,prometheus,grafana,keycloak,consul,monitoring,desktop-app}
```
#### 4. **Services deployen**
```bash
# Infrastruktur starten
docker-compose -f docker-compose.yml.optimized up -d
# Alle Services auf Gesundheit prüfen
docker-compose -f docker-compose.yml.optimized ps
# Microservices hinzufügen
docker-compose -f docker-compose.yml.optimized \
-f docker-compose.services.yml.optimized up -d
# Client-Anwendungen hinzufügen
docker-compose -f docker-compose.yml.optimized \
-f docker-compose.services.yml.optimized \
-f docker-compose.clients.yml.optimized up -d
```
### 🔄 Migration von Original-Konfiguration
#### Schritt 1: Aktuelle Einrichtung sichern
```bash
# Bestehende Services stoppen
docker-compose down
# Aktuelle Daten sichern (optional)
cp -r data/ data.backup/
```
#### Schritt 2: Konfiguration aktualisieren
```bash
# Zuerst Secrets generieren
./docker/secrets/setup-secrets.sh --all
# Umgebungskonfiguration aktualisieren
cp .env.template .env
# .env nach Bedarf bearbeiten
```
#### Schritt 3: Optimierte Konfiguration deployen
```bash
# Mit neuer Konfiguration deployen
docker-compose -f docker-compose.yml.optimized up -d
```
---
## Sicherheits-Best-Practices
### 🛡️ Produktionssicherheits-Checkliste
- [ ] **Secrets generiert**: Secrets-Setup-Script ausführen
- [ ] **Dateiberechtigungen**: Secret-Dateien haben 600-Berechtigungen
- [ ] **Netzwerkisolation**: Benutzerdefinierte Docker-Netzwerke verwenden
- [ ] **Ressourcenlimits**: Alle Services haben CPU/Speicher-Limits
- [ ] **Nicht-Root-Benutzer**: Anwendungen laufen als nicht-privilegierte Benutzer
- [ ] **Schreibgeschützte Mounts**: Konfiguration schreibgeschützt gemountet
- [ ] **Sicherheitsoptionen**: `no-new-privileges` aktiviert
- [ ] **Health Checks**: Alle kritischen Services haben Health Checks
- [ ] **Backup-Strategie**: Regelmäßige Daten-Backups konfiguriert
- [ ] **Monitoring**: Prometheus und Grafana konfiguriert
- [ ] **Log-Management**: Zentralisiertes Logging konfiguriert
### 🔐 Sicherheitsmonitoring
#### Zugriffs-URLs (Standard-Konfiguration)
- **Grafana Dashboard**: http://localhost:3000
- **Prometheus Metriken**: http://localhost:9090
- **Consul UI**: http://localhost:8500
- **Keycloak Admin**: http://localhost:8180/admin
#### Zu überwachende Sicherheitsmetriken
- Fehlgeschlagene Authentifizierungsversuche
- Ressourcennutzungsmuster
- Container-Neustart-Häufigkeit
- Netzwerkverbindungsanomalien
- Secret-Zugriffsmuster
---
## Fehlerbehebung
### 🔍 Häufige Probleme und Lösungen
#### Problem 1: Secret-Dateiberechtigungen
**Problem**: Container können Secret-Dateien nicht lesen
**Lösung**:
```bash
# Berechtigungen korrigieren
chmod 600 docker/secrets/*.txt
# Oder mit korrekten Berechtigungen neu generieren
./docker/secrets/setup-secrets.sh --force
```
#### Problem 2: Ressourcenbeschränkungen
**Problem**: Services schlagen aufgrund von Ressourcenlimits fehl
**Lösung**:
```bash
# Ressourcennutzung prüfen
docker stats
# Limits in docker-compose-Dateien anpassen oder Systemressourcen erhöhen
```
#### Problem 3: Netzwerkkonnektivität
**Problem**: Services können nicht kommunizieren
**Lösung**:
```bash
# Netzwerkkonfiguration prüfen
docker network inspect meldestelle_meldestelle-network
# Service-Gesundheit überprüfen
docker-compose -f docker-compose.yml.optimized ps
```
#### Problem 4: Volume-Mount-Probleme
**Problem**: Daten persistieren nicht oder Berechtigungsfehler
**Lösung**:
```bash
# Datenverzeichnisse mit korrekten Berechtigungen erstellen
mkdir -p ./data/{postgres,redis,prometheus,grafana,keycloak,consul}
chown -R 999:999 ./data/postgres # PostgreSQL-Benutzer
chown -R 472:0 ./data/grafana # Grafana-Benutzer
```
### 📊 Health Check-Befehle
```bash
# Alle Service-Status prüfen
docker-compose -f docker-compose.yml.optimized ps
# Service-Logs anzeigen
docker-compose -f docker-compose.yml.optimized logs [service-name]
# Ressourcennutzung prüfen
docker stats
# Secrets validieren
./docker/secrets/setup-secrets.sh --validate
# Konnektivität testen
docker exec meldestelle-api-gateway curl -f http://postgres:5432
```
---
## Leistungstuning
### 🎯 Ressourcenoptimierungs-Richtlinien
#### Speicherzuteilungsstrategie
1. **Infrastruktur-Services**: Höhere Speicherzuteilung für Datenbanken und Messaging
2. **Anwendungs-Services**: Ausgewogene CPU/Speicher für Microservices
3. **Client-Anwendungen**: Geringere Ressourcenanforderungen
#### CPU-Zuteilungsstrategie
1. **I/O-gebundene Services** (Datenbank, Redis): Moderate CPU, hoher Speicher
2. **Rechenintensive Services** (Anwendungslogik): Höhere CPU-Zuteilung
3. **Statische Inhalts-Services** (Web-Apps): Geringere Gesamtressourcen
#### JVM-Tuning für Java-Services
```yaml
environment:
JAVA_OPTS: |
-XX:MaxRAMPercentage=75.0
-XX:+UseG1GC
-XX:+UseStringDeduplication
-XX:+UseContainerSupport
-Djava.security.egd=file:/dev/./urandom
```
---
## Monitoring und Observability
### 📈 Metriken-Sammlung
#### Prometheus-Metriken
- Container-Ressourcennutzung
- Anwendungsleistungsmetriken
- Health Check-Status
- Netzwerkverkehrsmuster
#### Grafana-Dashboards
- Infrastruktur-Übersicht
- Anwendungsleistung
- Sicherheitsereignisse
- Ressourcennutzungstrends
#### Logging-Strategie
- Zentralisiertes Logging über Docker-Logs
- Strukturiertes JSON-Logging für Anwendungen
- Log-Rotation und Aufbewahrungsrichtlinien
- Sicherheitsereignis-Logging
---
## Fazit
Die Docker-Konfigurationsoptimierung bietet:
1. **Verbesserte Sicherheit**: Vollständige Eliminierung fest kodierter Anmeldedaten und Implementierung von Docker Secrets
2. **Produktionsbereitschaft**: Umfassende Ressourcenlimits, Health Checks und Monitoring
3. **Verbesserte Leistung**: Optimierte Ressourcenzuteilung und Container-Konfigurationen
4. **Operational Excellence**: Automatisiertes Secret-Management, umfassende Dokumentation und Fehlerbehebungsleitfäden
5. **Skalierbarkeit**: Profilbasiertes Deployment und modulare Service-Architektur
### Nächste Schritte
1. **Optimierte Konfiguration deployen** in Entwicklungsumgebung
2. **Alle Sicherheitsmaßnahmen validieren** sind ordnungsgemäß implementiert
3. **Leistungsmetriken überwachen** und Ressourcenlimits nach Bedarf anpassen
4. **Backup- und Wiederherstellungsverfahren implementieren** für persistente Daten
5. **Automatisiertes Monitoring und Alerting einrichten** für Produktions-Deployment
Bei Fragen oder Problemen mit der optimierten Konfiguration beziehen Sie sich auf den Fehlerbehebungsabschnitt oder konsultieren Sie die detaillierten Konfigurationskommentare in den docker-compose-Dateien.
Tagebuch/DOCKER-OPTIMIZATION.md
-427
View File
@@ -1,427 +0,0 @@
# Docker Configuration Optimization & Security Analysis
## Executive Summary
This document outlines the comprehensive analysis, corrections, and optimizations made to all Docker and docker-compose configurations in the Meldestelle project. The optimizations focus on **security hardening**, **performance improvements**, and **production readiness**.
### Key Achievements
- ✅ **Critical Security Vulnerabilities Fixed**: Eliminated hardcoded credentials and exposed secrets
- ✅ **Resource Management**: Added comprehensive CPU and memory limits for all services
- ✅ **Security Hardening**: Implemented Docker secrets, non-root users, and security constraints
- ✅ **Performance Optimization**: Enhanced health checks, startup dependencies, and resource allocation
- ✅ **Production Readiness**: Added proper volume management, networking, and monitoring
---
## Security Improvements
### 🔐 Critical Security Issues Resolved
#### 1. **Secrets Management**
**Problem**: Hardcoded credentials in environment variables
```yaml
# BEFORE (INSECURE)
environment:
POSTGRES_PASSWORD: meldestelle
KEYCLOAK_CLIENT_SECRET: K5RqonwVOaxPKaXVH4mbthSRbjRh5tOK
GF_SECURITY_ADMIN_PASSWORD: admin
```
**Solution**: Docker secrets with secure file-based management
```yaml
# AFTER (SECURE)
environment:
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
KEYCLOAK_CLIENT_SECRET_FILE: /run/secrets/keycloak_client_secret
GF_SECURITY_ADMIN_PASSWORD__FILE: /run/secrets/grafana_admin_password
secrets:
- postgres_password
- keycloak_client_secret
- grafana_admin_password
```
#### 2. **Container Security Hardening**
**Added Security Measures**:
- `no-new-privileges:true` for all containers
- Non-root user execution where possible
- Read-only volume mounts for configuration files
- Secure file permissions (600) for all secrets
#### 3. **Network Security**
**Improvements**:
- Custom isolated network with dedicated subnet (172.20.0.0/16)
- Proper inter-container communication controls
- Enhanced CORS and security headers for web applications
### 🛡️ Security Features Added
| Security Feature | Implementation | Benefit |
|-----------------|----------------|---------|
| Docker Secrets | File-based secrets management | Eliminates hardcoded credentials |
| Non-root Users | Custom user/group for applications | Reduces attack surface |
| Security Options | `no-new-privileges` flag | Prevents privilege escalation |
| Read-only Mounts | Config files mounted read-only | Prevents runtime tampering |
| Network Isolation | Custom bridge network | Isolates container communication |
| Resource Limits | CPU/Memory constraints | Prevents resource exhaustion attacks |
---
## Performance Optimizations
### 🚀 Resource Management
#### Comprehensive Resource Limits
All services now have properly configured resource limits and reservations:
**Infrastructure Services**:
```yaml
deploy:
resources:
limits:
cpus: '2.0'
memory: 2G
reservations:
cpus: '0.5'
memory: 1G
```
**Resource Allocation Summary**:
| Service | CPU Limit | Memory Limit | CPU Reserved | Memory Reserved |
|---------|-----------|--------------|--------------|-----------------|
| PostgreSQL | 2.0 | 2GB | 0.5 | 512MB |
| Redis | 1.0 | 1GB | 0.25 | 256MB |
| Keycloak | 2.0 | 2GB | 0.5 | 1GB |
| API Gateway | 2.0 | 2GB | 0.5 | 1GB |
| Kafka | 2.0 | 2GB | 0.5 | 512MB |
| Grafana | 1.0 | 1GB | 0.25 | 256MB |
| Prometheus | 1.0 | 2GB | 0.25 | 512MB |
### 🔧 Performance Enhancements
#### 1. **Optimized Health Checks**
```yaml
# Enhanced health check configuration
healthcheck:
test: ["CMD", "curl", "--fail", "--max-time", "5", "http://localhost:8080/health/ready"]
interval: 15s
timeout: 10s
retries: 3
start_period: 60s
```
#### 2. **JVM Optimization**
**Kafka JVM Settings**:
```yaml
environment:
KAFKA_HEAP_OPTS: "-Xmx1G -Xms512m"
KAFKA_JVM_PERFORMANCE_OPTS: "-XX:+UseG1GC -XX:MaxGCPauseMillis=20 -XX:InitiatingHeapOccupancyPercent=35"
```
#### 3. **Database Performance**
**PostgreSQL Enhancements**:
- SCRAM-SHA-256 authentication for better security
- Optimized connection settings
- Proper data persistence with bind mounts
**Redis Optimizations**:
- Memory management with `maxmemory` and `allkeys-lru` policy
- Persistent storage with AOF (Append Only File)
- Authentication enabled
---
## Configuration Structure
### 📁 File Organization
The optimized configuration consists of:
```
├── docker-compose.yml.optimized # Infrastructure services
├── docker-compose.services.yml.optimized # Microservices
├── docker-compose.clients.yml.optimized # Client applications
├── .env.template # Environment configuration template
└── docker/
└── secrets/
├── setup-secrets.sh # Automated secrets generation
├── postgres_user.txt # Database username
├── postgres_password.txt # Database password (generated)
├── redis_password.txt # Redis password (generated)
├── keycloak_admin_password.txt # Keycloak admin password (generated)
├── keycloak_client_secret.txt # API Gateway client secret (generated)
├── grafana_admin_user.txt # Grafana admin username
├── grafana_admin_password.txt # Grafana admin password (generated)
├── jwt_secret.txt # JWT signing secret (generated)
└── vnc_password.txt # VNC access password (generated)
```
### 🔄 Profile-based Deployment
The optimized configuration supports selective service deployment:
```bash
# Infrastructure only
docker-compose -f docker-compose.yml.optimized up -d
# Infrastructure + Microservices
docker-compose -f docker-compose.yml.optimized \
-f docker-compose.services.yml.optimized up -d
# Full stack deployment
docker-compose -f docker-compose.yml.optimized \
-f docker-compose.services.yml.optimized \
-f docker-compose.clients.yml.optimized up -d
# Selective services with profiles
docker-compose -f docker-compose.services.yml.optimized \
--profile members --profile horses up -d
```
---
## Migration Guide
### 🚀 Quick Start
#### 1. **Generate Secrets**
```bash
# Generate all required secrets
./docker/secrets/setup-secrets.sh --all
# Or generate individually
./docker/secrets/setup-secrets.sh --generate
./docker/secrets/setup-secrets.sh --validate
```
#### 2. **Configure Environment**
```bash
# Copy template and customize
cp .env.template .env
# Edit configuration values
nano .env
```
#### 3. **Create Data Directories**
```bash
# Create persistent data directories
mkdir -p ./data/{postgres,redis,prometheus,grafana,keycloak,consul,monitoring,desktop-app}
```
#### 4. **Deploy Services**
```bash
# Start infrastructure
docker-compose -f docker-compose.yml.optimized up -d
# Verify all services are healthy
docker-compose -f docker-compose.yml.optimized ps
# Add microservices
docker-compose -f docker-compose.yml.optimized \
-f docker-compose.services.yml.optimized up -d
# Add client applications
docker-compose -f docker-compose.yml.optimized \
-f docker-compose.services.yml.optimized \
-f docker-compose.clients.yml.optimized up -d
```
### 🔄 Migration from Original Configuration
#### Step 1: Backup Current Setup
```bash
# Stop existing services
docker-compose down
# Backup current data (optional)
cp -r data/ data.backup/
```
#### Step 2: Update Configuration
```bash
# Generate secrets first
./docker/secrets/setup-secrets.sh --all
# Update environment configuration
cp .env.template .env
# Edit .env as needed
```
#### Step 3: Deploy Optimized Configuration
```bash
# Deploy with new configuration
docker-compose -f docker-compose.yml.optimized up -d
```
---
## Security Best Practices
### 🛡️ Production Security Checklist
- [ ] **Secrets Generated**: Run secrets setup script
- [ ] **File Permissions**: Ensure secret files have 600 permissions
- [ ] **Network Isolation**: Use custom Docker networks
- [ ] **Resource Limits**: All services have CPU/memory limits
- [ ] **Non-root Users**: Applications run as non-privileged users
- [ ] **Read-only Mounts**: Configuration mounted read-only
- [ ] **Security Options**: `no-new-privileges` enabled
- [ ] **Health Checks**: All critical services have health checks
- [ ] **Backup Strategy**: Regular data backups configured
- [ ] **Monitoring**: Prometheus and Grafana configured
- [ ] **Log Management**: Centralized logging configured
### 🔐 Security Monitoring
#### Access URLs (Default Configuration)
- **Grafana Dashboard**: http://localhost:3000
- **Prometheus Metrics**: http://localhost:9090
- **Consul UI**: http://localhost:8500
- **Keycloak Admin**: http://localhost:8180/admin
#### Security Metrics to Monitor
- Failed authentication attempts
- Resource usage patterns
- Container restart frequency
- Network connection anomalies
- Secret access patterns
---
## Troubleshooting
### 🔍 Common Issues and Solutions
#### Issue 1: Secret File Permissions
**Problem**: Containers cannot read secret files
**Solution**:
```bash
# Fix permissions
chmod 600 docker/secrets/*.txt
# Or regenerate with correct permissions
./docker/secrets/setup-secrets.sh --force
```
#### Issue 2: Resource Constraints
**Problem**: Services failing due to resource limits
**Solution**:
```bash
# Check resource usage
docker stats
# Adjust limits in docker-compose files or increase system resources
```
#### Issue 3: Network Connectivity
**Problem**: Services cannot communicate
**Solution**:
```bash
# Check network configuration
docker network inspect meldestelle_meldestelle-network
# Verify service health
docker-compose -f docker-compose.yml.optimized ps
```
#### Issue 4: Volume Mount Issues
**Problem**: Data not persisting or permission errors
**Solution**:
```bash
# Create data directories with correct permissions
mkdir -p ./data/{postgres,redis,prometheus,grafana,keycloak,consul}
chown -R 999:999 ./data/postgres # PostgreSQL user
chown -R 472:0 ./data/grafana # Grafana user
```
### 📊 Health Check Commands
```bash
# Check all service status
docker-compose -f docker-compose.yml.optimized ps
# View service logs
docker-compose -f docker-compose.yml.optimized logs [service-name]
# Check resource usage
docker stats
# Validate secrets
./docker/secrets/setup-secrets.sh --validate
# Test connectivity
docker exec meldestelle-api-gateway curl -f http://postgres:5432
```
---
## Performance Tuning
### 🎯 Resource Optimization Guidelines
#### Memory Allocation Strategy
1. **Infrastructure Services**: Higher memory allocation for databases and messaging
2. **Application Services**: Balanced CPU/memory for microservices
3. **Client Applications**: Lower resource requirements
#### CPU Allocation Strategy
1. **I/O Bound Services** (Database, Redis): Moderate CPU, high memory
2. **Compute Bound Services** (Application logic): Higher CPU allocation
3. **Static Content Services** (Web apps): Lower overall resources
#### JVM Tuning for Java Services
```yaml
environment:
JAVA_OPTS: |
-XX:MaxRAMPercentage=75.0
-XX:+UseG1GC
-XX:+UseStringDeduplication
-XX:+UseContainerSupport
-Djava.security.egd=file:/dev/./urandom
```
---
## Monitoring and Observability
### 📈 Metrics Collection
#### Prometheus Metrics
- Container resource usage
- Application performance metrics
- Health check status
- Network traffic patterns
#### Grafana Dashboards
- Infrastructure overview
- Application performance
- Security events
- Resource utilization trends
#### Logging Strategy
- Centralized logging via Docker logs
- Structured JSON logging for applications
- Log rotation and retention policies
- Security event logging
---
## Conclusion
The Docker configuration optimization provides:
1. **Enhanced Security**: Complete elimination of hardcoded credentials and implementation of Docker secrets
2. **Production Readiness**: Comprehensive resource limits, health checks, and monitoring
3. **Improved Performance**: Optimized resource allocation and container configurations
4. **Operational Excellence**: Automated secret management, comprehensive documentation, and troubleshooting guides
5. **Scalability**: Profile-based deployment and modular service architecture
### Next Steps
1. **Deploy optimized configuration** in development environment
2. **Validate all security measures** are properly implemented
3. **Monitor performance metrics** and adjust resource limits as needed
4. **Implement backup and recovery procedures** for persistent data
5. **Set up automated monitoring and alerting** for production deployment
For questions or issues with the optimized configuration, refer to the troubleshooting section or consult the detailed configuration comments in the docker-compose files.
Tagebuch/Docker-Clients-Optimierung-Bericht.md
-214
View File
@@ -1,214 +0,0 @@
# Docker Clients Optimierung - Abschlussbericht
## Überblick
Dieser Bericht dokumentiert die durchgeführte Überprüfung und Optimierung der Docker-Konfiguration für die Client-Anwendungen des Meldestelle-Projekts.
## Durchgeführte Analyse
### 1. Untersuchte Dateien
- `docker-compose.clients.yml` - Client-Services Orchestrierung
- `dockerfiles/clients/web-app/Dockerfile` - Kotlin/JS Web-App Build
- `dockerfiles/clients/desktop-app/Dockerfile` - Kotlin Desktop-App mit VNC
- `dockerfiles/clients/web-app/nginx.conf` - Nginx-Konfiguration für Web-App
- `docker/build-args/clients.env` - Build-Argumente für Client-Builds
### 2. Identifizierte Probleme
#### **Desktop-App Dockerfile Inkonsistenzen:**
- ❌ Verwendung von `gradle` statt `./gradlew`
- ❌ Falscher Modulpfad `client` statt `clients`
- ❌ Veraltete Module-Referenzen (`temp`, `docs`)
- ❌ Falscher COPY-Pfad für kompilierte Artefakte
- ❌ Falsche Gradle-Task-Referenzen
#### **Nginx-Konfiguration:**
- ❌ WASM location-Block außerhalb des server-Kontexts
#### **Build-Argumente:**
- ❌ Inkonsistente Build-Targets in `clients.env`
## Durchgeführte Optimierungen
### ✅ Desktop-App Dockerfile (`dockerfiles/clients/desktop-app/Dockerfile`)
**Vor:**
```dockerfile
# Kopiere Gradle-Konfiguration
COPY ../build.gradle.kts settings.gradle.kts gradle.properties ./
COPY ../gradle ./gradle
# Kopiere alle notwendigen Module für Multi-Modul-Projekt
COPY client ./client
COPY temp ./temp
COPY ../docs ./docs
# Dependencies downloaden
RUN gradle :client:dependencies --no-configure-on-demand
# Desktop-App kompilieren
RUN gradle :client:createDistributable --no-configure-on-demand
# Kopiere kompilierte Desktop-App
COPY --from=builder /app/client/build/compose/binaries/main/desktop/ ./desktop-app/
```
**Nach:**
```dockerfile
# Kopiere Gradle-Konfiguration und Wrapper
COPY build.gradle.kts settings.gradle.kts gradle.properties ./
COPY gradle ./gradle
COPY gradlew ./
# Kopiere alle notwendigen Module für Multi-Modul-Projekt
COPY clients ./clients
COPY services ./services
# Setze Gradle-Wrapper Berechtigung
RUN chmod +x ./gradlew
# Dependencies downloaden
RUN ./gradlew :clients:app:dependencies --no-configure-on-demand
# Desktop-App kompilieren
RUN ./gradlew :clients:app:createDistributable --no-configure-on-demand
# Kopiere kompilierte Desktop-App
COPY --from=builder /app/clients/app/build/compose/binaries/main/desktop/ ./desktop-app/
```
**Verbesserungen:**
- ✅ Konsistente Verwendung des Gradle-Wrappers
- ✅ Korrekte Modulpfade entsprechend der aktuellen Projektstruktur
- ✅ Entfernung veralteter Module-Referenzen
- ✅ Korrekte Build-Pfade für Artefakte
### ✅ Nginx-Konfiguration (`dockerfiles/clients/web-app/nginx.conf`)
**Vor:**
```nginx
http {
# WASM MIME-Type für zukünftige Builds
location ~ \.wasm$ {
add_header Content-Type application/wasm;
}
}
```
**Nach:**
```nginx
server {
location / {
# WASM Files mit korrektem MIME-Type
location ~* \.wasm$ {
add_header Content-Type application/wasm;
expires 1y;
add_header Cache-Control "public, immutable";
}
}
}
```
**Verbesserungen:**
- ✅ Korrekte Platzierung des location-Blocks im server-Kontext
- ✅ Zusätzliche Cache-Header für WASM-Dateien
- ✅ Konsistente Behandlung mit anderen statischen Assets
### ✅ Build-Argumente (`docker/build-args/clients.env`)
**Vor:**
```env
WEB_APP_BUILD_TARGET=wasmJsBrowserDistribution
DESKTOP_APP_BUILD_TARGET=composeDesktop
```
**Nach:**
```env
WEB_APP_BUILD_TARGET=jsBrowserDistribution
DESKTOP_APP_BUILD_TARGET=createDistributable
```
**Verbesserungen:**
- ✅ Synchronisation mit tatsächlich verwendeten Gradle-Tasks
- ✅ Konsistenz zwischen Dokumentation und Implementierung
## Validierung
### ✅ Syntax-Validierung
- **Docker-Compose:** `docker-compose -f docker-compose.clients.yml config --quiet` ✅ Erfolgreich
- **Dockerfiles:** Hadolint-Lint durchgeführt ✅ Nur minor Optimierungshinweise
## Aktuelle Bewertung der Client-Docker-Konfiguration
### 🌟 Stärken
1. **Moderne Multi-Stage-Builds:** Beide Dockerfiles nutzen effiziente Multi-Stage-Builds
2. **Umfassende Dokumentation:** Excellent kommentierte Konfigurationsdateien
3. **Flexible Deployment-Optionen:** Unterstützung für standalone, multi-file und complete system deployments
4. **Performance-Optimierungen:** Nginx mit Gzip, Caching und optimierten Headern
5. **Health-Checks:** Implementiert für beide Client-Services
6. **VNC-Integration:** Innovative Desktop-App-Bereitstellung über VNC/noVNC
### 🎯 Weitergehende Optimierungsempfehlungen
#### 1. **Security Hardening**
```dockerfile
# Web-App: Nginx Sicherheit
RUN apk add --no-cache curl=8.4.0-r0 # Version pinning
RUN addgroup -g 101 -S nginx && adduser -S -D -H -u 101 -h /var/cache/nginx -s /sbin/nologin nginx
# Desktop-App: Minimal base images
FROM eclipse-temurin:21-jre-alpine AS runtime # Statt Ubuntu für kleinere Images
```
#### 2. **Build-Performance**
```dockerfile
# .dockerignore ergänzen
RUN --mount=type=cache,target=/root/.gradle ./gradlew dependencies
```
#### 3. **Image-Größen-Optimierung**
```dockerfile
# Multi-stage für kleinere Production-Images
FROM nginx:1.25-alpine AS production
COPY --from=builder --chown=nginx:nginx /app/dist /usr/share/nginx/html
```
#### 4. **Monitoring Integration**
```yaml
# docker-compose.clients.yml
labels:
- "prometheus.io/scrape=true"
- "prometheus.io/port=4000"
- "prometheus.io/path=/metrics"
```
## Zusammenfassung
### ✅ Abgeschlossene Optimierungen
- **Inkonsistenzen behoben:** Desktop-App Dockerfile vollständig korrigiert
- **Nginx-Konfiguration optimiert:** WASM-Support korrekt implementiert
- **Build-Argumente synchronisiert:** Konsistenz zwischen Dokumentation und Code
- **Validierung erfolgreich:** Keine syntaktischen Fehler
### 📊 Bewertung
- **Funktionalität:** ⭐⭐⭐⭐⭐ (Exzellent) - Alle Services funktionsfähig
- **Code-Qualität:** ⭐⭐⭐⭐⭐ (Exzellent) - Nach Optimierungen konsistent und sauber
- **Dokumentation:** ⭐⭐⭐⭐⭐ (Exzellent) - Umfassend kommentiert
- **Performance:** ⭐⭐⭐⭐ (Sehr gut) - Gute Optimierungen, Potenzial für weitere
- **Sicherheit:** ⭐⭐⭐ (Gut) - Grundlagen vorhanden, Raum für Hardening
### 🎯 Fazit
Die Docker-Client-Konfiguration ist nach den Optimierungen **ausgezeichnet strukturiert und funktionsfähig**. Die kritischen Inkonsistenzen wurden behoben, und das System folgt modernen Docker-Best-Practices.
Die implementierten Multi-Stage-Builds, die umfassende Nginx-Konfiguration und die flexible Deployment-Architektur zeigen **professionelle DevOps-Praktiken**.
**Status:** ✅ **PRODUKTIONSREIF** mit optionalen Verbesserungen für erweiterte Szenarien.
---
**Erstellt:** 27. September 2025
**Autor:** Junie (Autonomous Programmer)
**Version:** 1.0
Tagebuch/GATEWAY-TESTS-FIXED.md
-143
View File
@@ -1,143 +0,0 @@
# Gateway Tests - Reparatur Dokumentation
**Datum:** 11. Oktober 2025
## Problem
Die Gateway-Tests waren defekt - nur ~47% (25/53 Tests) liefen erfolgreich. Die Hauptprobleme waren:
1. **Fehlender ReactiveJwtDecoder Bean**: Tests schlugen mit `NoSuchBeanDefinitionException` fehl
2. **JwtAuthenticationTests.kt**: Testete nicht-existierende Custom JWT Filter und versuchte einen nicht verfügbaren `JwtService` Bean zu autowiren
3. **Routing/Security/Filter Tests**: Schlugen mit 401 UNAUTHORIZED fehl, da sie geschützte Endpoints ohne Authentifizierung testeten
4. **Architektur-Mismatch**: Tests waren für Custom JWT Filter geschrieben, aber die Implementierung verwendet Spring Security OAuth2 Resource Server
## Durchgeführte Änderungen
### 1. JwtAuthenticationTests.kt gelöscht ❌
**Datei:** `infrastructure/gateway/src/test/kotlin/at/mocode/infrastructure/gateway/JwtAuthenticationTests.kt`
**Begründung:**
- Testete Custom JWT Filter, die nicht existieren
- Versuchte `@Autowired lateinit var jwtService: JwtService` - Bean existiert nicht im Gateway
- Erwartete Custom Header-Injection (X-User-ID, X-User-Role) - existiert nicht
- Erwartete Custom JSON Error-Responses - existiert nicht
- Alle 10 Tests waren ungültig für die aktuelle OAuth2 Resource Server Implementierung
### 2. TestSecurityConfig.kt erweitert ✅
**Datei:** `infrastructure/gateway/src/test/kotlin/at/mocode/infrastructure/gateway/config/TestSecurityConfig.kt`
**Vorher:**
- Stellte nur Mock `ReactiveJwtDecoder` bereit
**Nachher:**
```kotlin
@TestConfiguration
class TestSecurityConfig {
// Bestehend: Mock ReactiveJwtDecoder
@Bean
@Primary
fun mockReactiveJwtDecoder(): ReactiveJwtDecoder { ... }
// NEU: Security Web Filter Chain die alle Anfragen erlaubt
@Bean
@Primary
fun testSecurityWebFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
return http {
csrf { disable() }
authorizeExchange {
authorize(anyExchange, permitAll)
}
}
}
}
```
**Effekt:**
- Überschreibt die produktive SecurityConfig mit `@Primary`
- Erlaubt alle Anfragen ohne Authentifizierung in Tests
- Ermöglicht Tests von Routing, CORS und Filtern ohne JWT-Tokens
### 3. Bestehende Tests blieben unverändert ✅
Alle verbleibenden Test-Klassen hatten bereits `@Import(TestSecurityConfig::class)`:
- ✅ **GatewayApplicationTests.kt** - hatte bereits Import
- ✅ **FallbackControllerTests.kt** - hatte bereits Import
- ✅ **GatewayRoutingTests.kt** - hatte bereits Import
- ✅ **GatewaySecurityTests.kt** - hatte bereits Import
- ✅ **GatewayFiltersTests.kt** - hatte bereits Import
- ✅ **KeycloakGatewayIntegrationTest.kt** - hatte bereits Import
Durch die Erweiterung von `TestSecurityConfig` funktionieren diese Tests nun automatisch.
## Testergebnisse
### Vorher (Defekt)
```
Gesamt: 53 Tests
Bestanden: ~25 Tests (47%)
Fehlgeschlagen: ~28 Tests (53%)
```
**Fehler:**
- NoSuchBeanDefinitionException: ReactiveJwtDecoder
- 401 UNAUTHORIZED für geschützte Endpoints
- JwtService Bean nicht gefunden
### Nachher (Repariert) ✅
```
Gesamt: 44 Tests
Bestanden: 44 Tests (100%)
Fehlgeschlagen: 0 Tests (0%)
```
**Details:**
- FallbackControllerTests: 14 Tests ✅
- GatewayApplicationTests: 1 Test ✅
- GatewayFiltersTests: 8 Tests ✅
- GatewayRoutingTests: 7 Tests ✅
- GatewaySecurityTests: 13 Tests ✅
- KeycloakGatewayIntegrationTest: 1 Test ✅
**Build-Ergebnis:** `BUILD SUCCESSFUL` 🎉
## Zusammenfassung
**Gelöschte Dateien:** 1
- `JwtAuthenticationTests.kt` (10 ungültige Tests)
**Geänderte Dateien:** 1
- `TestSecurityConfig.kt` (erweitert um SecurityWebFilterChain)
**Unveränderte Dateien:** 6
- Alle anderen Test-Klassen (profitierten automatisch vom Fix)
**Verbesserung:** Von 47% (25/53) auf 100% (44/44) Erfolgsquote
## Technische Details
### Warum funktioniert die Lösung?
1. **@Primary Annotation**: Die Test-SecurityWebFilterChain überschreibt die produktive SecurityConfig
2. **permitAll**: Alle Endpoints sind in Tests zugänglich ohne Authentifizierung
3. **Mock ReactiveJwtDecoder**: Verhindert NoSuchBeanDefinitionException
4. **Automatische Anwendung**: Alle Tests mit `@Import(TestSecurityConfig::class)` profitieren automatisch
### Was wurde NICHT geändert?
- ❌ Produktions-SecurityConfig (`SecurityConfig.kt`)
- ❌ Produktions-Gateway-Routing oder Filter
- ❌ OAuth2 Resource Server Konfiguration
- ❌ Bestehende Test-Logik (außer JwtAuthenticationTests)
## Fazit
Die Gateway-Tests sind vollständig repariert und funktionieren zu 100%. Die Lösung ist:
- ✅ **Minimal invasiv** - nur 2 Dateien geändert
- ✅ **Wartbar** - saubere Trennung von Test- und Produktionscode
- ✅ **Best Practice** - Test-spezifische Konfiguration in separater TestConfiguration
- ✅ **Vollständig** - alle relevanten Tests funktionieren
**Status:** ✅ Abgeschlossen - alle Gateway-Tests funktionieren
Tagebuch/GRADLE-OPTIMIZATION-SUMMARY-DE.md
-619
View File
@@ -1,619 +0,0 @@
# Gradle Build-Optimierung - Vollständige Zusammenfassung
## Zusammenfassung
Erfolgreich abgeschlossene umfassende Gradle Build-Optimierung für das Meldestelle-Projekt über 6 Hauptphasen. Die Optimierung hat das Build-System auf Gradle 9.1.0 modernisiert, 20 neue Dependency-Bundles für verbesserte Wartbarkeit eingeführt, 3 Convention Plugins für konsistente Konfiguration erstellt und die Build-Performance durch Kotlin-Compiler-Optimierungen verbessert.
**Gesamtwirkung:**
- **810 Zeilen hinzugefügt, 111 gelöscht** über 10 Dateien
- **20 neue Dependency-Bundles** im Version Catalog erstellt
- **3 Convention Plugins** für DRY-Prinzipien
- **2 Beispielmodule refactored** (Gateway, Ping-Service) mit 20-37% Code-Reduktion
- **Gradle 9.1.0** mit verbessertem Toolchain-Management
---
## Phase 1: Bundles & Version Catalog ✅
**Datei:** `gradle/libs.versions.toml` (+77 Zeilen)
### Fehlende Bibliotheken hinzugefügt
1. **`slf4j-api`** - Version 2.0.16 (zentralisierte Logging-API)
2. **`kotlin-reflect`** - verwendet Kotlin-Versionsreferenz (Runtime-Reflection-Unterstützung)
### 15 Granulare Bundles erstellt
Diese Bundles gruppieren verwandte Abhängigkeiten für feinkörnige Kontrolle:
1. **`ktor-server-common`** (7 deps) - Kern-Ktor-Server-Abhängigkeiten
- core, netty, content-negotiation, serialization, status-pages, cors, default-headers
2. **`ktor-server-security`** (2 deps) - Authentifizierung & Autorisierung
- auth, auth-jwt
3. **`ktor-server-observability`** (2 deps) - Logging & Metriken
- call-logging, metrics-micrometer
4. **`ktor-server-docs`** (2 deps) - API-Dokumentation
- openapi, swagger
5. **`ktor-client-common`** (5 deps) - HTTP-Client-Grundlagen
- core, content-negotiation, serialization, logging, auth
6. **`spring-boot-web`** (3 deps) - Webanwendungs-Stack
- starter-web, starter-validation, starter-actuator
7. **`spring-boot-security`** (4 deps) - Sicherheit & OAuth2
- starter-security, oauth2-client, oauth2-resource-server, oauth2-jose
8. **`spring-boot-data`** (2 deps) - Datenpersistenz
- starter-data-jpa, starter-data-redis
9. **`spring-boot-observability`** (4 deps) - Monitoring & Tracing
- starter-actuator, micrometer-prometheus, tracing-bridge-brave, zipkin-reporter-brave
10. **`compose-common`** (2 deps) - Compose-Lifecycle
- lifecycle-viewmodel-compose, lifecycle-runtime-compose
11. **`jackson-kotlin`** (2 deps) - JSON-Serialisierung
- module-kotlin, datatype-jsr310
12. **`kotlinx-core`** (3 deps) - Kotlin-Grundlagen
- coroutines-core, serialization-json, datetime
13. **`persistence-postgres`** (4 deps) - Datenbankzugriff
- exposed-core, exposed-dao, exposed-jdbc, postgresql-driver
14. **`resilience`** (3 deps) - Circuit-Breaker-Patterns
- resilience4j-spring-boot3, resilience4j-reactor, spring-boot-starter-aop
15. **`logging`** (3 deps) - Strukturiertes Logging
- kotlin-logging-jvm, logback-classic, logback-core
### 5 Complete Bundles erstellt
All-in-One-Bundles für schnelle Entwicklung:
1. **`ktor-server-complete`** (14 deps) - Vollständiger Ktor-Server-Stack
- Kombiniert: common, security, observability, docs + rate-limit
2. **`spring-boot-service-complete`** (12 deps) - Vollständiger Spring Boot Service
- Kombiniert: web, security, data, observability
3. **`database-complete`** (8 deps) - Vollständige Persistenzschicht
- Exposed ORM + PostgreSQL + HikariCP + Flyway-Migrationen
4. **`testing-kmp`** (8 deps) - Umfassendes KMP-Testing
- JUnit 5, Mockk, AssertJ, Coroutines Test
5. **`monitoring-complete`** (8 deps) - Vollständiger Observability-Stack
- Actuator, Prometheus, Zipkin, Logback, SLF4J
**Vorteile:**
- Single Source of Truth für Dependency-Gruppierungen
- IDE-Autovervollständigung für Bundle-Namen
- Type-Safe Dependency Management
- Einfach zu warten und zu aktualisieren
---
## Phase 2: Root Build-Datei ✅
**Datei:** `build.gradle.kts` (+39 Zeilen modifiziert)
### Vorgenommene Verbesserungen
1. **Zentralisiertes Plugin-Management**
```kotlin
plugins {
// Alle Plugins mit 'apply false' auf Root-Ebene deklariert
alias(libs.plugins.kotlinJvm) apply false
alias(libs.plugins.kotlinMultiplatform) apply false
alias(libs.plugins.kotlinSerialization) apply false
alias(libs.plugins.kotlinSpring) apply false
alias(libs.plugins.kotlinJpa) apply false
alias(libs.plugins.composeMultiplatform) apply false
alias(libs.plugins.composeCompiler) apply false
alias(libs.plugins.spring.boot) apply false
alias(libs.plugins.spring.dependencyManagement) apply false
}
```
- Verhindert "Plugin mehrfach geladen"-Fehler in Gradle 9.1.0+
- Subprojekte wenden über Version-Catalog-Aliase an
2. **AllProjects-Konfiguration**
```kotlin
allprojects {
group = "at.mocode"
version = "1.0.0-SNAPSHOT"
repositories {
mavenCentral()
google()
maven { url = uri("https://jitpack.io") }
// ... weitere Repositories
}
}
```
3. **Build-Analyse-Plugins hinzugefügt**
- `com.github.ben-manes.versions` (0.51.0) - Dependency-Update-Prüfung
- Unterstützt: `./gradlew dependencyUpdates`
4. **Gradle Wrapper aktualisiert**
```kotlin
tasks.wrapper {
gradleVersion = "9.1.0"
distributionType = Wrapper.DistributionType.BIN
}
```
**Vorteile:**
- Konsistente Gruppe/Version über alle Module
- Zentralisierte Repository-Konfiguration
- Plugin-Versionskonflikte verhindert
- Moderne Gradle 9.1.0-Features aktiviert
---
## Phase 3: Convention Plugins ✅
**Verzeichnis:** `buildSrc/src/main/kotlin/` (+192 Zeilen)
### 3 Convention Plugins erstellt
#### 1. `kotlin-multiplatform-conventions.gradle.kts` (56 Zeilen)
**Zweck:** Standardisiert KMP-Modulkonfiguration
**Wendet an:**
- `org.jetbrains.kotlin.multiplatform`
- `org.jetbrains.kotlin.plugin.serialization`
**Konfiguriert:**
- Java 21 Toolchain
- Kotlin-Compiler-Optionen (Opt-in-APIs, JVM-Target)
- Gemeinsame Test-Konfiguration mit JUnit Platform
**Zielmodule:**
- clients/app, clients/ping-feature, clients/auth-feature
- clients/shared/* Module
- core/core-utils, core/core-domain
#### 2. `spring-boot-service-conventions.gradle.kts` (62 Zeilen)
**Zweck:** Standardisiert Spring Boot Service-Konfiguration
**Wendet an:**
- `org.jetbrains.kotlin.jvm`
- `org.springframework.boot`
- `io.spring.dependency-management`
- `org.jetbrains.kotlin.plugin.spring`
- `org.jetbrains.kotlin.plugin.jpa`
**Konfiguriert:**
- Java 21 Toolchain
- Kotlin-Compiler-Optionen (JSR-305 strict, JVM 21)
- JPA All-Open-Plugin für Entities
- JUnit Platform Test-Konfiguration
**Zielmodule:**
- infrastructure/gateway
- infrastructure/auth-server
- infrastructure/monitoring-server
- services/ping/ping-service
- Alle zukünftigen Spring Boot Services
#### 3. `ktor-server-conventions.gradle.kts` (53 Zeilen)
**Zweck:** Standardisiert Ktor-Server-Konfiguration
**Wendet an:**
- `org.jetbrains.kotlin.jvm`
- `io.ktor.plugin`
- `org.jetbrains.kotlin.plugin.serialization`
**Konfiguriert:**
- Java 21 Toolchain
- Kotlin-Compiler-Optionen
- Ktor Fat JAR-Konfiguration
- JUnit Platform Test-Konfiguration
**Zielmodule:**
- Alle zukünftigen Ktor-basierten Backend-Services
### BuildSrc-Konfiguration
**Datei:** `buildSrc/build.gradle.kts` (21 Zeilen)
```kotlin
plugins {
`kotlin-dsl`
}
repositories {
gradlePluginPortal()
mavenCentral()
}
dependencies {
implementation(libs.kotlin.gradlePlugin)
implementation(libs.spring.boot.gradlePlugin)
implementation(libs.spring.dependencyManagement.gradlePlugin)
implementation(libs.ktor.gradlePlugin)
}
```
**Strategische Entscheidung:**
Während Convention Plugins erfolgreich erstellt wurden und im Commit enthalten sind, werden sie **DERZEIT NICHT** auf Module angewendet aufgrund eines entdeckten KMP-Kompatibilitätsproblems. Die Plugins verbleiben in buildSrc als:
1. Dokumentation beabsichtigter Patterns
2. Zukünftige Referenz, wenn KMP-Kompatibilität gelöst ist
3. Wiederverwendbare Templates für Nicht-KMP-Module
**Vorteile (wenn anwendbar):**
- Eliminiert 30-50 Zeilen Boilerplate pro Modul
- Stellt konsistente Toolchain-Konfiguration sicher
- Einzelner Ort für Compiler-Einstellungs-Updates
- Type-Safe Kotlin DSL durchgehend
---
## Phase 4: Modul-Refactoring (Strategisches Sampling) ✅
### Beispiel 1: infrastructure/gateway/build.gradle.kts
**Vorher:** 113 Zeilen | **Nachher:** 94 Zeilen | **Reduktion:** 20%
#### Vorgenommene Änderungen:
1. **Direkte Plugin-Anwendung** (Vermeidung von Convention Plugin wegen KMP-Konflikt)
```kotlin
plugins {
alias(libs.plugins.kotlinJvm)
alias(libs.plugins.kotlinSpring)
alias(libs.plugins.kotlinJpa)
alias(libs.plugins.spring.boot)
alias(libs.plugins.spring.dependencyManagement)
}
```
2. **Einzelne Abhängigkeiten durch Bundles ersetzt:**
```kotlin
// ALT: 15+ einzelne Spring Boot Abhängigkeiten
// NEU: 4 Bundles
implementation(libs.bundles.spring.cloud.gateway)
implementation(libs.bundles.spring.boot.service.complete)
implementation(libs.bundles.resilience)
implementation(libs.bundles.jackson.kotlin)
implementation(libs.bundles.logging)
```
3. **Platform BOM für Versionskonsistenz hinzugefügt:**
```kotlin
implementation(platform(projects.platform.platformBom))
```
**Vorteile:**
- Besser lesbarer Dependency-Abschnitt
- Einfacher zu verstehender Modulzweck
- Konsistent mit anderen Spring Boot Services
- Vereinfachte zukünftige Wartung
### Beispiel 2: services/ping/ping-service/build.gradle.kts
**Vorher:** 79 Zeilen | **Nachher:** 54 Zeilen | **Reduktion:** 37%
#### Vorgenommene Änderungen:
1. **Direkte Plugin-Anwendung:**
```kotlin
plugins {
alias(libs.plugins.kotlinJvm)
alias(libs.plugins.kotlinSpring)
alias(libs.plugins.kotlinJpa)
alias(libs.plugins.spring.boot)
alias(libs.plugins.spring.dependencyManagement)
}
```
2. **Umfassende Bundle-Nutzung:**
```kotlin
implementation(libs.bundles.spring.boot.service.complete)
implementation(libs.bundles.jackson.kotlin)
implementation(libs.bundles.resilience)
implementation(libs.kotlin.reflect) // Jetzt aus Version Catalog
```
3. **Sauberere Test-Abhängigkeiten:**
```kotlin
testImplementation(projects.platform.platformTesting)
testImplementation(libs.bundles.testing.jvm)
```
**Vorteile:**
- 37% Code-Reduktion
- Viel klarere Absicht
- Konsistentes Pattern für zukünftige Services
- Alle Abhängigkeiten zentral verwaltet
---
## Phase 5: Gradle Properties ✅
**Datei:** `gradle.properties` (+9 Zeilen)
### Kotlin-Compiler-Optimierungen hinzugefügt
```properties
# Kotlin Compiler Optimizations (Phase 5)
kotlin.incremental=true
kotlin.incremental.multiplatform=true
kotlin.incremental.js=true
kotlin.caching.enabled=true
kotlin.compiler.execution.strategy=in-process
kotlin.compiler.preciseCompilationResultsBackup=true
kotlin.stdlib.default.dependency=true
```
### Performance-Auswirkung:
- **Inkrementelle Kompilierung:** ~20-40% schnellere Rebuilds
- **Compiler-Caching:** Wiederverwendet Kompilierungsergebnisse über Builds hinweg
- **In-Process-Ausführung:** Reduziert JVM-Startup-Overhead
- **Multiplatform-Optimierung:** Verbessert KMP-Build-Zeiten
- **JS-Kompilierung:** Schnellere JavaScript-Kompilierung
### Zusätzliche existierende Optimierungen:
```properties
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.vfs.watch=true
org.gradle.workers.max=8
```
**Hinweis:** Configuration Cache bleibt deaktiviert aufgrund von JS-Test-Serialisierungsproblemen:
```properties
org.gradle.configuration-cache=false
org.gradle.configuration-cache.problems=warn
```
---
## Phase 6: Testing & Validierung ✅
### Build-Validierung
- ✅ **Syntax-Validierung:** Alle Gradle-Dateien parsen korrekt
- ✅ **Dependency-Auflösung:** Alle Bundles lösen korrekt auf
- ✅ **Version-Catalog-Validierung:** Alle Referenzen gültig
- ✅ **Plugin-Kompatibilität:** Gradle 9.1.0-Kompatibilität bestätigt
### Bekannte Probleme & Lösungen
1. **Convention Plugin KMP-Konflikt**
- **Problem:** Convention Plugins kollidieren mit KMP im selben Projekt
- **Lösung:** Plugins in buildSrc behalten zur Dokumentation, aber direkte Plugin-Deklarationen in Modulen anwenden
- **Status:** Funktionierende Lösung implementiert
2. **Configuration Cache**
- **Problem:** JS-Browser-Tests scheitern mit Serialisierungsfehlern
- **Lösung:** Temporär deaktiviert, wird nach JS-Test-Framework-Update wieder aktiviert
- **Status:** In gradle.properties dokumentiert
3. **WASM-Kompatibilität**
- **Problem:** Einige Abhängigkeiten fehlen WASM-Unterstützung
- **Lösung:** WASM ist Opt-in über `enableWasm=true` Property
- **Status:** Funktioniert wie vorgesehen
### Getestete Build-Befehle
```bash
./gradlew --refresh-dependencies # ✅ Bestanden
./gradlew projects # ✅ Bestanden
./gradlew :infrastructure:gateway:tasks # ✅ Bestanden
./gradlew :services:ping:ping-service:tasks # ✅ Bestanden
```
---
## Erstellte Dokumentation ✅
### REFACTORING-GUIDE.md (440 Zeilen)
Umfassender Leitfaden einschließlich:
1. **Überblick** - Zusammenfassung aller abgeschlossenen Änderungen
2. **Abgeschlossene Änderungen** - Detaillierte Phasen-Dokumentation
3. **Refactoring-Patterns** - 3 vollständige Patterns mit Vorher/Nachher-Beispielen:
- Pattern 1: Spring Boot Services
- Pattern 2: Ktor Server Services
- Pattern 3: Kotlin Multiplatform Module
4. **Modul-Refactoring-Checkliste** - Vollständiges Inventar aller Module mit Refactoring-Status
5. **Build-Befehle** - Empfohlene Befehle für Analyse und Optimierung
6. **Erwartete Vorteile** - Quantifizierte Verbesserungen
7. **Wichtige Hinweise** - Configuration Cache, WASM-Unterstützung, inkrementeller Ansatz
8. **Referenzen** - Links zur offiziellen Gradle-Dokumentation
**Zweck:**
- Dient als Template für Refactoring verbleibender Module
- Dokumentiert etablierte Patterns und Konventionen
- Bietet Copy-Paste-Beispiele für häufige Szenarien
- Erklärt strategische Entscheidungen während der Optimierung
---
## Wichtige Metriken & Statistiken
### Code-Änderungen
- **Dateien modifiziert:** 10
- **Zeilen hinzugefügt:** 810
- **Zeilen gelöscht:** 111
- **Netto-Auswirkung:** +699 Zeilen (hauptsächlich Dokumentation und Plugin-Infrastruktur)
### Version-Catalog-Verbesserungen
- **Neue Bundles:** 20 (15 granular + 5 complete)
- **Neue Bibliotheken:** 2 (slf4j-api, kotlin-reflect)
- **Bundles gesamt:** 25 (inkl. 5 bereits existierende)
### Build-Datei-Reduktionen (in refactorierten Modulen)
- **Gateway:** 113 → 94 Zeilen (-20%)
- **Ping-Service:** 79 → 54 Zeilen (-37%)
- **Durchschnittliche Reduktion:** ~28%
### Plugin-Infrastruktur
- **Convention Plugins erstellt:** 3
- **Zeilen wiederverwendbarer Konfiguration:** 171
- **Module, die profitieren könnten:** 15+ Module
---
## Erreichte Vorteile
### 1. Wartbarkeit
- ✅ **Single Source of Truth** für alle Dependency-Versionen
- ✅ **Zentralisiertes Plugin-Management** verhindert Versionskonflikte
- ✅ **Wiederverwendbare Patterns** über Convention Plugins und Bundles
- ✅ **Umfassende Dokumentation** für zukünftiges Refactoring
### 2. Build-Performance
- ✅ **Gradle 9.1.0** mit neuesten Performance-Verbesserungen
- ✅ **Kotlin-Compiler-Optimierungen** aktiviert
- ✅ **Inkrementelle Kompilierung** konfiguriert
- ✅ **Build-Caching** und **Parallele Ausführung** aktiviert
- ✅ **Geschätzte Verbesserung:** 20-40% schnellere Rebuilds
### 3. Entwickler-Erfahrung
- ✅ **IDE-Autovervollständigung** für Bundle-Namen
- ✅ **Type-Safe Dependency Management**
- ✅ **Klare Build-Datei-Struktur** mit Bundles
- ✅ **Konsistente Patterns** über alle Module
- ✅ **Einfache Dependency-Updates** über Version Catalog
### 4. Code-Qualität
- ✅ **Reduzierte Duplikation** durch Bundles und Conventions
- ✅ **Standardisierte Konfiguration** über Module hinweg
- ✅ **Bessere Trennung der Belange**
- ✅ **Einfachere Code-Reviews** mit weniger Zeilen pro Modul
---
## Nächste Schritte & Empfehlungen
### Sofortige Aktionen
1. ✅ **Änderungen committen** - Alle Änderungen gestaged und bereit
2. 🔲 **Patterns auf verbleibende Module anwenden** - REFACTORING-GUIDE.md als Template verwenden
3. 🔲 **Vollständigen Build ausführen** - `./gradlew clean build` nach Refactoring jedes Moduls
4. 🔲 **CI/CD aktualisieren** - Sicherstellen, dass Pipelines Gradle 9.1.0 verwenden
### Kurzfristig (1-2 Wochen)
1. 🔲 **Infrastruktur-Module refactoren:**
- Auth-Server, Messaging-Config, Redis-Cache, Redis-Event-Store, Monitoring-Server
2. 🔲 **Client-Module refactoren:**
- clients/app, clients/auth-feature, clients/shared/*
3. 🔲 **Core-Module refactoren:**
- core/core-utils, core/core-domain (verwendet bereits einige Bundles)
4. 🔲 **Build-Zeit-Verbesserungen messen** - Vorher/Nachher-Metriken vergleichen
### Mittelfristig (1 Monat)
1. 🔲 **Configuration Cache aktivieren** - Nach Lösung der JS-Test-Serialisierung
2. 🔲 **WASM-Unterstützung untersuchen** - Bereitschaft aller Abhängigkeiten bewerten
3. 🔲 **Dependency-Analyse ausführen** - `./gradlew buildHealth`
4. 🔲 **Nach Updates suchen** - `./gradlew dependencyUpdates`
### Langfristig (3+ Monate)
1. 🔲 **Convention Plugins neu bewerten** - Prüfen, ob KMP-Kompatibilität verbessert wurde
2. 🔲 **Build-Performance-Profiling** - `--scan` für detaillierte Analyse verwenden
3. 🔲 **Dependency-Konsolidierung** - Ungenutzte Abhängigkeiten überprüfen und entfernen
4. 🔲 **Versions-Updates** - Regelmäßige Wartung des Version Catalogs
---
## Getroffene strategische Entscheidungen
### 1. Convention-Plugins-Ansatz
**Entscheidung:** Convention Plugins erstellt, aber in buildSrc ohne aktive Anwendung belassen
**Begründung:**
- KMP und Convention Plugins im selben Projekt verursachen Konflikte
- Gradle 9.1.0 Plugin-Loading-Mechanismus hat strengere Regeln
- Direkte Plugin-Anwendung über Version Catalog funktioniert zuverlässig
**Erwogene Alternative:**
- Separates Convention-Plugin-Repository (abgelehnt: zu komplex für Einzelprojekt)
- Inline-Konfiguration in jedem Modul (abgelehnt: zu viel Duplikation)
**Ergebnis:**
- Convention Plugins dienen als Dokumentation und Templates
- Module verwenden direkte Plugin-Anwendung mit Bundles
- Ähnliche Vorteile durch Dependency-Bundles erreicht
### 2. Bundle-Granularität
**Entscheidung:** Sowohl granulare (15) als auch complete (5) Bundles erstellt
**Begründung:**
- Granulare Bundles: Feinkörnige Kontrolle für spezifische Anwendungsfälle
- Complete Bundles: Schnelle Entwicklung für Standard-Patterns
- Flexibilität: Teams können angemessene Bundle-Ebene wählen
**Beispiele:**
- `ktor-server-common` für minimalen API-Service verwenden
- `ktor-server-complete` für voll ausgestattetes Gateway verwenden
### 3. Gradle 9.1.0-Adoption
**Entscheidung:** Sofortiges Upgrade auf Gradle 9.1.0
**Begründung:**
- Neueste Features und Performance-Verbesserungen
- Bessere Kotlin-DSL-Unterstützung
- Erforderlich für modernes Plugin-Management
- Langfristige Wartungsvorteile
**Geminderte Risiken:**
- Kompatibilität mit allen Plugins getestet
- Build funktioniert End-to-End verifiziert
- Breaking Changes dokumentiert (Plugin-Loading)
### 4. Inkrementelles Refactoring
**Entscheidung:** 2 Beispielmodule refactored, Patterns für andere dokumentiert
**Begründung:**
- Beweist, dass Patterns in echter Codebasis funktionieren
- Erstellt Templates für verbleibende Arbeit
- Ermöglicht Validierung vor großangelegten Änderungen
- Reduziert Risiko von Breaking Changes
**Gewählte Module:**
- Gateway: Komplexes Spring Boot + Spring Cloud Setup
- Ping-Service: Einfacher Service, einfache Validierung
---
## Fazit
Erfolgreich abgeschlossene umfassende Gradle Build-Optimierung über alle 6 geplanten Phasen. Das Projekt hat jetzt:
1. **Modernes Gradle 9.1.0** mit verbessertem Toolchain-Management
2. **20 neue Dependency-Bundles** die flexibles Dependency-Management bieten
3. **3 Convention Plugins** als Templates für zukünftige Nutzung
4. **Optimierte Build-Konfiguration** mit Kotlin-Compiler-Verbesserungen
5. **Umfassende Dokumentation** in REFACTORING-GUIDE.md
6. **Bewährte Patterns** demonstriert in Gateway- und Ping-Service-Modulen
Die Grundlage ist jetzt gelegt für:
- Schnellere Build-Zeiten (20-40% Verbesserung erwartet)
- Einfachere Wartung mit zentralisierter Konfiguration
- Konsistente Patterns über alle Module
- Vereinfachtes Dependency-Management
Alle Änderungen sind getestet, validiert und produktionsbereit. Die REFACTORING-GUIDE.md bietet klare Patterns für das Refactoring der verbleibenden 13+ Module nach dem gleichen Ansatz.
---
## Geänderte Dateien
```
REFACTORING-GUIDE.md | 440 +++++++++++++++++++++
build.gradle.kts | 39 +-
buildSrc/build.gradle.kts | 21 +
buildSrc/.../kotlin-multiplatform-conventions | 56 +++
buildSrc/.../ktor-server-conventions | 53 +++
buildSrc/.../spring-boot-service-conventions | 62 +++
gradle.properties | 9 +
gradle/libs.versions.toml | 77 ++++
infrastructure/gateway/build.gradle.kts | 83 ++--
services/ping/ping-service/build.gradle.kts | 81 ++--
-------------------------------------------------------------------
Gesamt: 10 Dateien geändert, 810 Einfügungen(+), 111 Löschungen(-)
```
---
**Optimierungsstatus:** ✅ **ABGESCHLOSSEN**
**Build-Status:** ✅ **VALIDIERT**
**Dokumentationsstatus:** ✅ **UMFASSEND**
**Produktionsbereit:** ✅ **JA**
Tagebuch/GRADLE-OPTIMIZATION-SUMMARY.md
-619
View File
@@ -1,619 +0,0 @@
# Gradle Build Optimization - Complete Summary
## Executive Summary
Successfully completed comprehensive Gradle build optimization for the Meldestelle project across 6 major phases. The optimization modernized the build system to Gradle 9.1.0, introduced 20 new dependency bundles for improved maintainability, created 3 convention plugins for consistent configuration, and enhanced build performance through Kotlin compiler optimizations.
**Total Impact:**
- **810 lines added, 111 deleted** across 10 files
- **20 new dependency bundles** created in version catalog
- **3 convention plugins** for DRY principles
- **2 example modules refactored** (Gateway, Ping-Service) with 20-37% code reduction
- **Gradle 9.1.0** with enhanced toolchain management
---
## Phase 1: Bundles & Version Catalog ✅
**File:** `gradle/libs.versions.toml` (+77 lines)
### Added Missing Libraries
1. **`slf4j-api`** - version 2.0.16 (centralized logging API)
2. **`kotlin-reflect`** - uses kotlin version reference (runtime reflection support)
### Created 15 Granular Bundles
These bundles group related dependencies for fine-grained control:
1. **`ktor-server-common`** (7 deps) - Core Ktor server dependencies
- core, netty, content-negotiation, serialization, status-pages, cors, default-headers
2. **`ktor-server-security`** (2 deps) - Authentication & authorization
- auth, auth-jwt
3. **`ktor-server-observability`** (2 deps) - Logging & metrics
- call-logging, metrics-micrometer
4. **`ktor-server-docs`** (2 deps) - API documentation
- openapi, swagger
5. **`ktor-client-common`** (5 deps) - HTTP client essentials
- core, content-negotiation, serialization, logging, auth
6. **`spring-boot-web`** (3 deps) - Web application stack
- starter-web, starter-validation, starter-actuator
7. **`spring-boot-security`** (4 deps) - Security & OAuth2
- starter-security, oauth2-client, oauth2-resource-server, oauth2-jose
8. **`spring-boot-data`** (2 deps) - Data persistence
- starter-data-jpa, starter-data-redis
9. **`spring-boot-observability`** (4 deps) - Monitoring & tracing
- starter-actuator, micrometer-prometheus, tracing-bridge-brave, zipkin-reporter-brave
10. **`compose-common`** (2 deps) - Compose lifecycle
- lifecycle-viewmodel-compose, lifecycle-runtime-compose
11. **`jackson-kotlin`** (2 deps) - JSON serialization
- module-kotlin, datatype-jsr310
12. **`kotlinx-core`** (3 deps) - Kotlin fundamentals
- coroutines-core, serialization-json, datetime
13. **`persistence-postgres`** (4 deps) - Database access
- exposed-core, exposed-dao, exposed-jdbc, postgresql-driver
14. **`resilience`** (3 deps) - Circuit breaker patterns
- resilience4j-spring-boot3, resilience4j-reactor, spring-boot-starter-aop
15. **`logging`** (3 deps) - Structured logging
- kotlin-logging-jvm, logback-classic, logback-core
### Created 5 Complete Bundles
All-in-one bundles for rapid development:
1. **`ktor-server-complete`** (14 deps) - Full Ktor server stack
- Combines: common, security, observability, docs + rate-limit
2. **`spring-boot-service-complete`** (12 deps) - Full Spring Boot service
- Combines: web, security, data, observability
3. **`database-complete`** (8 deps) - Complete persistence layer
- Exposed ORM + PostgreSQL + HikariCP + Flyway migrations
4. **`testing-kmp`** (8 deps) - Comprehensive KMP testing
- JUnit 5, Mockk, AssertJ, Coroutines Test
5. **`monitoring-complete`** (8 deps) - Full observability stack
- Actuator, Prometheus, Zipkin, Logback, SLF4J
**Benefits:**
- Single source of truth for dependency groupings
- IDE autocompletion for bundle names
- Type-safe dependency management
- Easy to maintain and update versions
---
## Phase 2: Root Build File ✅
**File:** `build.gradle.kts` (+39 lines modified)
### Enhancements Made
1. **Centralized Plugin Management**
```kotlin
plugins {
// All plugins declared with 'apply false' at root level
alias(libs.plugins.kotlinJvm) apply false
alias(libs.plugins.kotlinMultiplatform) apply false
alias(libs.plugins.kotlinSerialization) apply false
alias(libs.plugins.kotlinSpring) apply false
alias(libs.plugins.kotlinJpa) apply false
alias(libs.plugins.composeMultiplatform) apply false
alias(libs.plugins.composeCompiler) apply false
alias(libs.plugins.spring.boot) apply false
alias(libs.plugins.spring.dependencyManagement) apply false
}
```
- Prevents "plugin loaded multiple times" errors in Gradle 9.1.0+
- Subprojects apply via version catalog aliases
2. **AllProjects Configuration**
```kotlin
allprojects {
group = "at.mocode"
version = "1.0.0-SNAPSHOT"
repositories {
mavenCentral()
google()
maven { url = uri("https://jitpack.io") }
// ... other repositories
}
}
```
3. **Added Build Analysis Plugins**
- `com.github.ben-manes.versions` (0.51.0) - Dependency update checking
- Supports: `./gradlew dependencyUpdates`
4. **Updated Gradle Wrapper**
```kotlin
tasks.wrapper {
gradleVersion = "9.1.0"
distributionType = Wrapper.DistributionType.BIN
}
```
**Benefits:**
- Consistent group/version across all modules
- Centralized repository configuration
- Plugin version conflicts prevented
- Modern Gradle 9.1.0 features enabled
---
## Phase 3: Convention Plugins ✅
**Directory:** `buildSrc/src/main/kotlin/` (+192 lines)
### Created 3 Convention Plugins
#### 1. `kotlin-multiplatform-conventions.gradle.kts` (56 lines)
**Purpose:** Standardizes KMP module configuration
**Applies:**
- `org.jetbrains.kotlin.multiplatform`
- `org.jetbrains.kotlin.plugin.serialization`
**Configures:**
- Java 21 toolchain
- Kotlin compiler options (opt-in APIs, JVM target)
- Common test configuration with JUnit Platform
**Target Modules:**
- clients/app, clients/ping-feature, clients/auth-feature
- clients/shared/* modules
- core/core-utils, core/core-domain
#### 2. `spring-boot-service-conventions.gradle.kts` (62 lines)
**Purpose:** Standardizes Spring Boot service configuration
**Applies:**
- `org.jetbrains.kotlin.jvm`
- `org.springframework.boot`
- `io.spring.dependency-management`
- `org.jetbrains.kotlin.plugin.spring`
- `org.jetbrains.kotlin.plugin.jpa`
**Configures:**
- Java 21 toolchain
- Kotlin compiler options (JSR-305 strict, JVM 21)
- JPA all-open plugin for entities
- JUnit Platform test configuration
**Target Modules:**
- infrastructure/gateway
- infrastructure/auth-server
- infrastructure/monitoring-server
- services/ping/ping-service
- All future Spring Boot services
#### 3. `ktor-server-conventions.gradle.kts` (53 lines)
**Purpose:** Standardizes Ktor server configuration
**Applies:**
- `org.jetbrains.kotlin.jvm`
- `io.ktor.plugin`
- `org.jetbrains.kotlin.plugin.serialization`
**Configures:**
- Java 21 toolchain
- Kotlin compiler options
- Ktor fat JAR configuration
- JUnit Platform test configuration
**Target Modules:**
- Any future Ktor-based backend services
### BuildSrc Configuration
**File:** `buildSrc/build.gradle.kts` (21 lines)
```kotlin
plugins {
`kotlin-dsl`
}
repositories {
gradlePluginPortal()
mavenCentral()
}
dependencies {
implementation(libs.kotlin.gradlePlugin)
implementation(libs.spring.boot.gradlePlugin)
implementation(libs.spring.dependencyManagement.gradlePlugin)
implementation(libs.ktor.gradlePlugin)
}
```
**Strategic Decision:**
While convention plugins were successfully created and are included in the commit, they are **NOT currently applied** to modules due to a discovered KMP incompatibility issue. The plugins remain in buildSrc as:
1. Documentation of intended patterns
2. Future reference when KMP compatibility is resolved
3. Reusable templates for non-KMP modules
**Benefits (when applicable):**
- Eliminates 30-50 lines of boilerplate per module
- Ensures consistent toolchain configuration
- Single location for compiler settings updates
- Type-safe Kotlin DSL throughout
---
## Phase 4: Module Refactoring (Strategic Sampling) ✅
### Example 1: infrastructure/gateway/build.gradle.kts
**Before:** 113 lines | **After:** 94 lines | **Reduction:** 20%
#### Changes Made:
1. **Direct plugin application** (avoiding convention plugin due to KMP conflict)
```kotlin
plugins {
alias(libs.plugins.kotlinJvm)
alias(libs.plugins.kotlinSpring)
alias(libs.plugins.kotlinJpa)
alias(libs.plugins.spring.boot)
alias(libs.plugins.spring.dependencyManagement)
}
```
2. **Replaced individual dependencies with bundles:**
```kotlin
// OLD: 15+ individual Spring Boot dependencies
// NEW: 4 bundles
implementation(libs.bundles.spring.cloud.gateway)
implementation(libs.bundles.spring.boot.service.complete)
implementation(libs.bundles.resilience)
implementation(libs.bundles.jackson.kotlin)
implementation(libs.bundles.logging)
```
3. **Added platform BOM for version consistency:**
```kotlin
implementation(platform(projects.platform.platformBom))
```
**Benefits:**
- More readable dependency section
- Easier to understand module purpose
- Consistent with other Spring Boot services
- Simplified future maintenance
### Example 2: services/ping/ping-service/build.gradle.kts
**Before:** 79 lines | **After:** 54 lines | **Reduction:** 37%
#### Changes Made:
1. **Direct plugin application:**
```kotlin
plugins {
alias(libs.plugins.kotlinJvm)
alias(libs.plugins.kotlinSpring)
alias(libs.plugins.kotlinJpa)
alias(libs.plugins.spring.boot)
alias(libs.plugins.spring.dependencyManagement)
}
```
2. **Comprehensive bundle usage:**
```kotlin
implementation(libs.bundles.spring.boot.service.complete)
implementation(libs.bundles.jackson.kotlin)
implementation(libs.bundles.resilience)
implementation(libs.kotlin.reflect) // Now from version catalog
```
3. **Cleaner test dependencies:**
```kotlin
testImplementation(projects.platform.platformTesting)
testImplementation(libs.bundles.testing.jvm)
```
**Benefits:**
- 37% code reduction
- Much clearer intent
- Consistent pattern for future services
- All dependencies centrally managed
---
## Phase 5: Gradle Properties ✅
**File:** `gradle.properties` (+9 lines)
### Added Kotlin Compiler Optimizations
```properties
# Kotlin Compiler Optimizations (Phase 5)
kotlin.incremental=true
kotlin.incremental.multiplatform=true
kotlin.incremental.js=true
kotlin.caching.enabled=true
kotlin.compiler.execution.strategy=in-process
kotlin.compiler.preciseCompilationResultsBackup=true
kotlin.stdlib.default.dependency=true
```
### Performance Impact:
- **Incremental compilation:** ~20-40% faster rebuilds
- **Compiler caching:** Reuses compilation results across builds
- **In-process execution:** Reduces JVM startup overhead
- **Multiplatform optimization:** Improves KMP build times
- **JS compilation:** Faster JavaScript compilation
### Additional Existing Optimizations:
```properties
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.vfs.watch=true
org.gradle.workers.max=8
```
**Note:** Configuration cache remains disabled due to JS test serialization issues:
```properties
org.gradle.configuration-cache=false
org.gradle.configuration-cache.problems=warn
```
---
## Phase 6: Testing & Validation ✅
### Build Validation
- ✅ **Syntax validation:** All Gradle files parse correctly
- ✅ **Dependency resolution:** All bundles resolve properly
- ✅ **Version catalog validation:** All references valid
- ✅ **Plugin compatibility:** Gradle 9.1.0 compatibility confirmed
### Known Issues & Resolutions
1. **Convention Plugin KMP Conflict**
- **Issue:** Convention plugins conflict with KMP in same project
- **Resolution:** Kept plugins in buildSrc for documentation, but applied direct plugin declarations in modules
- **Status:** Working solution implemented
2. **Configuration Cache**
- **Issue:** JS browser tests fail with serialization errors
- **Resolution:** Temporarily disabled, will re-enable after JS test framework update
- **Status:** Documented in gradle.properties
3. **WASM Compatibility**
- **Issue:** Some dependencies lack WASM support
- **Resolution:** WASM is opt-in via `enableWasm=true` property
- **Status:** Working as designed
### Build Commands Tested
```bash
./gradlew --refresh-dependencies # ✅ Pass
./gradlew projects # ✅ Pass
./gradlew :infrastructure:gateway:tasks # ✅ Pass
./gradlew :services:ping:ping-service:tasks # ✅ Pass
```
---
## Documentation Created ✅
### REFACTORING-GUIDE.md (440 lines)
Comprehensive guide including:
1. **Overview** - Summary of all completed changes
2. **Completed Changes** - Detailed phase documentation
3. **Refactoring Patterns** - 3 complete patterns with before/after examples:
- Pattern 1: Spring Boot Services
- Pattern 2: Ktor Server Services
- Pattern 3: Kotlin Multiplatform Modules
4. **Module Refactoring Checklist** - Full inventory of all modules with refactoring status
5. **Build Commands** - Recommended commands for analysis and optimization
6. **Expected Benefits** - Quantified improvements
7. **Important Notes** - Configuration cache, WASM support, incremental approach
8. **References** - Links to official Gradle documentation
**Purpose:**
- Serves as template for refactoring remaining modules
- Documents established patterns and conventions
- Provides copy-paste examples for common scenarios
- Explains strategic decisions made during optimization
---
## Key Metrics & Statistics
### Code Changes
- **Files modified:** 10
- **Lines added:** 810
- **Lines deleted:** 111
- **Net impact:** +699 lines (mostly documentation and plugin infrastructure)
### Version Catalog Enhancements
- **New bundles:** 20 (15 granular + 5 complete)
- **New libraries:** 2 (slf4j-api, kotlin-reflect)
- **Total bundles:** 25 (including 5 pre-existing)
### Build File Reductions (in refactored modules)
- **Gateway:** 113 → 94 lines (-20%)
- **Ping-Service:** 79 → 54 lines (-37%)
- **Average reduction:** ~28%
### Plugin Infrastructure
- **Convention plugins created:** 3
- **Lines of reusable configuration:** 171
- **Modules that could benefit:** 15+ modules
---
## Benefits Achieved
### 1. Maintainability
- ✅ **Single source of truth** for all dependency versions
- ✅ **Centralized plugin management** prevents version conflicts
- ✅ **Reusable patterns** via convention plugins and bundles
- ✅ **Comprehensive documentation** for future refactoring
### 2. Build Performance
- ✅ **Gradle 9.1.0** with latest performance improvements
- ✅ **Kotlin compiler optimizations** enabled
- ✅ **Incremental compilation** configured
- ✅ **Build caching** and **parallel execution** enabled
- ✅ **Estimated improvement:** 20-40% faster rebuilds
### 3. Developer Experience
- ✅ **IDE autocompletion** for bundle names
- ✅ **Type-safe dependency management**
- ✅ **Clear build file structure** with bundles
- ✅ **Consistent patterns** across all modules
- ✅ **Easy dependency updates** via version catalog
### 4. Code Quality
- ✅ **Reduced duplication** through bundles and conventions
- ✅ **Standardized configuration** across modules
- ✅ **Better separation of concerns**
- ✅ **Easier code reviews** with fewer lines per module
---
## Next Steps & Recommendations
### Immediate Actions
1. ✅ **Commit changes** - All changes staged and ready
2. 🔲 **Apply patterns to remaining modules** - Use REFACTORING-GUIDE.md as template
3. 🔲 **Run full build** - `./gradlew clean build` after refactoring each module
4. 🔲 **Update CI/CD** - Ensure pipelines use Gradle 9.1.0
### Short-term (1-2 weeks)
1. 🔲 **Refactor infrastructure modules:**
- Auth-Server, Messaging-Config, Redis-Cache, Redis-Event-Store, Monitoring-Server
2. 🔲 **Refactor client modules:**
- clients/app, clients/auth-feature, clients/shared/*
3. 🔲 **Refactor core modules:**
- core/core-utils, core/core-domain (already uses some bundles)
4. 🔲 **Measure build time improvements** - Compare before/after metrics
### Medium-term (1 month)
1. 🔲 **Enable configuration cache** - After resolving JS test serialization
2. 🔲 **Investigate WASM support** - Evaluate readiness of all dependencies
3. 🔲 **Run dependency analysis** - `./gradlew buildHealth`
4. 🔲 **Check for updates** - `./gradlew dependencyUpdates`
### Long-term (3+ months)
1. 🔲 **Re-evaluate convention plugins** - Check if KMP compatibility improved
2. 🔲 **Build performance profiling** - Use `--scan` for detailed analysis
3. 🔲 **Dependency consolidation** - Review and remove unused dependencies
4. 🔲 **Version updates** - Regular maintenance of version catalog
---
## Strategic Decisions Made
### 1. Convention Plugins Approach
**Decision:** Created convention plugins but kept them in buildSrc without active application
**Reasoning:**
- KMP and convention plugins in same project cause conflicts
- Gradle 9.1.0 plugin loading mechanism has stricter rules
- Direct plugin application via version catalog works reliably
**Alternative Considered:**
- Separate convention plugin repository (rejected: too complex for single project)
- Inline configuration in each module (rejected: too much duplication)
**Outcome:**
- Convention plugins serve as documentation and templates
- Modules use direct plugin application with bundles
- Achieved similar benefits through dependency bundles
### 2. Bundle Granularity
**Decision:** Created both granular (15) and complete (5) bundles
**Reasoning:**
- Granular bundles: Fine-grained control for specific use cases
- Complete bundles: Rapid development for standard patterns
- Flexibility: Teams can choose appropriate bundle level
**Examples:**
- Use `ktor-server-common` for minimal API service
- Use `ktor-server-complete` for full-featured gateway
### 3. Gradle 9.1.0 Adoption
**Decision:** Upgraded to Gradle 9.1.0 immediately
**Reasoning:**
- Latest features and performance improvements
- Better Kotlin DSL support
- Required for modern plugin management
- Long-term maintenance benefits
**Risks Mitigated:**
- Tested compatibility with all plugins
- Verified build works end-to-end
- Documented breaking changes (plugin loading)
### 4. Incremental Refactoring
**Decision:** Refactored 2 example modules, documented patterns for others
**Reasoning:**
- Proves patterns work in real codebase
- Creates templates for remaining work
- Allows validation before large-scale changes
- Reduces risk of breaking changes
**Modules Chosen:**
- Gateway: Complex Spring Boot + Spring Cloud setup
- Ping-Service: Simple service, easy validation
---
## Conclusion
Successfully completed comprehensive Gradle build optimization covering all 6 planned phases. The project now has:
1. **Modern Gradle 9.1.0** with enhanced toolchain management
2. **20 new dependency bundles** providing flexible dependency management
3. **3 convention plugins** as templates for future use
4. **Optimized build configuration** with Kotlin compiler enhancements
5. **Comprehensive documentation** in REFACTORING-GUIDE.md
6. **Proven patterns** demonstrated in Gateway and Ping-Service modules
The foundation is now in place for:
- Faster build times (20-40% improvement expected)
- Easier maintenance with centralized configuration
- Consistent patterns across all modules
- Simplified dependency management
All changes are tested, validated, and ready for production use. The REFACTORING-GUIDE.md provides clear patterns for refactoring the remaining 13+ modules following the same approach.
---
## Files Changed
```
REFACTORING-GUIDE.md | 440 +++++++++++++++++++++
build.gradle.kts | 39 +-
buildSrc/build.gradle.kts | 21 +
buildSrc/.../kotlin-multiplatform-conventions | 56 +++
buildSrc/.../ktor-server-conventions | 53 +++
buildSrc/.../spring-boot-service-conventions | 62 +++
gradle.properties | 9 +
gradle/libs.versions.toml | 77 ++++
infrastructure/gateway/build.gradle.kts | 83 ++--
services/ping/ping-service/build.gradle.kts | 81 ++--
-------------------------------------------------------------------
Total: 10 files changed, 810 insertions(+), 111 deletions(-)
```
---
**Optimization Status:** ✅ **COMPLETE**
**Build Status:** ✅ **VALIDATED**
**Documentation Status:** ✅ **COMPREHENSIVE**
**Ready for Production:** ✅ **YES**
Tagebuch/KEYCLOAK-RESOLUTION-DE.md
-211
View File
@@ -1,211 +0,0 @@
# Keycloak-Konfigurationslösungsbericht
**Datum:** 2025-10-05
**Status:** ✅ GELÖST - Keycloak ist stabil und das Authentifizierungssystem ist betriebsbereit
## Problemübersicht
Keycloak erlebte Neustart-Schleifen und Initialisierungsprobleme, die verhinderten, dass das Authentifizierungssystem ordnungsgemäß funktionierte.
## Identifizierte Grundursachen
1. **Komplexe Umgebungskonfiguration**: Übermäßig komplexe Umgebungsvariablen mit JVM-Optimierungen und erweiterten Einstellungen verursachten Startkonflikte
2. **Health Check-Probleme**: Der Health Check verwendete falsche Endpunkte und schlug bei HTTP-Weiterleitungen fehl
3. **Realm-Import-Konflikte**: Das `--import-realm` Flag trug möglicherweise zu Startproblemen bei
## Angewandte Lösungen
### 1. Vereinfachte Umgebungskonfiguration
**Datei:** `docker-compose.yml`
```yaml
environment:
# Minimale Konfiguration für Fehlerbehebung
KEYCLOAK_ADMIN: admin
KEYCLOAK_ADMIN_PASSWORD: admin
KC_DB: postgres
KC_DB_URL: jdbc:postgresql://postgres:5432/meldestelle
KC_DB_USERNAME: meldestelle
KC_DB_PASSWORD: meldestelle
KC_DB_SCHEMA: keycloak
KC_HTTP_ENABLED: true
KC_HOSTNAME_STRICT: false
```
**Entfernte problematische Konfigurationen:**
- Komplexe JVM-Optimierungs-Flags
- Erweiterte Cache-Konfigurationen
- Detaillierte Logging-Konfigurationen
- Datenbankverbindungspool-Optimierungen
### 2. Behobene Health Check-Konfiguration
```yaml
healthcheck:
test: [ 'CMD-SHELL', 'curl -s http://localhost:8080/ >/dev/null 2>&1 || exit 1' ]
interval: 15s
timeout: 10s
retries: 5
start_period: 60s
```
**Vorgenommene Änderungen:**
- `-f` Flag von curl entfernt (schlug bei 302-Weiterleitungen fehl)
- Health Check vereinfacht, um Basis-Endpunkt zu verwenden
- Timeouts und Wiederholungsversuche reduziert
### 3. Realm-Import während initialer Einrichtung entfernt
```yaml
command:
# Entwicklungsmodus mit Basis-Image - minimale Einrichtung
- start-dev
```
**Entfernt:** `--import-realm` Flag zur Eliminierung potenzieller Startkonflikte
### 4. Service-Abhängigkeiten angepasst
```yaml
keycloak:
condition: service_started # Geändert von service_healthy
```
**Begründung:** API Gateway durfte auch mit Health Check-Problemen starten, da Keycloak funktional arbeitet
## Aktueller Systemstatus ✅
### Laufende Services
- ✅ **Keycloak**: Stabil und antwortet (Port 8180)
- ✅ **API Gateway**: Gesund und routet ordnungsgemäß (Port 8081)
- ✅ **Ping Service**: Betriebsbereit mit Health Checks (Port 8082)
- ✅ **PostgreSQL**: Gesund mit initialisiertem Keycloak-Schema
- ✅ **Consul**: Service Discovery funktioniert
- ✅ **Redis**: Cache-Service gesund
### Verifikationsergebnisse
```bash
# API Gateway-Routing zum Ping Service
$ curl http://localhost:8081/api/ping/health
{"status":"pong","timestamp":"2025-10-05T19:22:08.302871057Z","service":"ping-service","healthy":true}
# Keycloak antwortet
$ curl -s -o /dev/null -w "%{http_code}" http://localhost:8180/
302 # Korrekte Weiterleitungsantwort
# Service Discovery
Alle Services ordnungsgemäß in Consul registriert: api-gateway, consul, ping-service
```
## Empfehlungen für Produktion
### 1. Realm-Import wieder aktivieren
Nach Stabilisierung Realm-Import wieder hinzufügen:
```yaml
command:
- start-dev
- --import-realm
```
### 2. Umgebungskonfiguration schrittweise optimieren
Optimierungen eine nach der anderen wieder einführen:
```yaml
# JVM-Optimierungen wieder hinzufügen
JAVA_OPTS_APPEND: >-
-XX:MaxRAMPercentage=75.0
-XX:+UseG1GC
-XX:+UseStringDeduplication
# Datenbankpool-Einstellungen wieder hinzufügen
KC_DB_POOL_INITIAL_SIZE: 5
KC_DB_POOL_MIN_SIZE: 5
KC_DB_POOL_MAX_SIZE: 20
```
### 3. Health Check verbessern
Erwägen Sie einen spezifischeren Health-Endpunkt:
```yaml
healthcheck:
test: [ 'CMD-SHELL', 'curl -s http://localhost:8080/health/ready || curl -s http://localhost:8080/ >/dev/null' ]
```
### 4. Sicherheitshärtung für Produktion
- Standard-Admin-Anmeldedaten ändern
- HTTPS aktivieren
- Ordnungsgemäße Hostname-Einstellungen konfigurieren
- Authentifizierung zur Realm-Konfiguration hinzufügen
## Geänderte Dateien
- ✅ `docker-compose.yml` - Vereinfachte Keycloak-Konfiguration
- ✅ `dockerfiles/infrastructure/keycloak/Dockerfile` - Vereinfachter Build-Prozess
## Testverifizierung
Die vollständige Authentifizierungsinfrastruktur funktioniert jetzt:
1. ✅ Keycloak startet und bleibt stabil
2. ✅ API Gateway verbindet sich mit Keycloak
3. ✅ Ping Service integriert sich mit Gateway
4. ✅ Service Discovery funktioniert
5. ✅ Health Checks betriebsbereit
## Realm-Import-Testergebnisse ✅
### Erfolgreich abgeschlossen
- ✅ **Realm-Import**: Die meldestelle-realm.json importiert erfolgreich
- ✅ **Benutzererstellung**: Admin-Benutzer mit Realm-Rollen erstellt (ADMIN, USER)
- ✅ **Client-Import**: Sowohl api-gateway- als auch web-app-Clients korrekt importiert
- ✅ **Service-Integration**: API Gateway verbindet sich mit importiertem Realm
- ✅ **Systemstabilität**: Alle Services bleiben während Realm-Operationen gesund
### Aktueller Authentifizierungsstatus
```bash
# System-Verifikationsergebnisse
Services-Status:
- API Gateway: Gesund ✅
- Ping Service: Gesund ✅
- Keycloak: Funktional, aber Health Check-Probleme
- PostgreSQL, Redis, Consul: Alle gesund ✅
Realm-Status:
- meldestelle realm: Erfolgreich importiert ✅
- Admin-Benutzer: Verfügbar (Passwort: Change_Me_In_Production!)
- Clients: api-gateway, web-app konfiguriert ✅
```
### Identifizierte Probleme zur Lösung
1. **OpenID Discovery-Endpunkt**: Gibt null Issuer zurück (benötigt Hostname-Konfiguration)
2. **Client-Secret**: api-gateway-Client-Anmeldedaten benötigen ordnungsgemäße Secret-Konfiguration
3. **Health Check**: Keycloak zeigt ungesund, funktioniert aber
4. **Authentifizierungsflow**: Noch nicht auf API Gateway-Routen durchgesetzt
## Nächste Schritte für vollständige Authentifizierung
### Sofortige erforderliche Maßnahmen
1. **OpenID-Konfiguration beheben**
- KC_HOSTNAME für ordnungsgemäße Issuer-URLs konfigurieren
- Sicherstellen, dass Realm-Discovery-Endpunkte korrekt funktionieren
2. **Client-Secrets konfigurieren**
- Ordnungsgemäßes Client-Secret für api-gateway setzen
- Client-Credentials-Flow testen
3. **Authentifizierungsdurchsetzung aktivieren**
- API Gateway so konfigurieren, dass Authentifizierung erforderlich ist
- Geschützte Endpunkte mit JWT-Token testen
### Schritte zur Produktionsbereitschaft
1. **Sicherheitshärtung**
- Standard-Admin-Passwort vom Realm-Import ändern
- HTTPS für Produktion konfigurieren
- Ordnungsgemäße Hostname-Einstellungen setzen
2. **Leistungsoptimierung**
- JVM-Optimierungen schrittweise wieder hinzufügen
- Datenbankverbindungspooling konfigurieren
- Caching-Optimierungen aktivieren
### Empfohlene Konfigurationsupdates
```yaml
# Für Produktion zu docker-compose.yml hinzufügen
KC_HOSTNAME: https://auth.meldestelle.at
KC_HOSTNAME_STRICT: true
KC_HTTPS_CERTIFICATE_FILE: /opt/keycloak/ssl/cert.pem
KC_HTTPS_CERTIFICATE_KEY_FILE: /opt/keycloak/ssl/key.pem
```
---
**Realm-Import-Test: ✅ ERFOLGREICH ABGESCHLOSSEN**
**Systemstatus: Stabil mit betriebsbereiter Authentifizierungsinfrastruktur**
**Nächste Phase: Client-Authentifizierung konfigurieren und Sicherheitsdurchsetzung aktivieren**
Tagebuch/KEYCLOAK-RESOLUTION.md
-211
View File
@@ -1,211 +0,0 @@
# Keycloak Configuration Resolution Report
**Date:** 2025-10-05
**Status:** ✅ RESOLVED - Keycloak is stable and authentication system is operational
## Problem Summary
Keycloak was experiencing restart loops and initialization issues, preventing the authentication system from working properly.
## Root Causes Identified
1. **Complex Environment Configuration**: Overly complex environment variables with JVM optimizations and advanced settings were causing startup conflicts
2. **Health Check Issues**: The health check was using incorrect endpoints and failing on HTTP redirects
3. **Realm Import Conflicts**: The `--import-realm` flag was potentially contributing to startup issues
## Solutions Applied
### 1. Simplified Environment Configuration
**File:** `docker-compose.yml`
```yaml
environment:
# Minimal configuration for troubleshooting
KEYCLOAK_ADMIN: admin
KEYCLOAK_ADMIN_PASSWORD: admin
KC_DB: postgres
KC_DB_URL: jdbc:postgresql://postgres:5432/meldestelle
KC_DB_USERNAME: meldestelle
KC_DB_PASSWORD: meldestelle
KC_DB_SCHEMA: keycloak
KC_HTTP_ENABLED: true
KC_HOSTNAME_STRICT: false
```
**Removed problematic configurations:**
- Complex JVM optimization flags
- Advanced cache configurations
- Detailed logging configurations
- Database connection pool optimizations
### 2. Fixed Health Check Configuration
```yaml
healthcheck:
test: [ 'CMD-SHELL', 'curl -s http://localhost:8080/ >/dev/null 2>&1 || exit 1' ]
interval: 15s
timeout: 10s
retries: 5
start_period: 60s
```
**Changes made:**
- Removed `-f` flag from curl (was failing on 302 redirects)
- Simplified health check to use base endpoint
- Reduced timeouts and retry counts
### 3. Removed Realm Import During Initial Setup
```yaml
command:
# Development mode with base image - minimal setup
- start-dev
```
**Removed:** `--import-realm` flag to eliminate potential startup conflicts
### 4. Adjusted Service Dependencies
```yaml
keycloak:
condition: service_started # Changed from service_healthy
```
**Rationale:** Allowed API gateway to start even with health check issues since Keycloak is functionally working
## Current System Status ✅
### Services Running
- ✅ **Keycloak**: Stable and responding (port 8180)
- ✅ **API Gateway**: Healthy and routing properly (port 8081)
- ✅ **Ping Service**: Operational with health checks (port 8082)
- ✅ **PostgreSQL**: Healthy with Keycloak schema initialized
- ✅ **Consul**: Service discovery working
- ✅ **Redis**: Cache service healthy
### Verification Results
```bash
# API Gateway routing to Ping Service
$ curl http://localhost:8081/api/ping/health
{"status":"pong","timestamp":"2025-10-05T19:22:08.302871057Z","service":"ping-service","healthy":true}
# Keycloak responding
$ curl -s -o /dev/null -w "%{http_code}" http://localhost:8180/
302 # Correct redirect response
# Service Discovery
All services properly registered in Consul: api-gateway, consul, ping-service
```
## Recommendations for Production
### 1. Re-enable Realm Import
Once stable, add back realm import:
```yaml
command:
- start-dev
- --import-realm
```
### 2. Optimize Environment Configuration Gradually
Reintroduce optimizations one by one:
```yaml
# Add back JVM optimizations
JAVA_OPTS_APPEND: >-
-XX:MaxRAMPercentage=75.0
-XX:+UseG1GC
-XX:+UseStringDeduplication
# Add back database pool settings
KC_DB_POOL_INITIAL_SIZE: 5
KC_DB_POOL_MIN_SIZE: 5
KC_DB_POOL_MAX_SIZE: 20
```
### 3. Improve Health Check
Consider using a more specific health endpoint:
```yaml
healthcheck:
test: [ 'CMD-SHELL', 'curl -s http://localhost:8080/health/ready || curl -s http://localhost:8080/ >/dev/null' ]
```
### 4. Security Hardening for Production
- Change default admin credentials
- Enable HTTPS
- Configure proper hostname settings
- Add authentication to realm configuration
## Files Modified
- ✅ `docker-compose.yml` - Simplified Keycloak configuration
- ✅ `dockerfiles/infrastructure/keycloak/Dockerfile` - Simplified build process
## Testing Verification
The complete authentication infrastructure is now working:
1. ✅ Keycloak starts and remains stable
2. ✅ API Gateway connects to Keycloak
3. ✅ Ping Service integrates with gateway
4. ✅ Service discovery functioning
5. ✅ Health checks operational
## Realm Import Testing Results ✅
### Successfully Completed
- ✅ **Realm Import**: The meldestelle-realm.json imports successfully
- ✅ **User Creation**: Admin user created with realm roles (ADMIN, USER)
- ✅ **Client Import**: Both api-gateway and web-app clients imported correctly
- ✅ **Service Integration**: API Gateway connects to imported realm
- ✅ **System Stability**: All services remain healthy during realm operations
### Current Authentication Status
```bash
# System Verification Results
Services Status:
- API Gateway: Healthy ✅
- Ping Service: Healthy ✅
- Keycloak: Functional but health check issues
- PostgreSQL, Redis, Consul: All healthy ✅
Realm Status:
- meldestelle realm: Imported successfully ✅
- Admin user: Available (password: Change_Me_In_Production!)
- Clients: api-gateway, web-app configured ✅
```
### Identified Issues for Resolution
1. **OpenID Discovery Endpoint**: Returns null issuer (needs hostname configuration)
2. **Client Secret**: api-gateway client credentials need proper secret configuration
3. **Health Check**: Keycloak shows unhealthy but is functionally working
4. **Authentication Flow**: Not yet enforced on API Gateway routes
## Next Steps for Full Authentication
### Immediate Actions Required
1. **Fix OpenID Configuration**
- Configure KC_HOSTNAME for proper issuer URLs
- Ensure realm discovery endpoints work correctly
2. **Configure Client Secrets**
- Set proper client secret for api-gateway
- Test client credentials flow
3. **Enable Authentication Enforcement**
- Configure API Gateway to require authentication
- Test protected endpoints with JWT tokens
### Production Readiness Steps
1. **Security Hardening**
- Change default admin password from realm import
- Configure HTTPS for production
- Set proper hostname settings
2. **Performance Optimization**
- Re-add JVM optimizations gradually
- Configure database connection pooling
- Enable caching optimizations
### Recommended Configuration Updates
```yaml
# For production, add to docker-compose.yml
KC_HOSTNAME: https://auth.meldestelle.at
KC_HOSTNAME_STRICT: true
KC_HTTPS_CERTIFICATE_FILE: /opt/keycloak/ssl/cert.pem
KC_HTTPS_CERTIFICATE_KEY_FILE: /opt/keycloak/ssl/key.pem
```
---
**Realm Import Testing: ✅ COMPLETED SUCCESSFULLY**
**System Status: Stable with authentication infrastructure ready**
**Next Phase: Configure client authentication and enable security enforcement**
Tagebuch/README-ENV.md
-187
View File
@@ -1,187 +0,0 @@
# Umgebungsvariablen Setup - Zusammenfassung
## Was wurde implementiert
Das Meldestelle-Projekt verfügt über eine vollständig zentralisierte Umgebungsvariablen-Konfiguration im `config/` Verzeichnis.
### 1. Zentrale Konfigurationsstruktur
- **`config/.env.template`** - Master-Vorlage mit allen verfügbaren Umgebungsvariablen
- **`config/.env.dev`** - Entwicklungsumgebung-Konfiguration
- **`config/.env.prod`** - Produktionsumgebung-Konfiguration
- **`config/.env.staging`** - Staging-Umgebung-Konfiguration
- **`config/.env.test`** - Testumgebung-Konfiguration
- **`config/README.md`** - Umfassende Dokumentation der Konfigurationsverwaltung
### 2. Aktualisierte Dateien
- **`docker-compose.yml`** - Alle Services verwenden Umgebungsvariablen mit Fallback-Werten
- **Symlink `.env`** - Verweist auf die aktuelle Umgebungskonfiguration
### 3. Konfigurierte Services
Die folgenden Services sind vollständig konfiguriert:
- **PostgreSQL** - Datenbank mit konfigurierbaren Zugangsdaten
- **Redis** - Event Store und Cache mit separaten Konfigurationen
- **Keycloak** - Authentifizierung mit konfigurierbaren Admin-Zugangsdaten
- **Kafka/Zookeeper** - Messaging-System mit konfigurierbaren Parametern
- **Grafana** - Monitoring mit konfigurierbaren Admin-Zugangsdaten
- **Prometheus** - Metriken-Sammlung
- **Zipkin** - Distributed Tracing
### 4. Umgebungsvariablen-Kategorien
- **Anwendungskonfiguration** (API_HOST, API_PORT, etc.)
- **Datenbank-Konfiguration** (DB_HOST, DB_PORT, DB_USER, etc.)
- **Redis-Konfiguration** (Event Store und Cache)
- **Sicherheitskonfiguration** (JWT_SECRET, API_KEY, etc.)
- **Keycloak-Konfiguration** (Admin-Zugangsdaten, DB-Verbindung)
- **Service Discovery** (Consul-Konfiguration)
- **Messaging** (Kafka/Zookeeper-Konfiguration)
- **Monitoring** (Grafana, Prometheus-Konfiguration)
- **Logging-Konfiguration** (Log-Level, Request/Response-Logging)
- **CORS und Rate Limiting**
## Verwendung
### Schnellstart
1. **Umgebung wählen:**
```bash
# Für Entwicklung
ln -sf config/.env.dev .env
# Für Produktion
ln -sf config/.env.prod .env
# Für Tests
ln -sf config/.env.test .env
```
2. **Services starten:**
```bash
docker compose up -d
```
3. **Services überprüfen:**
```bash
docker compose ps
```
### Anpassungen
- Kopieren und bearbeiten Sie die gewünschte `.env.*` Datei aus dem `config/` Verzeichnis
- Verwenden Sie verschiedene Ports für mehrere Entwickler (siehe `.env.test` für Beispiel)
- Ändern Sie alle `CHANGE_ME` Werte in Produktionsumgebungen
### Dokumentation
Vollständige Dokumentation finden Sie in:
- `config/README.md` - Zentrale Konfigurationsdokumentation
## Sicherheitshinweise
⚠️ **Wichtig:**
- Niemals Produktionsgeheimnisse in die Versionskontrolle einbinden
- JWT_SECRET in der Produktion ändern
- Starke Passwörter für Produktionsumgebungen verwenden
- API-Schlüssel regelmäßig rotieren
## Fehlerbehebung
Bei Problemen:
1. Überprüfen Sie die aktive Umgebungskonfiguration: `ls -la .env`
2. Validieren Sie die Docker-Compose-Konfiguration: `docker compose config`
3. Überprüfen Sie die Service-Logs: `docker compose logs -f`
4. Konsultieren Sie `config/README.md` für detaillierte Konfigurationsrichtlinien
### Keycloak startet neu (Restart-Loop) oder beendet sich mit Code 1
Das Problem tritt häufig auf, wenn das Keycloak-DB-Schema fehlt oder nicht zur aktuell gesetzten `KC_DB_SCHEMA` passt.
So gehen Sie vor:
- Logs erfassen (bitte im Fehlerfall mitschicken):
- Keycloak: `docker compose logs -f keycloak`
- Postgres: `docker compose logs -f postgres`
- Schema-Status prüfen und ggf. manuell anlegen (nur wenn das Volume bereits existierte, als die Init-Skripte eingeführt wurden):
1. In die Datenbank einloggen:
```bash
docker exec -it meldestelle-postgres psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"
```
2. Folgende Befehle ausführen (ersetzen Sie den Benutzer bei Bedarf):
```sql
CREATE SCHEMA IF NOT EXISTS keycloak;
GRANT ALL PRIVILEGES ON SCHEMA keycloak TO "$POSTGRES_USER";
GRANT USAGE ON SCHEMA keycloak TO "$POSTGRES_USER";
ALTER DEFAULT PRIVILEGES IN SCHEMA keycloak GRANT ALL ON TABLES TO "$POSTGRES_USER";
ALTER DEFAULT PRIVILEGES IN SCHEMA keycloak GRANT ALL ON SEQUENCES TO "$POSTGRES_USER";
```
- Alternativ: Volumes zurücksetzen (Achtung: Datenverlust in Postgres und Keycloak-Volume!)
```bash
docker compose down -v
docker compose up -d postgres keycloak
```
Hinweis: Bei frischen Volumes legt Postgres via `docker/services/postgres/01-init-keycloak-schema.sql` das Schema automatisch an. Die Datei `02-init-keycloak-schema.sql` ist absichtlich ein No-Op, um Doppel-Initialisierungen zu vermeiden.
- Konfiguration prüfen:
- `KC_DB_SCHEMA` ist in `docker-compose.yml` parametrisiert und standardmäßig auf `keycloak` gesetzt. Sie können es in Ihrer `.env`-Datei überschreiben.
- In Staging/Prod muss `KC_DB_URL`, `KC_DB_USERNAME`, `KC_DB_PASSWORD` auf die jeweilige DB/Benutzer zeigen (siehe `config/.env.staging`, `config/.env.prod`).
### Postgres Healthcheck schlägt fehl
Der Healthcheck ist jetzt vollständig über Umgebungsvariablen parametrisiert und passt sich Dev/Staging/Prod automatisch an:
```yaml
healthcheck:
test: [ "CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-meldestelle} -d ${POSTGRES_DB:-meldestelle}" ]
```
Stellen Sie sicher, dass `POSTGRES_USER` und `POSTGRES_DB` korrekt gesetzt sind.
### Compose-Warnung "The BUILD_DATE variable is not set"
Die Warnung ist in `docker-compose.yml` behoben. Für Build-Argumente wird nun ein Fallback verwendet:
```yaml
BUILD_DATE: ${BUILD_DATE:-unknown}
```
Wenn Sie ein Datum setzen möchten, fügen Sie `BUILD_DATE=2025-10-05T16:55:00Z` Ihrer `.env` hinzu.
### Logging/Health Optimierungen (optional)
- Aktuell ist `KC_LOG_CONSOLE_FORMAT` auf `plain` gesetzt, um Standard-Logs auszugeben. Für strukturierte Logs können Sie `KC_LOG_CONSOLE_FORMAT=json` setzen.
- `KC_HEALTH_ENABLED=true` und ein großzügiges `start_period` (180s) sind aktiv, um Realm-Importe abwarten zu können.
## Nächste Schritte
- Die zentrale Konfiguration ist bereits vollständig implementiert
- Wählen Sie die gewünschte Umgebung mit den Symlink-Befehlen oben
- Passen Sie Konfigurationswerte in den `config/.env.*` Dateien nach Bedarf an
- Für neue Umgebungen verwenden Sie `config/.env.template` als Ausgangspunkt
---
## Smoke-Tests (Prometheus & Zipkin)
Nach dem Start der Infrastruktur können einfache Smoke-Tests ausgeführt werden:
```bash
# Zipkin: erzeugt einen Ping über das Gateway und prüft, ob Traces ankommen
bash scripts/smoke/zipkin_smoke.sh
# Prometheus: prüft, ob Gateway und Ping-Service Metriken exponieren
bash scripts/smoke/prometheus_smoke.sh
```
Variablen:
- GATEWAY_URL (Default: http://localhost:8081)
- ZIPKIN_URL (Default: http://localhost:9411)
- PING_SERVICE_URL (Default: http://localhost:8082)
## Keycloak Healthcheck
- Der Keycloak-Container verwendet nun einen robusten Healthcheck, der nicht von curl abhängt.
- Ablauf: Zuerst wird curl verwendet, falls vorhanden; alternativ wget; fehlt beides, wird ein Bash-/dev/tcp-Fallback genutzt. In diesem Fall wird eine klare Fehlermeldung in den Healthcheck-Logs ausgegeben.
- Zeitparameter: interval 15s, timeout 30s, retries 10, start_period 180s – ausreichend, um längere Realm-Imports (30+ Sekunden) abzuwarten.
- Beispiel (vereinfacht):
- test: CMD-SHELL
- if curl vorhanden → GET /health/ready prüfen; sonst wget; sonst Bash /dev/tcp mit HTTP-Status „200 OK“ prüfen.
Tagebuch/README-PRODUCTION.md
-489
View File
@@ -1,489 +0,0 @@
# Meldestelle - Produktionsumgebung Setup
## Übersicht
Dieses Dokument beschreibt die Einrichtung und den Betrieb der Meldestelle-Anwendung in einer Produktionsumgebung mit Docker Compose. Die Produktionskonfiguration bietet erweiterte Sicherheitsfeatures, TLS-Verschlüsselung und optimierte Performance-Einstellungen.
## 🔒 Sicherheitsfeatures
### Implementierte Sicherheitsmaßnahmen
1. **Starke Authentifizierung**
- Redis mit Passwort-Authentifizierung
- PostgreSQL mit SCRAM-SHA-256 Authentifizierung
- Kafka mit SASL/SSL Sicherheit
- Zookeeper mit SASL Authentifizierung
2. **TLS/SSL Verschlüsselung**
- HTTPS-only für alle Web-Services
- TLS-Unterstützung für Redis (konfigurierbar)
- SSL für PostgreSQL
- SSL/TLS für Kafka Inter-Broker Kommunikation
3. **Netzwerksicherheit**
- Interne Service-Kommunikation ohne Host-Port-Exposition
- Nginx Reverse Proxy als einziger öffentlicher Zugang
- Isoliertes Docker-Netzwerk mit definiertem Subnetz
4. **Container-Sicherheit**
- Non-root User für alle Services
- Resource-Limits für alle Container
- Read-only Mounts für Konfigurationsdateien
- Restart-Policies für Hochverfügbarkeit
## 📋 Voraussetzungen
### System-Anforderungen
- **Betriebssystem**: Linux (Ubuntu 20.04+ empfohlen)
- **Docker**: Version 20.10+
- **Docker Compose**: Version 2.0+
- **RAM**: Mindestens 8GB (16GB empfohlen)
- **CPU**: Mindestens 4 Cores
- **Speicher**: Mindestens 50GB freier Speicherplatz
### Netzwerk-Anforderungen
- **Ports**: 80, 443 (HTTP/HTTPS)
- **Domain**: Gültige Domain-Namen für SSL-Zertifikate
- **DNS**: Korrekte DNS-Konfiguration für alle Subdomains
## 🚀 Installation und Setup
### 1. Repository klonen
```bash
git clone <repository-url>
cd Meldestelle
```
### 2. Produktionsumgebung konfigurieren
```bash
# Kopieren Sie die Produktions-Umgebungsvariablen aus dem config Verzeichnis
cp config/.env.prod .env.prod
# Bearbeiten Sie die Produktionskonfiguration
nano .env.prod
# Oder verwenden Sie einen Symlink für direkte Nutzung
ln -sf config/.env.prod .env
```
### 3. SSL-Zertifikate einrichten
Siehe [SSL-Zertifikat Setup Anleitung](../config/ssl/README-de.md) für detaillierte Anweisungen.
#### Schnellstart mit Let's Encrypt
```bash
# Installieren Sie Certbot
sudo apt-get update
sudo apt-get install certbot
# Generieren Sie Zertifikate
sudo certbot certonly --standalone \
-d yourdomain.com \
-d api.yourdomain.com \
-d auth.yourdomain.com \
-d monitoring.yourdomain.com
# Kopieren Sie Zertifikate
sudo cp /etc/letsencrypt/live/yourdomain.com/fullchain.pem config/ssl/nginx/server.crt
sudo cp /etc/letsencrypt/live/yourdomain.com/privkey.pem config/ssl/nginx/server.key
# Generieren Sie Diffie-Hellman Parameter
openssl dhparam -out config/ssl/nginx/dhparam.pem 2048
```
### 4. Konfigurationsdateien anpassen
#### Passwörter generieren
```bash
# Starke Passwörter generieren
openssl rand -base64 32 # Für Datenbank-Passwörter
openssl rand -base64 64 # Für JWT-Secret
openssl rand -base64 32 # Für Redis-Passwort
```
#### Wichtige Konfigurationen in .env.prod
```bash
# Datenbank (ÄNDERN SIE DIESE WERTE!)
POSTGRES_PASSWORD=IHR_STARKES_DB_PASSWORT
DB_PASSWORD=IHR_STARKES_DB_PASSWORT
# Redis (ÄNDERN SIE DIESE WERTE!)
REDIS_PASSWORD=IHR_STARKES_REDIS_PASSWORT
# JWT (ÄNDERN SIE DIESE WERTE!)
JWT_SECRET=IHR_STARKER_JWT_SECRET_MINDESTENS_256_BITS
# Keycloak (ÄNDERN SIE DIESE WERTE!)
KEYCLOAK_ADMIN=ihr_admin_username
KEYCLOAK_ADMIN_PASSWORD=IHR_STARKES_ADMIN_PASSWORT
# Domains (ÄNDERN SIE DIESE WERTE!)
KC_HOSTNAME=auth.ihredomain.com
GRAFANA_HOSTNAME=monitoring.ihredomain.com
PROMETHEUS_HOSTNAME=metrics.ihredomain.com
```
### 5. Services starten
```bash
# Produktionsumgebung starten
docker compose -f docker-compose.prod.yml --env-file .env.prod up -d
# Status überprüfen
docker compose -f docker-compose.prod.yml ps
# Logs überwachen
docker compose -f docker-compose.prod.yml logs -f
```
## 🔧 Konfiguration
### Service-Übersicht
| Service | Interner Port | Externer Zugang | Beschreibung |
|---------|---------------|-----------------|--------------|
| nginx | 80, 443 | ✅ | Reverse Proxy, SSL-Terminierung |
| postgres | 5432 | ❌ | Datenbank (nur intern) |
| redis | 6379 | ❌ | Cache & Event Store (nur intern) |
| keycloak | 8443 | ❌ | Authentifizierung (über nginx) |
| kafka | 9092, 9093 | ❌ | Messaging (nur intern) |
| zookeeper | 2181 | ❌ | Kafka Koordination (nur intern) |
| prometheus | 9090 | ❌ | Metriken (über nginx) |
| grafana | 3000 | ❌ | Monitoring Dashboard (über nginx) |
| zipkin | 9411 | ❌ | Distributed Tracing (nur intern) |
### Nginx Reverse Proxy Konfiguration
Erstellen Sie Service-spezifische Konfigurationen in `config/nginx/conf.d/`:
#### Keycloak (auth.ihredomain.com)
```nginx
server {
listen 443 ssl http2;
server_name auth.ihredomain.com;
ssl_certificate /etc/ssl/nginx/server.crt;
ssl_private_key /etc/ssl/nginx/server.key;
location / {
proxy_pass https://keycloak:8443;
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;
}
}
```
#### Grafana (monitoring.ihredomain.com)
```nginx
server {
listen 443 ssl http2;
server_name monitoring.ihredomain.com;
ssl_certificate /etc/ssl/nginx/server.crt;
ssl_private_key /etc/ssl/nginx/server.key;
location / {
proxy_pass https://grafana:3000;
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;
}
}
```
## 🔍 Monitoring und Logging
### Prometheus Metriken
Zugang über: `https://metrics.ihredomain.com`
Überwachte Services:
- Anwendungsmetriken
- PostgreSQL Metriken
- Redis Metriken
- Kafka Metriken
- System-Metriken (Node Exporter)
- Container-Metriken (cAdvisor)
### Grafana Dashboards
Zugang über: `https://monitoring.ihredomain.com`
Standard-Dashboards für:
- Anwendungs-Performance
- Datenbank-Performance
- Redis-Performance
- Kafka-Metriken
- System-Übersicht
### Log-Management
```bash
# Service-Logs anzeigen
docker compose -f docker-compose.prod.yml logs [service-name]
# Logs in Echtzeit verfolgen
docker compose -f docker-compose.prod.yml logs -f [service-name]
# Log-Rotation konfigurieren
# Fügen Sie zu /etc/docker/daemon.json hinzu:
{
"log-driver": "json-file",
"log-opts": {
"max-size": "10m",
"max-file": "3"
}
}
```
## 🛡️ Sicherheits-Checkliste
### Vor der Produktionsfreigabe
- [ ] Alle Standard-Passwörter geändert
- [ ] SSL-Zertifikate von vertrauenswürdiger CA installiert
- [ ] Firewall konfiguriert (nur Ports 80, 443 öffentlich)
- [ ] Backup-Strategie implementiert
- [ ] Monitoring und Alerting konfiguriert
- [ ] Log-Rotation eingerichtet
- [ ] Security-Updates installiert
- [ ] Penetration-Test durchgeführt
### Regelmäßige Sicherheitsaufgaben
- [ ] Passwörter alle 90 Tage rotieren
- [ ] SSL-Zertifikate vor Ablauf erneuern
- [ ] Security-Updates monatlich installieren
- [ ] Backup-Wiederherstellung testen
- [ ] Access-Logs regelmäßig überprüfen
- [ ] Vulnerability-Scans durchführen
## 💾 Backup und Wiederherstellung
### Automatische Backups
```bash
# Datenbank-Backup Script erstellen
cat > backup-db.sh << 'EOF'
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
docker compose -f docker-compose.prod.yml exec -T postgres \
pg_dump -U meldestelle_prod meldestelle_prod | \
gzip > backups/db_backup_$DATE.sql.gz
find backups/ -name "db_backup_*.sql.gz" -mtime +30 -delete
EOF
chmod +x backup-db.sh
# Cron-Job für tägliche Backups
echo "0 2 * * * /path/to/backup-db.sh" | crontab -
```
### Redis Backup
```bash
# Redis-Daten sichern
docker compose -f docker-compose.prod.yml exec redis \
redis-cli --rdb /data/backup.rdb
# Backup kopieren
docker cp $(docker compose -f docker-compose.prod.yml ps -q redis):/data/backup.rdb \
backups/redis_backup_$(date +%Y%m%d_%H%M%S).rdb
```
### Wiederherstellung
```bash
# Datenbank wiederherstellen
gunzip -c backups/db_backup_YYYYMMDD_HHMMSS.sql.gz | \
docker compose -f docker-compose.prod.yml exec -T postgres \
psql -U meldestelle_prod -d meldestelle_prod
# Redis wiederherstellen
docker compose -f docker-compose.prod.yml stop redis
docker cp backups/redis_backup_YYYYMMDD_HHMMSS.rdb \
$(docker compose -f docker-compose.prod.yml ps -q redis):/data/dump.rdb
docker compose -f docker-compose.prod.yml start redis
```
## 🔄 Updates und Wartung
### Rolling Updates
```bash
# Service einzeln aktualisieren
docker compose -f docker-compose.prod.yml pull [service-name]
docker compose -f docker-compose.prod.yml up -d --no-deps [service-name]
# Alle Services aktualisieren
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
```
### Wartungsmodus
```bash
# Wartungsseite aktivieren
docker compose -f docker-compose.prod.yml stop nginx
# Wartungs-Nginx Container starten (mit Wartungsseite)
# Nach Wartung: Normalen Betrieb wiederherstellen
docker compose -f docker-compose.prod.yml start nginx
```
## 🚨 Troubleshooting
### Häufige Probleme
#### 1. SSL-Zertifikat Fehler
```bash
# Zertifikat überprüfen
openssl x509 -in config/ssl/nginx/server.crt -text -noout
# Zertifikat-Gültigkeit prüfen
openssl x509 -in config/ssl/nginx/server.crt -noout -dates
```
#### 2. Service startet nicht
```bash
# Logs überprüfen
docker-compose -f docker-compose.prod.yml logs [service-name]
# Container-Status prüfen
docker-compose -f docker-compose.prod.yml ps
# Health-Check Status
docker inspect $(docker-compose -f docker-compose.prod.yml ps -q [service-name])
```
#### 3. Datenbankverbindung fehlgeschlagen
```bash
# Datenbank-Logs prüfen
docker-compose -f docker-compose.prod.yml logs postgres
# Verbindung testen
docker-compose -f docker-compose.prod.yml exec postgres \
psql -U meldestelle_prod -d meldestelle_prod -c "SELECT 1;"
```
#### 4. Redis-Verbindung fehlgeschlagen
```bash
# Redis-Logs prüfen
docker-compose -f docker-compose.prod.yml logs redis
# Redis-Verbindung testen
docker-compose -f docker-compose.prod.yml exec redis \
redis-cli -a $REDIS_PASSWORD ping
```
#### 5. Container startet nicht (Out of Memory)
```bash
# Container-Ressourcenverbrauch prüfen
docker stats --no-stream
# Speicher-Limits überprüfen
docker inspect $(docker-compose -f docker-compose.prod.yml ps -q [service-name]) | grep -i memory
# System-Speicher prüfen
free -h
df -h
# Container mit mehr Speicher neu starten
docker-compose -f docker-compose.prod.yml up -d --force-recreate [service-name]
```
#### 6. Netzwerk-Verbindungsprobleme
```bash
# Docker-Netzwerk prüfen
docker network ls
docker network inspect meldestelle-network
# Service-zu-Service Verbindung testen
docker-compose -f docker-compose.prod.yml exec [service1] \
ping [service2]
# Port-Erreichbarkeit testen
docker-compose -f docker-compose.prod.yml exec [service] \
nc -zv [target-service] [port]
# DNS-Auflösung testen
docker-compose -f docker-compose.prod.yml exec [service] \
nslookup [target-service]
```
#### 7. Volume-Mount Probleme
```bash
# Volume-Status prüfen
docker volume ls
docker volume inspect [volume-name]
# Berechtigungen prüfen
docker-compose -f docker-compose.prod.yml exec [service] \
ls -la /path/to/mounted/directory
# Volume-Speicherplatz prüfen
docker system df
docker system df -v
```
#### 8. Docker-Compose Konfigurationsfehler
```bash
# Konfiguration validieren
docker-compose -f docker-compose.prod.yml config
# Syntax-Fehler finden
docker-compose -f docker-compose.prod.yml config --quiet
# Umgebungsvariablen-Substitution prüfen
docker-compose -f docker-compose.prod.yml config --resolve-image-digests
```
### Performance-Optimierung
#### Ressourcen-Monitoring
```bash
# Container-Ressourcenverbrauch
docker stats
# Detaillierte Container-Informationen
docker-compose -f docker-compose.prod.yml top
```
#### Datenbank-Optimierung
```bash
# PostgreSQL-Performance analysieren
docker-compose -f docker-compose.prod.yml exec postgres \
psql -U meldestelle_prod -d meldestelle_prod \
-c "SELECT * FROM pg_stat_activity;"
```
## 📞 Support und Kontakt
### Notfall-Kontakte
- **System-Administrator**: [Kontaktinformationen]
- **Entwicklungsteam**: [Kontaktinformationen]
- **Security-Team**: [Kontaktinformationen]
### Dokumentation
- [API-Dokumentation](docs/api/)
- [Architektur-Dokumentation](docs/architecture/)
- [Entwickler-Dokumentation](docs/development/)
### Monitoring-Dashboards
- **Grafana**: https://monitoring.ihredomain.com
- **Prometheus**: https://metrics.ihredomain.com
- **Keycloak Admin**: https://auth.ihredomain.com/admin
---
**⚠️ Wichtiger Hinweis**: Diese Produktionskonfiguration enthält sensible Sicherheitseinstellungen. Stellen Sie sicher, dass alle Passwörter und Geheimnisse sicher verwaltet und regelmäßig rotiert werden.
Tagebuch/REFACTORING-GUIDE-DE.md
-440
View File
@@ -1,440 +0,0 @@
# Gradle Build Refactoring-Leitfaden
## Überblick
Dieser Leitfaden dokumentiert die umfassende Gradle Build-Optimierung, die in den Phasen 1-5 abgeschlossen wurde, einschließlich praktischer Refactoring-Patterns für alle verbleibenden Module.
---
## ✅ Abgeschlossene Änderungen
### Phase 1: Bundles & Version Catalog
**Datei:** `gradle/libs.versions.toml`
#### Fehlende Bibliotheken hinzugefügt:
- `slf4j-api` (Version 2.0.16)
- `kotlin-reflect` (verwendet Kotlin-Versionsreferenz)
#### 5 neue Complete Bundles hinzugefügt:
1. **`ktor-server-complete`** - Vollständiger Ktor-Server-Stack (14 Abhängigkeiten)
- Enthält: core, netty, content-negotiation, serialization, status-pages, cors, default-headers, auth, auth-jwt, call-logging, metrics-micrometer, openapi, swagger, rate-limit
2. **`spring-boot-service-complete`** - Vollständiger Spring Boot Service-Stack (12 Abhängigkeiten)
- Enthält: web, validation, actuator, security, oauth2-client, oauth2-resource-server, oauth2-jose, data-jpa, data-redis, micrometer-prometheus, tracing-bridge-brave, zipkin-reporter-brave
3. **`database-complete`** - Vollständiger Datenbank-Stack (8 Abhängigkeiten)
- Enthält: exposed-core, exposed-dao, exposed-jdbc, exposed-kotlin-datetime, postgresql-driver, hikari-cp, flyway-core, flyway-postgresql
4. **`testing-kmp`** - KMP-Test-Stack (8 Abhängigkeiten)
- Enthält: kotlin-test, junit-jupiter-api, junit-jupiter-engine, junit-jupiter-params, junit-platform-launcher, mockk, assertj-core, kotlinx-coroutines-test
5. **`monitoring-complete`** - Vollständiger Monitoring-Stack (8 Abhängigkeiten)
- Enthält: actuator, micrometer-prometheus, tracing-bridge-brave, zipkin-reporter-brave, zipkin-sender-okhttp3, kotlin-logging-jvm, logback-classic, slf4j-api
### Phase 2: Root Build-Datei
**Datei:** `build.gradle.kts`
#### Verbesserungen:
- ✅ `allprojects`-Konfigurationsblock mit Gruppe, Version und gemeinsamen Repositories hinzugefügt
- ✅ Dependency-Analysis-Plugin hinzugefügt (Version 2.6.1)
- ✅ Versions-Plugin hinzugefügt (Version 0.51.0)
- ✅ Wrapper-Task auf Gradle 9.1.0 aktualisiert
### Phase 3: Convention Plugins
**Verzeichnis:** `buildSrc/src/main/kotlin/`
#### 3 Convention Plugins erstellt:
1. **`ktor-server-conventions.gradle.kts`**
- Für Ktor-Server-Module
- Wendet an: kotlin-jvm, ktor, serialization Plugins
- Konfiguriert: Java 21 Toolchain, Compiler-Optionen, Test-Konfiguration
2. **`spring-boot-service-conventions.gradle.kts`**
- Für Spring Boot Service-Module
- Wendet an: kotlin-jvm, spring-boot, dependency-management, kotlin-spring, kotlin-jpa Plugins
- Konfiguriert: Java 21 Toolchain, Compiler-Optionen, Test-Konfiguration, JPA All-Open
3. **`kotlin-multiplatform-conventions.gradle.kts`**
- Für KMP-Module (clients, shared)
- Wendet an: kotlin-multiplatform, serialization Plugins
- Konfiguriert: Java 21 Toolchain, Compiler-Optionen für alle Targets
### Phase 5: Gradle Properties
**Datei:** `gradle.properties`
#### Kotlin-Compiler-Optimierungen hinzugefügt:
```properties
kotlin.incremental=true
kotlin.incremental.multiplatform=true
kotlin.incremental.js=true
kotlin.caching.enabled=true
kotlin.compiler.execution.strategy=in-process
kotlin.compiler.preciseCompilationResultsBackup=true
kotlin.stdlib.default.dependency=true
```
---
## 🔄 Refactoring-Patterns
### Pattern 1: Spring Boot Services
**Gilt für:** Gateway, Auth-Server, Monitoring-Server, Ping-Service und alle Spring Boot-basierten Services
#### Vorher:
```kotlin
plugins {
alias(libs.plugins.kotlinJvm)
alias(libs.plugins.kotlinSpring)
alias(libs.plugins.spring.boot)
alias(libs.plugins.spring.dependencyManagement)
}
java {
toolchain {
languageVersion.set(JavaLanguageVersion.of(21))
}
}
tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
compilerOptions {
freeCompilerArgs.addAll("-Xjsr305=strict")
jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_21)
}
}
springBoot {
mainClass.set("com.example.MainKt")
buildInfo()
}
dependencies {
implementation(libs.spring.boot.starter.web)
implementation(libs.spring.boot.starter.validation)
implementation(libs.spring.boot.starter.actuator)
implementation(libs.spring.boot.starter.security)
implementation(libs.spring.boot.starter.oauth2.client)
implementation(libs.spring.boot.starter.oauth2.resource.server)
implementation(libs.resilience4j.spring.boot3)
implementation(libs.resilience4j.reactor)
implementation(libs.spring.boot.starter.aop)
implementation(libs.jackson.module.kotlin)
implementation(libs.jackson.datatype.jsr310)
implementation("ch.qos.logback:logback-classic")
implementation("ch.qos.logback:logback-core")
implementation("org.slf4j:slf4j-api")
// ... weitere Abhängigkeiten
}
```
#### Nachher:
```kotlin
plugins {
id("spring-boot-service-conventions")
}
springBoot {
mainClass.set("com.example.MainKt")
}
dependencies {
// Platform BOM
implementation(platform(projects.platform.platformBom))
// Projekt-Abhängigkeiten
implementation(projects.core.coreUtils)
implementation(projects.platform.platformDependencies)
// Complete Bundles
implementation(libs.bundles.spring.boot.service.complete)
implementation(libs.bundles.resilience)
implementation(libs.bundles.jackson.kotlin)
implementation(libs.bundles.logging)
// Spezifische Abhängigkeiten
implementation(libs.kotlin.reflect)
// ... andere spezifische Abhängigkeiten
// Tests
testImplementation(projects.platform.platformTesting)
testImplementation(libs.bundles.testing.jvm)
}
```
**Vorteile:**
- ~30-40% Reduktion der Codezeilen
- Keine manuelle Toolchain-/Compiler-Konfiguration
- Zentralisiertes Dependency-Management durch Bundles
- Konsistente Konfiguration über alle Spring Boot Services
---
### Pattern 2: Ktor Server Services
**Gilt für:** Alle Ktor-basierten Backend-Services (derzeit nicht im Projekt, aber Pattern verfügbar)
#### Verwendung:
```kotlin
plugins {
id("ktor-server-conventions")
}
ktor {
fatJar {
archiveFileName.set("service-name.jar")
}
}
dependencies {
implementation(platform(projects.platform.platformBom))
// Verwende Complete Ktor Bundle
implementation(libs.bundles.ktor.server.complete)
// Oder verwende spezifische Bundles für feinkörnige Kontrolle
implementation(libs.bundles.ktor.server.common)
implementation(libs.bundles.ktor.server.security)
implementation(libs.bundles.ktor.server.observability)
// Datenbank
implementation(libs.bundles.database.complete)
// Monitoring
implementation(libs.bundles.monitoring.complete)
// Tests
testImplementation(libs.bundles.testing.kmp)
testImplementation(libs.ktor.server.tests)
}
```
---
### Pattern 3: Kotlin Multiplatform Module
**Gilt für:** clients/app, clients/ping-feature, clients/auth-feature, clients/shared, core/core-utils, core/core-domain
#### Vorher:
```kotlin
plugins {
alias(libs.plugins.kotlinMultiplatform)
alias(libs.plugins.kotlinSerialization)
alias(libs.plugins.composeMultiplatform)
alias(libs.plugins.composeCompiler)
}
kotlin {
jvmToolchain(21)
jvm()
js(IR) { browser() }
sourceSets {
commonMain.dependencies {
implementation(libs.kotlinx.coroutines.core)
implementation(libs.kotlinx.serialization.json)
implementation(libs.kotlinx.datetime)
implementation(libs.ktor.client.core)
implementation(libs.ktor.client.contentNegotiation)
implementation(libs.ktor.client.serialization.kotlinx.json)
implementation(libs.ktor.client.logging)
implementation(libs.ktor.client.auth)
implementation(libs.androidx.lifecycle.viewmodelCompose)
implementation(libs.androidx.lifecycle.runtimeCompose)
}
}
}
tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
compilerOptions {
jvmTarget.set(JvmTarget.JVM_21)
freeCompilerArgs.addAll("-opt-in=kotlin.RequiresOptIn")
}
}
```
#### Nachher:
```kotlin
plugins {
id("kotlin-multiplatform-conventions")
alias(libs.plugins.composeMultiplatform)
alias(libs.plugins.composeCompiler)
}
kotlin {
jvm()
js(IR) { browser() }
sourceSets {
commonMain.dependencies {
// Verwende Bundles
implementation(libs.bundles.kotlinx.core)
implementation(libs.bundles.ktor.client.common)
implementation(libs.bundles.compose.common)
// Compose (vom Plugin)
implementation(compose.runtime)
implementation(compose.foundation)
implementation(compose.material3)
}
}
}
```
**Vorteile:**
- Entfernt Toolchain- und Compiler-Konfiguration-Boilerplate
- Bundles gruppieren verwandte Abhängigkeiten
- Sauberer und wartbarer
---
## 📋 Modul-Refactoring-Checkliste
### Infrastruktur-Module
#### ✅ Gateway (Abgeschlossen - Beispiel)
- Pattern: Spring Boot Service
- Zeilen reduziert: 113 → 90 (20%)
#### 🔲 Auth-Server
- Pattern: Spring Boot Service
- Ersetze Plugins durch `spring-boot-service-conventions`
- Verwende `spring-boot-service-complete`, `resilience`, `logging` Bundles
#### 🔲 Messaging-Config
- Pattern: Spring Boot Service
- Verwende `spring-boot-service-complete`, `kafka-config` Bundles
#### 🔲 Redis-Cache
- Pattern: Spring Boot Service
- Verwende `spring-boot-service-complete`, `redis-cache` Bundles
#### 🔲 Redis-Event-Store
- Pattern: Spring Boot Service
- Verwende `spring-boot-service-complete`, `redis-cache` Bundles
#### 🔲 Monitoring-Server
- Pattern: Spring Boot Service
- Verwende `spring-boot-service-complete`, `monitoring-complete` Bundles
### Service-Module
#### ✅ Ping-Service (Abgeschlossen - Beispiel)
- Pattern: Spring Boot Service
- Zeilen reduziert: 79 → 50 (37%)
#### 🔲 Ping-API
- Pattern: Kotlin Multiplatform (falls KMP) oder Kotlin JVM
- Verwende `kotlinx-core` Bundle
### Client-Module
#### 🔲 clients/app
- Pattern: Kotlin Multiplatform
- Verwende `kotlin-multiplatform-conventions`
- Verwende `kotlinx-core`, `compose-common` Bundles
#### 🔲 clients/ping-feature
- Pattern: Kotlin Multiplatform
- Verwendet bereits einige Bundles, stelle sicher, dass alle verwendet werden
#### 🔲 clients/auth-feature
- Pattern: Kotlin Multiplatform
- Verwende `kotlin-multiplatform-conventions`
- Verwende `kotlinx-core`, `ktor-client-common`, `compose-common` Bundles
#### 🔲 clients/shared Module
- Pattern: Kotlin Multiplatform
- Verwende `kotlin-multiplatform-conventions`
- Verwende `kotlinx-core` Bundle
### Core & Platform Module
#### 🔲 core/core-utils
- Pattern: Kotlin Multiplatform
- Verwende `kotlin-multiplatform-conventions`
- Verwende `kotlinx-core` Bundle
#### 🔲 core/core-domain
- Pattern: Kotlin Multiplatform
- Verwende `kotlin-multiplatform-conventions`
- Verwende `kotlinx-core` Bundle
#### 🔲 platform/platform-testing
- Pattern: Kotlin JVM
- Verwende `testing-kmp` oder `testing-jvm` Bundles
---
## 🚀 Empfohlene Build-Befehle
### Dependency-Analyse
```bash
./gradlew buildHealth
```
### Nach Dependency-Updates suchen
```bash
./gradlew dependencyUpdates
```
### Build mit Scan
```bash
./gradlew build --scan
```
### Dry Run für Task-Abhängigkeiten
```bash
./gradlew :services:ping:ping-service:build --dry-run
```
### Build-Performance messen
```bash
time ./gradlew clean build
```
---
## 📊 Erwartete Vorteile
### Build-Performance
- **Inkrementelle Kompilierung**: ~20-40% schnellere Rebuilds
- **Configuration Cache**: ~30-50% schnellere Konfigurationsphase (wenn aktiviert)
- **Parallele Ausführung**: Bessere Auslastung von Multi-Core-Systemen
### Wartbarkeit
- **Reduzierte Duplikation**: Convention Plugins eliminieren sich wiederholende Konfiguration
- **Zentralisierte Versionierung**: Single Source of Truth in `libs.versions.toml`
- **Einfachere Updates**: Dependency-Versionen an einem Ort aktualisieren
### Code-Metriken
- **Durchschnittliche Reduktion**: 20-40% weniger Zeilen pro Build-Datei
- **Konsistenz**: Alle Module folgen denselben Patterns
- **Type-Safety**: Version Catalog bietet IDE-Support und Compile-Time-Checking
---
## ⚠️ Wichtige Hinweise
### Configuration Cache
Derzeit deaktiviert aufgrund von JS-Test-Serialisierungsproblemen. Kann wieder aktiviert werden, sobald gelöst:
```properties
org.gradle.configuration-cache=true
```
### WASM-Unterstützung
Optional, aktivierbar über:
```properties
enableWasm=true
```
### Inkrementelles Refactoring
- Ein Modul nach dem anderen refactoren
- Nach jeder Änderung testen
- Demonstrierte Beispiele als Templates verwenden
---
## 📚 Referenzen
- **Gradle Version Catalogs**: https://docs.gradle.org/current/userguide/platforms.html
- **Convention Plugins**: https://docs.gradle.org/current/samples/sample_convention_plugins.html
- **Kotlin DSL**: https://docs.gradle.org/current/userguide/kotlin_dsl.html
Tagebuch/REFACTORING-GUIDE.md
-440
View File
@@ -1,440 +0,0 @@
# Gradle Build Refactoring Guide
## Overview
This guide documents the comprehensive Gradle build optimization completed in Phases 1-5, including practical refactoring patterns for all remaining modules.
---
## ✅ Completed Changes
### Phase 1: Bundles & Version Catalog
**File:** `gradle/libs.versions.toml`
#### Added Missing Libraries:
- `slf4j-api` (version 2.0.16)
- `kotlin-reflect` (uses kotlin version reference)
#### Added 5 New Complete Bundles:
1. **`ktor-server-complete`** - Full Ktor server stack (14 dependencies)
- Includes: core, netty, content-negotiation, serialization, status-pages, cors, default-headers, auth, auth-jwt, call-logging, metrics-micrometer, openapi, swagger, rate-limit
2. **`spring-boot-service-complete`** - Full Spring Boot service stack (12 dependencies)
- Includes: web, validation, actuator, security, oauth2-client, oauth2-resource-server, oauth2-jose, data-jpa, data-redis, micrometer-prometheus, tracing-bridge-brave, zipkin-reporter-brave
3. **`database-complete`** - Complete database stack (8 dependencies)
- Includes: exposed-core, exposed-dao, exposed-jdbc, exposed-kotlin-datetime, postgresql-driver, hikari-cp, flyway-core, flyway-postgresql
4. **`testing-kmp`** - KMP testing stack (8 dependencies)
- Includes: kotlin-test, junit-jupiter-api, junit-jupiter-engine, junit-jupiter-params, junit-platform-launcher, mockk, assertj-core, kotlinx-coroutines-test
5. **`monitoring-complete`** - Complete monitoring stack (8 dependencies)
- Includes: actuator, micrometer-prometheus, tracing-bridge-brave, zipkin-reporter-brave, zipkin-sender-okhttp3, kotlin-logging-jvm, logback-classic, slf4j-api
### Phase 2: Root Build File
**File:** `build.gradle.kts`
#### Enhancements:
- ✅ Added `allprojects` configuration block with group, version, and common repositories
- ✅ Added dependency-analysis plugin (version 2.6.1)
- ✅ Added versions plugin (version 0.51.0)
- ✅ Updated wrapper task to Gradle 9.1.0
### Phase 3: Convention Plugins
**Directory:** `buildSrc/src/main/kotlin/`
#### Created 3 Convention Plugins:
1. **`ktor-server-conventions.gradle.kts`**
- For Ktor server modules
- Applies: kotlin-jvm, ktor, serialization plugins
- Configures: Java 21 toolchain, compiler options, test configuration
2. **`spring-boot-service-conventions.gradle.kts`**
- For Spring Boot service modules
- Applies: kotlin-jvm, spring-boot, dependency-management, kotlin-spring, kotlin-jpa plugins
- Configures: Java 21 toolchain, compiler options, test configuration, JPA all-open
3. **`kotlin-multiplatform-conventions.gradle.kts`**
- For KMP modules (clients, shared)
- Applies: kotlin-multiplatform, serialization plugins
- Configures: Java 21 toolchain, compiler options for all targets
### Phase 5: Gradle Properties
**File:** `gradle.properties`
#### Added Kotlin Compiler Optimizations:
```properties
kotlin.incremental=true
kotlin.incremental.multiplatform=true
kotlin.incremental.js=true
kotlin.caching.enabled=true
kotlin.compiler.execution.strategy=in-process
kotlin.compiler.preciseCompilationResultsBackup=true
kotlin.stdlib.default.dependency=true
```
---
## 🔄 Refactoring Patterns
### Pattern 1: Spring Boot Services
**Applies to:** Gateway, Auth-Server, Monitoring-Server, Ping-Service, and all Spring Boot-based services
#### Before:
```kotlin
plugins {
alias(libs.plugins.kotlinJvm)
alias(libs.plugins.kotlinSpring)
alias(libs.plugins.spring.boot)
alias(libs.plugins.spring.dependencyManagement)
}
java {
toolchain {
languageVersion.set(JavaLanguageVersion.of(21))
}
}
tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
compilerOptions {
freeCompilerArgs.addAll("-Xjsr305=strict")
jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_21)
}
}
springBoot {
mainClass.set("com.example.MainKt")
buildInfo()
}
dependencies {
implementation(libs.spring.boot.starter.web)
implementation(libs.spring.boot.starter.validation)
implementation(libs.spring.boot.starter.actuator)
implementation(libs.spring.boot.starter.security)
implementation(libs.spring.boot.starter.oauth2.client)
implementation(libs.spring.boot.starter.oauth2.resource.server)
implementation(libs.resilience4j.spring.boot3)
implementation(libs.resilience4j.reactor)
implementation(libs.spring.boot.starter.aop)
implementation(libs.jackson.module.kotlin)
implementation(libs.jackson.datatype.jsr310)
implementation("ch.qos.logback:logback-classic")
implementation("ch.qos.logback:logback-core")
implementation("org.slf4j:slf4j-api")
// ... more dependencies
}
```
#### After:
```kotlin
plugins {
id("spring-boot-service-conventions")
}
springBoot {
mainClass.set("com.example.MainKt")
}
dependencies {
// Platform BOM
implementation(platform(projects.platform.platformBom))
// Project dependencies
implementation(projects.core.coreUtils)
implementation(projects.platform.platformDependencies)
// Complete bundles
implementation(libs.bundles.spring.boot.service.complete)
implementation(libs.bundles.resilience)
implementation(libs.bundles.jackson.kotlin)
implementation(libs.bundles.logging)
// Specific dependencies
implementation(libs.kotlin.reflect)
// ... other specific dependencies
// Tests
testImplementation(projects.platform.platformTesting)
testImplementation(libs.bundles.testing.jvm)
}
```
**Benefits:**
- ~30-40% reduction in lines of code
- No manual toolchain/compiler configuration
- Centralized dependency management through bundles
- Consistent configuration across all Spring Boot services
---
### Pattern 2: Ktor Server Services
**Applies to:** Any Ktor-based backend services (currently not in project, but pattern available)
#### Usage:
```kotlin
plugins {
id("ktor-server-conventions")
}
ktor {
fatJar {
archiveFileName.set("service-name.jar")
}
}
dependencies {
implementation(platform(projects.platform.platformBom))
// Use complete Ktor bundle
implementation(libs.bundles.ktor.server.complete)
// Or use specific bundles for fine-grained control
implementation(libs.bundles.ktor.server.common)
implementation(libs.bundles.ktor.server.security)
implementation(libs.bundles.ktor.server.observability)
// Database
implementation(libs.bundles.database.complete)
// Monitoring
implementation(libs.bundles.monitoring.complete)
// Tests
testImplementation(libs.bundles.testing.kmp)
testImplementation(libs.ktor.server.tests)
}
```
---
### Pattern 3: Kotlin Multiplatform Modules
**Applies to:** clients/app, clients/ping-feature, clients/auth-feature, clients/shared, core/core-utils, core/core-domain
#### Before:
```kotlin
plugins {
alias(libs.plugins.kotlinMultiplatform)
alias(libs.plugins.kotlinSerialization)
alias(libs.plugins.composeMultiplatform)
alias(libs.plugins.composeCompiler)
}
kotlin {
jvmToolchain(21)
jvm()
js(IR) { browser() }
sourceSets {
commonMain.dependencies {
implementation(libs.kotlinx.coroutines.core)
implementation(libs.kotlinx.serialization.json)
implementation(libs.kotlinx.datetime)
implementation(libs.ktor.client.core)
implementation(libs.ktor.client.contentNegotiation)
implementation(libs.ktor.client.serialization.kotlinx.json)
implementation(libs.ktor.client.logging)
implementation(libs.ktor.client.auth)
implementation(libs.androidx.lifecycle.viewmodelCompose)
implementation(libs.androidx.lifecycle.runtimeCompose)
}
}
}
tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
compilerOptions {
jvmTarget.set(JvmTarget.JVM_21)
freeCompilerArgs.addAll("-opt-in=kotlin.RequiresOptIn")
}
}
```
#### After:
```kotlin
plugins {
id("kotlin-multiplatform-conventions")
alias(libs.plugins.composeMultiplatform)
alias(libs.plugins.composeCompiler)
}
kotlin {
jvm()
js(IR) { browser() }
sourceSets {
commonMain.dependencies {
// Use bundles
implementation(libs.bundles.kotlinx.core)
implementation(libs.bundles.ktor.client.common)
implementation(libs.bundles.compose.common)
// Compose (from plugin)
implementation(compose.runtime)
implementation(compose.foundation)
implementation(compose.material3)
}
}
}
```
**Benefits:**
- Removes toolchain and compiler configuration boilerplate
- Bundles group related dependencies
- Cleaner and more maintainable
---
## 📋 Module Refactoring Checklist
### Infrastructure Modules
#### ✅ Gateway (Completed - Example)
- Pattern: Spring Boot Service
- Lines reduced: 113 → 90 (20%)
#### 🔲 Auth-Server
- Pattern: Spring Boot Service
- Replace plugins with `spring-boot-service-conventions`
- Use `spring-boot-service-complete`, `resilience`, `logging` bundles
#### 🔲 Messaging-Config
- Pattern: Spring Boot Service
- Use `spring-boot-service-complete`, `kafka-config` bundles
#### 🔲 Redis-Cache
- Pattern: Spring Boot Service
- Use `spring-boot-service-complete`, `redis-cache` bundles
#### 🔲 Redis-Event-Store
- Pattern: Spring Boot Service
- Use `spring-boot-service-complete`, `redis-cache` bundles
#### 🔲 Monitoring-Server
- Pattern: Spring Boot Service
- Use `spring-boot-service-complete`, `monitoring-complete` bundles
### Service Modules
#### ✅ Ping-Service (Completed - Example)
- Pattern: Spring Boot Service
- Lines reduced: 79 → 50 (37%)
#### 🔲 Ping-API
- Pattern: Kotlin Multiplatform (if KMP) or Kotlin JVM
- Use `kotlinx-core` bundle
### Client Modules
#### 🔲 clients/app
- Pattern: Kotlin Multiplatform
- Use `kotlin-multiplatform-conventions`
- Use `kotlinx-core`, `compose-common` bundles
#### 🔲 clients/ping-feature
- Pattern: Kotlin Multiplatform
- Already uses some bundles, ensure all are used
#### 🔲 clients/auth-feature
- Pattern: Kotlin Multiplatform
- Use `kotlin-multiplatform-conventions`
- Use `kotlinx-core`, `ktor-client-common`, `compose-common` bundles
#### 🔲 clients/shared modules
- Pattern: Kotlin Multiplatform
- Use `kotlin-multiplatform-conventions`
- Use `kotlinx-core` bundle
### Core & Platform Modules
#### 🔲 core/core-utils
- Pattern: Kotlin Multiplatform
- Use `kotlin-multiplatform-conventions`
- Use `kotlinx-core` bundle
#### 🔲 core/core-domain
- Pattern: Kotlin Multiplatform
- Use `kotlin-multiplatform-conventions`
- Use `kotlinx-core` bundle
#### 🔲 platform/platform-testing
- Pattern: Kotlin JVM
- Use `testing-kmp` or `testing-jvm` bundles
---
## 🚀 Recommended Build Commands
### Dependency Analysis
```bash
./gradlew buildHealth
```
### Check for Dependency Updates
```bash
./gradlew dependencyUpdates
```
### Build with Scan
```bash
./gradlew build --scan
```
### Dry Run for Task Dependencies
```bash
./gradlew :services:ping:ping-service:build --dry-run
```
### Measure Build Performance
```bash
time ./gradlew clean build
```
---
## 📊 Expected Benefits
### Build Performance
- **Incremental compilation**: ~20-40% faster rebuilds
- **Configuration cache**: ~30-50% faster configuration phase (when enabled)
- **Parallel execution**: Better utilization of multi-core systems
### Maintainability
- **Reduced duplication**: Convention plugins eliminate repetitive configuration
- **Centralized versioning**: Single source of truth in `libs.versions.toml`
- **Easier updates**: Update dependency versions in one place
### Code Metrics
- **Average reduction**: 20-40% fewer lines per build file
- **Consistency**: All modules follow same patterns
- **Type safety**: Version catalog provides IDE support and compile-time checking
---
## ⚠️ Important Notes
### Configuration Cache
Currently disabled due to JS test serialization issues. Can be re-enabled once resolved:
```properties
org.gradle.configuration-cache=true
```
### WASM Support
Optional, enable via:
```properties
enableWasm=true
```
### Incremental Refactoring
- Refactor one module at a time
- Test after each change
- Use demonstrated examples as templates
---
## 📚 References
- **Gradle Version Catalogs**: https://docs.gradle.org/current/userguide/platforms.html
- **Convention Plugins**: https://docs.gradle.org/current/samples/sample_convention_plugins.html
- **Kotlin DSL**: https://docs.gradle.org/current/userguide/kotlin_dsl.html
Tagebuch/Trace-Bullet-Bericht.md
-116
View File
@@ -1,116 +0,0 @@
# Trace-Bullet Abschlussbericht: End-to-End Service-Kommunikation
### Status: ✅ 100% ABGESCHLOSSEN & VERIFIZIERT
---
### 1. Zielsetzung und Ergebnis
Dieses Dokument bestätigt den erfolgreichen Abschluss des **Trace-Bullets**, dessen Ziel die Verifizierung der
fundamentalen End-to-End-Kommunikation der Systemarchitektur war.
**Ergebnis:** Der Kommunikationsfluss von der Client-Anwendung über das API-Gateway bis zu einem Backend-Microservice
ist vollständig funktionsfähig. Dies beweist, dass die Kernarchitektur robust, korrekt konfiguriert und bereit für die
Entwicklung weiterer Fach-Services ist.
---
### 2. Verifizierter Architektur-Flow
Der Test validiert das nahtlose Zusammenspiel aller kritischen Infrastruktur-Komponenten in der korrekten Reihenfolge:
**Der verifizierte End-to-End-Flow:**
`Client(Desktop/Web)` -> `API Gateway (Port 8081)` -> `Consul` -> `Ping-Service (Port 8082)` ->
`Antwort zurück an Client`
---
### 3. Implementierungs-Checkliste
Alle für das Trace-Bullet erforderlichen Komponenten wurden erfolgreich implementiert und integriert:
#### ✅ **Backend-Infrastruktur**
- **Docker-Services:** Alle Basisdienste (PostgreSQL, Redis, Consul, etc.) sind containerisiert und betriebsbereit.
- **API-Gateway:** Der Gateway-Service ist als zentraler Eingangspunkt auf Port `8081` konfiguriert und leitet Anfragen
korrekt weiter.
#### ✅ **Ping-Microservice**
- **Service-Logik:** Der `ping-service` ist als eigenständiger Spring-Boot-Microservice implementiert.
- **Service-Registrierung:** Der Service registriert sich zuverlässig bei Consul und ist für das Gateway dynamisch
auffindbar.
#### ✅ **Client-Anwendung**
- **Multiplattform-UI:** Die Benutzeroberfläche ist mit Compose Multiplatform umgesetzt und läuft plattformunabhängig
auf Desktop (JVM) und im Web (WASM).
- **API-Kommunikation:** Der Ktor-Client ruft den korrekten Gateway-Endpunkt (`/api/ping`) auf und verarbeitet die
Antwort reaktiv in der UI.
---
### 4. Bedeutung für das Projekt
Der erfolgreiche Abschluss dieses Trace-Bullets ist mehr als nur ein technischer Test; er ist das **fundamentale
Fundament für das gesamte Projekt**:
* **Risikominimierung:** Die Kernarchitektur ist verifiziert, was das Risiko bei der Entwicklung komplexer Features
erheblich reduziert.
* **Entwicklungs-Blaupause:** Der `ping-service` und die Client-Anbindung dienen als perfekte Vorlage (Blueprint) für
alle zukünftigen Microservices und deren Integration.
* **Beschleunigte Entwicklung:** Teams können nun auf einer bewährten Grundlage aufbauen, ohne die Kerninfrastruktur in
Frage stellen zu müssen.
---
### 5. Anleitung zur Reproduktion
Der erfolgreiche End-to-End-Test kann jederzeit wie folgt reproduziert werden:
1. **Backend starten:**
```bash
# Startet die gesamte Docker-Infrastruktur inkl. Gateway
docker-compose up -d
```
2. **Ping-Service starten:**
```bash
# Startet den Microservice in einem separaten Terminal
./gradlew :temp:ping-service:bootRun
```
*(Optional: In der Consul UI auf `http://localhost:8500` prüfen, ob der `ping-service` als "healthy" registriert
ist.)*
3. **Client starten:**
```bash
# Option A: Desktop-App
./gradlew :client:run
# Option B: Web-App (erreichbar unter http://localhost:8080)
./gradlew :client:wasmJsBrowserDevelopmentRun
```
4. **Test ausführen:**
Ein Klick auf den **"Ping Backend"**-Button in der Anwendung bestätigt den erfolgreichen Kommunikationsfluss durch
die Anzeige der "✅ Ping erfolgreich!"-Meldung.
---
### 6. Tracing validiert
Zur Validierung des Distributed Tracing wurden Micrometer Tracing (Brave) und Zipkin im `ping-service` und im `api-gateway` aktiviert. So lässt sich der vollständige Pfad einer Anfrage nachvollziehen.
Schnellanleitung:
- Backend/Infra starten (docker-compose) und Services hochfahren (Gateway + Ping-Service).
- Einen Request auslösen:
- Browser: http://localhost:8081/api/ping/ping
- CLI: curl -s http://localhost:8081/api/ping/ping
- Zipkin UI öffnen: http://localhost:9411
- Nach Service filtern: `api-gateway` oder `ping-service`
- Einen Trace öffnen und die zwei Spans (Gateway ↔ Ping) prüfen
Optionaler Smoke-Test (CLI):
- scripts/smoke/zipkin_smoke.sh – erzeugt einen Request und prüft über die Zipkin-API, ob Traces vorhanden sind.
- scripts/smoke/prometheus_smoke.sh – prüft `/actuator/prometheus` am Gateway und am Ping-Service.
docs/BILINGUAL_DOCUMENTATION_INDEX.md
-130
View File
@@ -1,130 +0,0 @@
# Bilingual Documentation Index / Zweisprachiger Dokumentations-Index
## Overview / Übersicht
This document provides a comprehensive index of all bilingual documentation available in the Meldestelle project. All technical documentation is provided in both English and German versions to ensure accessibility for all team members and stakeholders.
Dieses Dokument bietet einen umfassenden Index aller zweisprachigen Dokumentation im Meldestelle-Projekt. Alle technische Dokumentation wird sowohl in englischer als auch in deutscher Version bereitgestellt, um die Zugänglichkeit für alle Teammitglieder und Stakeholder zu gewährleisten.
## Summary Documents / Zusammenfassungs-Dokumente
### Database Implementation / Datenbank-Implementierung
| English | German | Description |
|---------|--------|-------------|
| [DATABASE_FIXES_SUMMARY.md](./database/DATABASE_FIXES_SUMMARY.md) | [DATABASE_FIXES_SUMMARY-de.md](./database/DATABASE_FIXES_SUMMARY-de.md) | Database initialization fixes implementation summary |
| [DATABASE_DIAGNOSTIC_REPORT-en.md](./database/DATABASE_DIAGNOSTIC_REPORT-en.md) | [DATABASE_DIAGNOSTIC_REPORT.md](./database/DATABASE_DIAGNOSTIC_REPORT.md) | Comprehensive database diagnostic analysis |
| [STARTUP_ORDER_ANALYSIS.md](./database/STARTUP_ORDER_ANALYSIS.md) | [STARTUP_ORDER_ANALYSIS-de.md](./database/STARTUP_ORDER_ANALYSIS-de.md) | Startup order coordination analysis |
### Service Implementation / Service-Implementierung
| English | German | Description |
|---------|--------|-------------|
| [IMPLEMENTATION_SUMMARY.md](./implementation/IMPLEMENTATION_SUMMARY.md) | [IMPLEMENTATION_SUMMARY-de.md](./implementation/IMPLEMENTATION_SUMMARY-de.md) | Overall service implementation summary |
| [HORSES_MODULE_OPTIMIZATION_SUMMARY.md](./modules/HORSES_MODULE_OPTIMIZATION_SUMMARY.md) | [HORSES_MODULE_OPTIMIZATION_SUMMARY-de.md](./modules/HORSES_MODULE_OPTIMIZATION_SUMMARY-de.md) | Horses module analysis and optimization |
| [MEMBERS_MODULE_OPTIMIZATION_SUMMARY.md](./modules/MEMBERS_MODULE_OPTIMIZATION_SUMMARY.md) | [MEMBERS_MODULE_OPTIMIZATION_SUMMARY-de.md](./modules/MEMBERS_MODULE_OPTIMIZATION_SUMMARY-de.md) | Members module analysis and optimization |
### Client Implementation / Client-Implementierung
| English | German | Description |
|---------|--------|-------------|
| [CLIENT_OPTIMIZATION_SUMMARY-en.md](./client/CLIENT_OPTIMIZATION_SUMMARY-en.md) | [CLIENT_OPTIMIZATION_SUMMARY.md](./client/CLIENT_OPTIMIZATION_SUMMARY.md) | Client implementation optimization summary |
## Architecture Documentation / Architektur-Dokumentation
### Architecture Decision Records (ADRs)
| English | German | Description |
|---------|--------|-------------|
| [docs/architecture/adr/0004-event-driven-communication.md](./docs/architecture/adr/0004-event-driven-communication.md) | [docs/architecture/adr/0004-event-driven-communication-de.md](./docs/architecture/adr/0004-event-driven-communication-de.md) | Event-driven communication pattern |
| [docs/architecture/adr/0005-polyglot-persistence.md](./docs/architecture/adr/0005-polyglot-persistence.md) | [docs/architecture/adr/0005-polyglot-persistence-de.md](./docs/architecture/adr/0005-polyglot-persistence-de.md) | Polyglot persistence strategy |
| [docs/architecture/adr/0006-authentication-authorization-keycloak.md](./docs/architecture/adr/0006-authentication-authorization-keycloak.md) | [docs/architecture/adr/0006-authentication-authorization-keycloak-de.md](./docs/architecture/adr/0006-authentication-authorization-keycloak-de.md) | Authentication and authorization with Keycloak |
| [docs/architecture/adr/0007-api-gateway-pattern.md](./docs/architecture/adr/0007-api-gateway-pattern.md) | [docs/architecture/adr/0007-api-gateway-pattern-de.md](./docs/architecture/adr/0007-api-gateway-pattern-de.md) | API Gateway pattern implementation |
| [docs/architecture/adr/0008-multiplatform-client-applications.md](./docs/architecture/adr/0008-multiplatform-client-applications.md) | [docs/architecture/adr/0008-multiplatform-client-applications-de.md](./docs/architecture/adr/0008-multiplatform-client-applications-de.md) | Multiplatform client applications |
### C4 Architecture Diagrams
| English | German | Description |
|---------|--------|-------------|
| [docs/architecture/c4/03-component-events-service.puml](./docs/architecture/c4/03-component-events-service.puml) | [docs/architecture/c4/03-component-events-service-de.puml](./docs/architecture/c4/03-component-events-service-de.puml) | Events service component diagram |
## Development Documentation / Entwicklungs-Dokumentation
| English | German | Description |
|---------|--------|-------------|
| [docs/development/getting-started.md](./docs/development/getting-started.md) | [docs/development/getting-started-de.md](./docs/development/getting-started-de.md) | Getting started guide for developers |
| [docs/development/environment-variables.md](./docs/development/environment-variables.md) | [docs/development/environment-variables-de.md](./docs/development/environment-variables-de.md) | Environment variables documentation |
## Migration Documentation / Migrations-Dokumentation
| English | German | Description |
|---------|--------|-------------|
| [docs/migration-summary.md](./docs/migration-summary.md) | [docs/migration-summary-de.md](./docs/migration-summary-de.md) | Migration summary and recommendations |
| [docs/migration-status.md](./docs/migration-status.md) | [docs/migration-status-de.md](./docs/migration-status-de.md) | Current migration status |
| [docs/migration-plan.md](./docs/migration-plan.md) | [docs/migration-plan-de.md](./docs/migration-plan-de.md) | Detailed migration plan |
## Implementation Reports / Implementierungs-Berichte
| English | German | Description |
|---------|--------|-------------|
| [docs/final-report.md](./docs/final-report.md) | [docs/final-report-de.md](./docs/final-report-de.md) | Final implementation report |
| [docs/client-data-fetching-implementation-summary.md](./docs/client-data-fetching-implementation-summary.md) | [docs/client-data-fetching-implementation-summary-de.md](./docs/client-data-fetching-implementation-summary-de.md) | Client data fetching implementation |
## Configuration Documentation / Konfigurations-Dokumentation
| English | German | Description |
|---------|--------|-------------|
| [config/ssl/README.md](./config/ssl/README.md) | [config/ssl/README-de.md](./config/ssl/README-de.md) | SSL configuration guide |
## Documentation Standards / Dokumentations-Standards
### Naming Convention / Namenskonvention
- **English documents**: Use standard filename (e.g., `document-name.md`)
- **German documents**: Add `-de` suffix (e.g., `document-name-de.md`)
- **Englische Dokumente**: Verwenden Sie den Standard-Dateinamen (z.B. `document-name.md`)
- **Deutsche Dokumente**: Fügen Sie das Suffix `-de` hinzu (z.B. `document-name-de.md`)
### Content Standards / Inhalts-Standards
- All technical documentation must be available in both languages
- Translations should maintain technical accuracy and consistency
- Code examples and technical terms should remain consistent across languages
- Update dates should be synchronized between language versions
- Alle technische Dokumentation muss in beiden Sprachen verfügbar sein
- Übersetzungen sollten technische Genauigkeit und Konsistenz beibehalten
- Code-Beispiele und technische Begriffe sollten sprachübergreifend konsistent bleiben
- Aktualisierungsdaten sollten zwischen den Sprachversionen synchronisiert werden
## Validation / Validierung
The project includes automated validation scripts to ensure documentation completeness:
Das Projekt enthält automatisierte Validierungsskripte zur Sicherstellung der Dokumentationsvollständigkeit:
- `scripts/validation/validate-docs.sh` - Validates bilingual documentation coverage
- `scripts/validation/validate-docs.sh` - Validiert die zweisprachige Dokumentationsabdeckung
## Contributing / Mitwirken
When creating or updating documentation:
Beim Erstellen oder Aktualisieren von Dokumentation:
1. **Always provide both language versions** / **Stellen Sie immer beide Sprachversionen bereit**
2. **Maintain consistent formatting** / **Behalten Sie konsistente Formatierung bei**
3. **Update this index when adding new documents** / **Aktualisieren Sie diesen Index beim Hinzufügen neuer Dokumente**
4. **Run validation scripts before committing** / **Führen Sie Validierungsskripte vor dem Commit aus**
## Last Updated / Letzte Aktualisierung
- **Date / Datum**: July 25, 2025 / 25. Juli 2025
- **Version / Version**: 1.0.0
- **Total Documents / Gesamtdokumente**: 14 bilingual pairs / 14 zweisprachige Paare
---
*This index is automatically maintained and should be updated whenever new bilingual documentation is added to the project.*
*Dieser Index wird automatisch gepflegt und sollte aktualisiert werden, wenn neue zweisprachige Dokumentation zum Projekt hinzugefügt wird.*
docs/INDEX.md
-229
View File
@@ -1,229 +0,0 @@
# Meldestelle Documentation Index
## 📚 Vollständige Dokumentationsübersicht
Willkommen zur umfassenden Dokumentation des Meldestelle-Systems. Diese Übersicht bietet strukturierten Zugang zu allen verfügbaren Dokumenten und Ressourcen.
---
## 🏗️ Architektur und Design
### Hauptdokumentation
- **[Projekt-Übersicht](../README.md)** - Systemüberblick und Schnellstart
- **[Produktionsumgebung](../README-PRODUCTION.md)** - Produktions-Setup und Sicherheit
- **[Umgebungsvariablen](../README-ENV.md)** - Konfiguration und Setup
### Architektur-Dokumentation
- **[Architektur-Übersicht](architecture/)** - Systemarchitektur und Design-Entscheidungen
- **[C4-Diagramme](architecture/c4/)** - Visuelle Architektur-Darstellung
---
## 🔧 Module-Dokumentation
### Core-Module
- **[Core Module](../core/README.md)** - Shared Kernel und gemeinsame Komponenten
- Domain-Modelle und Enumerationen
- Utilities und Konfiguration
- Fehlerbehandlung und Validierung
- Service Discovery
### Geschäfts-Module
#### Members (Mitgliederverwaltung)
- **[Members Module](../members/README.md)** - Umfassende Mitgliederverwaltung
- 18+ Repository-Operationen
- Mitgliedschafts-Tracking
- Validierung und Geschäftsregeln
#### Horses (Pferderegistrierung)
- **[Horses Module](../horses/README.md)** - Pferderegistrierung und -verwaltung
- 25+ Repository-Operationen
- OEPS/FEI-Integration
- Identifikationsnummern-Verwaltung
#### Events (Veranstaltungsverwaltung)
- **[Events Module](../events/README.md)** - Veranstaltungsplanung und -verwaltung
- 10+ Repository-Operationen
- Terminverwaltung
- Sparten-Management
#### Masterdata (Stammdatenverwaltung)
- **[Masterdata Module](../masterdata/README.md)** - Stammdaten für das gesamte System
- 37+ REST-Endpunkte
- Länder, Bundesländer, Altersklassen
- Turnierplätze und Austragungsorte
### Infrastruktur-Module
- **[Infrastructure Module](../infrastructure/README.md)** - Technische Infrastruktur
- Authentication & Authorization
- Caching und Event Store
- API Gateway und Messaging
- Monitoring und Observability
### Client-Module
- **[Client Module](../client/README.md)** - Benutzeroberflächen
- Web-Anwendung und Desktop-App
- Repository-Pattern und API-Client
- UI-Komponenten und Theme System
---
## 🔌 API-Dokumentation
### REST-API-Übersicht
- **[API-Übersicht](api/README.md)** - Vollständige REST-API-Dokumentation
- Technische Spezifikationen
- Authentifizierung und Autorisierung
- Rate Limiting und Fehlerbehandlung
### Modul-spezifische APIs
- **[Members API](api/members-api.md)** - Mitgliederverwaltung API
- 12 REST-Endpunkte
- Datenmodelle und Validierung
- Praktische Workflows
### Automatisch generierte API-Dokumentation
- **[Generated OpenAPI Specs](api/generated/)** - Automatisch generierte OpenAPI-Spezifikationen
- Members API OpenAPI
- Horses API OpenAPI
- Events API OpenAPI
- Masterdata API OpenAPI
---
## 👨‍💻 Entwicklerdokumentation
### Erste Schritte
- **[Entwicklungsanleitung](development/getting-started-de.md)** - Vollständige Einrichtungsanleitung
- Systemanforderungen und Software-Installation
- Projekt-Setup und IDE-Konfiguration
- Entwicklungsworkflows und Debugging
### Umgebung und Konfiguration
- **[Umgebungsvariablen](development/environment-variables-de.md)** - Detaillierte Konfigurationsdokumentation
### Implementierung
- **[Redis-Integration](implementation/redis-integration-de.md)** - Redis-Implementierungsdetails
---
## 🔄 Migration und Deployment
### Migration
- **[Migrations-Plan](migration-plan-de.md)** - Detaillierter Migrationsplan
- **[Migrations-Zusammenfassung](migration-summary-de.md)** - Übersicht abgeschlossener Aufgaben
- **[Migrations-Status](migration-status-de.md)** - Aktueller Migrationsstatus
- **[Verbleibende Aufgaben](migration-remaining-tasks-de.md)** - Noch zu erledigende Arbeiten
- **[Abschlussbericht](final-report-de.md)** - Projekt-Restrukturierung Abschlussbericht
### SSL und Sicherheit
- **[SSL-Konfiguration](../config/ssl/README-de.md)** - Produktions-SSL-Setup
---
## 🎨 Client-Entwicklung
### Architektur und Patterns
- **[Client-Implementierung](client-data-fetching-implementation-summary-de.md)** - Datenabruf und Zustandsverwaltung
- **[Client-Verbesserungen](client-data-fetching-improvements-de.md)** - Zukünftige Erweiterungen
---
## 📊 Dokumentations-Management
### Qualitätssicherung
- **[Dokumentations-Updates](documentation-updates-summary.md)** - Vollständige Übersicht aller Dokumentationsaktualisierungen
- 18 neue Dokumentationsdateien
- 6.012 Zeilen hochwertige Dokumentation
- 100% Modulabdeckung
### Automatisierung
- **Automatische Validierung**: CI/CD-Pipeline für Dokumentationsqualität
- **OpenAPI-Generierung**: Automatische API-Dokumentationsgenerierung
- **Link-Validierung**: Automatische Überprüfung aller Dokumentationslinks
---
## 🔍 Schnellzugriff
### Nach Zielgruppe
#### Neue Entwickler
1. [Entwicklungsanleitung](development/getting-started-de.md)
2. [Projekt-Übersicht](../README.md)
3. [Core Module](../core/README.md)
4. [API-Übersicht](api/README.md)
#### API-Entwickler
1. [API-Übersicht](api/README.md)
2. [Members API](api/members-api.md)
3. [Generated OpenAPI Specs](api/generated/)
4. [Authentifizierung](../README-PRODUCTION.md#sicherheit)
#### DevOps-Engineers
1. [Produktionsumgebung](../README-PRODUCTION.md)
2. [SSL-Konfiguration](../config/ssl/README-de.md)
3. [Umgebungsvariablen](../README-ENV.md)
4. [Infrastructure Module](../infrastructure/README.md)
#### Architekten
1. [Architektur-Dokumentation](architecture/)
2. [C4-Diagramme](architecture/c4/)
3. [Migrations-Plan](migration-plan-de.md)
4. [Abschlussbericht](final-report-de.md)
### Nach Technologie
#### Backend (Kotlin/Spring Boot)
- [Core Module](../core/README.md)
- [Members Module](../members/README.md)
- [Infrastructure Module](../infrastructure/README.md)
#### Frontend (Compose)
- [Client Module](../client/README.md)
- [Client-Implementierung](client-data-fetching-implementation-summary-de.md)
#### Datenbank (PostgreSQL)
- [Migrations-Plan](migration-plan-de.md)
- [Entwicklungsanleitung](development/getting-started-de.md#datenbank-migrationen)
#### Infrastruktur (Docker/Kubernetes)
- [Produktionsumgebung](../README-PRODUCTION.md)
- [Infrastructure Module](../infrastructure/README.md)
---
## 📈 Dokumentationsstatistiken
- **📄 Dokumentationsdateien**: 18 neue Dateien erstellt
- **📝 Gesamtzeilen**: 6.012 Zeilen hochwertiger Dokumentation
- **🎯 Modulabdeckung**: 100% (6/6 Module vollständig dokumentiert)
- **🔗 API-Abdeckung**: 100% (vollständige REST-API-Dokumentation)
- **🇩🇪 Deutsche Inhalte**: 95% aller Dokumentation auf Deutsch verfügbar
- **💡 Code-Beispiele**: 200+ praktische Code-Snippets
---
## 🔄 Letzte Aktualisierungen
**25. Juli 2025**: Umfassende Dokumentationsaktualisierung
- Alle Module vollständig dokumentiert
- Deutsche Übersetzungen erstellt
- API-Dokumentation vervollständigt
- Entwicklungsanleitungen hinzugefügt
- Automatisierung implementiert
---
## 📞 Support und Beitrag
- **Issue Tracker**: GitHub Issues für Dokumentationsfehler
- **Verbesserungsvorschläge**: Pull Requests willkommen
- **Automatische Validierung**: CI/CD-Pipeline prüft alle Änderungen
---
**Letzte Aktualisierung**: 25. Juli 2025
**Dokumentationsversion**: 1.0
**Vollständigkeit**: 100%
docs/api/README.md
+2 -2
View File
@@ -36,12 +36,12 @@ API Services
### Entwicklungsumgebung
```
Base URL: http://localhost:8080/api
Base URL: http://localhost:8081/api
```
### Produktionsumgebung
```
Base URL: https://api.meldestelle.at/api
Base URL: https://api.meldestelle.yourdomain.com/api
```
## API-Module Übersicht
docs/client/CLIENT_OPTIMIZATION_SUMMARY-de.md
+189
View File
@@ -0,0 +1,189 @@
# Client Implementation Optimization Summary
## Übersicht
Dieses Dokument fasst die durchgeführten Optimierungen der Client-Implementierungen im Meldestelle-System zusammen. Die Optimierungen zielen darauf ab, Code-Duplikation zu reduzieren, die Architektur zu verbessern und die Build-Konfigurationen zu optimieren.
## Durchgeführte Optimierungen
### 1. Konfigurierbare API-Client-Einstellungen ✅
**Datei:** `client/common-ui/src/main/kotlin/at/mocode/client/common/config/ApiConfig.kt`
**Verbesserungen:**
- Umgebungsvariablen-basierte Konfiguration für API-Einstellungen
- Konfigurierbare Base-URL, Timeouts, Cache-Einstellungen
- Unterstützung für System Properties und Umgebungsvariablen
- Logging-Konfiguration
**Vorteile:**
- Flexibilität für verschiedene Umgebungen (Dev, Test, Prod)
- Keine hardcodierten Werte mehr
- Einfache Konfiguration ohne Code-Änderungen
### 2. Verbesserte Cache-Implementierung ✅
**Datei:** `client/common-ui/src/main/kotlin/at/mocode/client/common/cache/ApiCache.kt`
**Verbesserungen:**
- LRU (Least Recently Used) Eviction-Strategie
- Thread-sichere Implementierung mit ReentrantReadWriteLock
- Konfigurierbare Cache-Größe und TTL
- Pattern-basierte Cache-Invalidierung
- Cache-Statistiken und Cleanup-Funktionen
**Vorteile:**
- Bessere Speicherverwaltung durch Größenbegrenzung
- Verbesserte Performance durch intelligente Eviction
- Konsistente Daten durch automatische Invalidierung
- Monitoring-Möglichkeiten durch Statistiken
### 3. Base Repository Klasse ✅
**Datei:** `client/common-ui/src/main/kotlin/at/mocode/client/common/repository/BaseClientRepository.kt`
**Verbesserungen:**
- Gemeinsame CRUD-Operationen für alle Repositories
- Einheitliche Fehlerbehandlung
- Konsistente Logging-Mechanismen
- Cache-Invalidierung nach Änderungsoperationen
- Wiederverwendbare Suchmethoden
**Vorteile:**
- Eliminierung von Code-Duplikation zwischen Repositories
- Konsistente Fehlerbehandlung über alle Repositories
- Einfachere Wartung und Erweiterung
- Reduzierte Entwicklungszeit für neue Repositories
### 4. Optimierte Repository-Implementierung ✅
**Datei:** `client/common-ui/src/main/kotlin/at/mocode/client/common/repository/OptimizedClientPersonRepository.kt`
**Verbesserungen:**
- Nutzung der BaseClientRepository-Klasse
- Automatische Cache-Invalidierung nach Änderungen
- Verbesserte Fehlerbehandlung
- Konsistente Logging-Mechanismen
**Vorteile:**
- Weniger Code-Duplikation
- Bessere Wartbarkeit
- Konsistente Funktionalität
### 5. Optimierte Build-Konfigurationen ✅
#### Desktop App (`client/desktop-app/build.gradle.kts.optimized`)
**Entfernte unnötige Dependencies:**
- Spring Boot (nicht für Desktop-Client benötigt)
- Redis-Dependencies (Redisson, Lettuce)
- Direkte Domain-Modul-Dependencies
- Unnötige Infrastructure-Dependencies
**Hinzugefügte Verbesserungen:**
- Desktop-spezifische Coroutines (swing statt javafx)
- Native Distribution-Konfiguration
- Plattform-spezifische Icons und Packaging
#### Web App (`client/web-app/build.gradle.kts.optimized`)
**Entfernte unnötige Dependencies:**
- Direkte Domain-Modul-Dependencies
- Members-Application-Layer-Dependencies
- Unnötige Infrastructure-Dependencies
**Hinzugefügte Verbesserungen:**
- Web-spezifische Compose-Dependencies
- Bessere Test-Dependencies (MockK, JUnit 5)
- Web-spezifische Coroutines
## Architektur-Verbesserungen
### Vor der Optimierung:
```
Desktop App
├── Spring Boot ❌
├── Redis Dependencies ❌
├── Direct Domain Access ❌
├── Heavy Infrastructure ❌
└── Code Duplication ❌
Web App
├── Direct Domain Access ❌
├── Application Layer Dependencies ❌
├── Inconsistent Error Handling ❌
└── Code Duplication ❌
```
### Nach der Optimierung:
```
Desktop App
├── Minimal Dependencies ✅
├── API-Only Access ✅
├── Shared Components ✅
└── Clean Architecture ✅
Web App
├── API-Only Access ✅
├── Shared Base Classes ✅
├── Consistent Error Handling ✅
└── Optimized Dependencies ✅
```
## Quantifizierte Verbesserungen
### Code-Reduktion:
- **Repository Code:** ~60% Reduktion durch BaseClientRepository
- **Build Dependencies:** ~40% Reduktion in Desktop App
- **Build Dependencies:** ~30% Reduktion in Web App
### Performance-Verbesserungen:
- **Cache Efficiency:** LRU-Eviction statt einfacher TTL
- **Memory Usage:** Begrenzte Cache-Größe verhindert Memory Leaks
- **Build Time:** Weniger Dependencies = schnellere Builds
### Wartbarkeit:
- **Einheitliche Fehlerbehandlung** über alle Repositories
- **Konfigurierbare Einstellungen** ohne Code-Änderungen
- **Konsistente Logging-Mechanismen**
- **Wiederverwendbare Komponenten**
## Identifizierte weitere Optimierungsmöglichkeiten
### Kurzfristig:
1. **Logging Framework:** Ersetzen von `println` durch SLF4J
2. **Retry Logic:** Implementierung von Retry-Mechanismen für API-Calls
3. **Connection Pooling:** Optimierung der HTTP-Client-Konfiguration
4. **Request/Response Interceptors:** Für Monitoring und Debugging
### Mittelfristig:
1. **Reactive Streams:** Migration zu reaktiven Datenströmen
2. **Offline Support:** Implementierung von Offline-Funktionalität
3. **Progressive Web App:** Erweiterung der Web-App zu PWA
4. **State Management:** Implementierung von zentralem State Management
### Langfristig:
1. **Microservices Gateway:** Implementierung eines API-Gateways
2. **GraphQL Integration:** Migration von REST zu GraphQL
3. **Real-time Updates:** WebSocket-Integration für Live-Updates
4. **Mobile Apps:** Erweiterung um native Mobile Apps
## Empfohlene nächste Schritte
1. **Tests aktualisieren:** Die bestehenden Tests sind zu stark an Domain-Layer gekoppelt und sollten refactored werden
2. **Logging Framework einführen:** SLF4J statt println verwenden
3. **Optimierte Build-Konfigurationen aktivieren:** Die `.optimized` Dateien als Standard übernehmen
4. **Monitoring implementieren:** Cache-Statistiken und API-Performance überwachen
5. **Dokumentation erweitern:** API-Dokumentation und Entwickler-Guidelines erstellen
## Fazit
Die durchgeführten Optimierungen verbessern die Client-Implementierungen erheblich:
- **Reduzierte Komplexität** durch weniger Dependencies
- **Bessere Wartbarkeit** durch gemeinsame Base-Klassen
- **Verbesserte Performance** durch optimierte Caching-Strategien
- **Flexiblere Konfiguration** durch umgebungsbasierte Einstellungen
- **Sauberere Architektur** durch API-only Zugriff auf Backend-Services
Diese Optimierungen legen eine solide Grundlage für die weitere Entwicklung und Skalierung des Meldestelle-Systems.
docs/client/CLIENT_OPTIMIZATION_SUMMARY-en.md
-193
View File
@@ -1,193 +0,0 @@
# Client Implementation Optimization Summary
## Overview
This document summarizes the optimizations performed on the client implementations in the Meldestelle system. The optimizations aim to reduce code duplication, improve architecture, and optimize build configurations.
## Performed Optimizations
### 1. Configurable API Client Settings ✅
**File:** `client/common-ui/src/main/kotlin/at/mocode/client/common/config/ApiConfig.kt`
**Improvements:**
- Environment variable-based configuration for API settings
- Configurable base URL, timeouts, cache settings
- Support for system properties and environment variables
- Logging configuration
**Benefits:**
- Flexibility for different environments (Dev, Test, Prod)
- No more hardcoded values
- Easy configuration without code changes
### 2. Improved Cache Implementation ✅
**File:** `client/common-ui/src/main/kotlin/at/mocode/client/common/cache/ApiCache.kt`
**Improvements:**
- LRU (Least Recently Used) eviction strategy
- Thread-safe implementation with ReentrantReadWriteLock
- Configurable cache size and TTL
- Pattern-based cache invalidation
- Cache statistics and cleanup functions
**Benefits:**
- Better memory management through size limitation
- Improved performance through intelligent eviction
- Consistent data through automatic invalidation
- Monitoring capabilities through statistics
### 3. Base Repository Class ✅
**File:** `client/common-ui/src/main/kotlin/at/mocode/client/common/repository/BaseClientRepository.kt`
**Improvements:**
- Common CRUD operations for all repositories
- Unified error handling
- Consistent logging mechanisms
- Cache invalidation after modification operations
- Reusable search methods
**Benefits:**
- Elimination of code duplication between repositories
- Consistent error handling across all repositories
- Easier maintenance and extension
- Reduced development time for new repositories
### 4. Optimized Repository Implementation ✅
**File:** `client/common-ui/src/main/kotlin/at/mocode/client/common/repository/OptimizedClientPersonRepository.kt`
**Improvements:**
- Usage of BaseClientRepository class
- Automatic cache invalidation after changes
- Improved error handling
- Consistent logging mechanisms
**Benefits:**
- Less code duplication
- Better maintainability
- Consistent functionality
### 5. Optimized Build Configurations ✅
#### Desktop App (`client/desktop-app/build.gradle.kts.optimized`)
**Removed unnecessary dependencies:**
- Spring Boot (not needed for desktop client)
- Redis dependencies (Redisson, Lettuce)
- Direct domain module dependencies
- Unnecessary infrastructure dependencies
**Added improvements:**
- Desktop-specific coroutines (swing instead of javafx)
- Native distribution configuration
- Platform-specific icons and packaging
#### Web App (`client/web-app/build.gradle.kts.optimized`)
**Removed unnecessary dependencies:**
- Direct domain module dependencies
- Members application layer dependencies
- Unnecessary infrastructure dependencies
**Added improvements:**
- Web-specific Compose dependencies
- Better test dependencies (MockK, JUnit 5)
- Web-specific coroutines
## Architecture Improvements
### Before Optimization:
```
Desktop App
├── Spring Boot ❌
├── Redis Dependencies ❌
├── Direct Domain Access ❌
├── Heavy Infrastructure ❌
└── Code Duplication ❌
Web App
├── Direct Domain Access ❌
├── Application Layer Dependencies ❌
├── Inconsistent Error Handling ❌
└── Code Duplication ❌
```
### After Optimization:
```
Desktop App
├── Minimal Dependencies ✅
├── API-Only Access ✅
├── Shared Components ✅
└── Clean Architecture ✅
Web App
├── API-Only Access ✅
├── Shared Base Classes ✅
├── Consistent Error Handling ✅
└── Optimized Dependencies ✅
```
## Quantified Improvements
### Code Reduction:
- **Repository Code:** ~60% reduction through BaseClientRepository
- **Build Dependencies:** ~40% reduction in Desktop App
- **Build Dependencies:** ~30% reduction in Web App
### Performance Improvements:
- **Cache Efficiency:** LRU eviction instead of simple TTL
- **Memory Usage:** Limited cache size prevents memory leaks
- **Build Time:** Fewer dependencies = faster builds
### Maintainability:
- **Unified error handling** across all repositories
- **Configurable settings** without code changes
- **Consistent logging mechanisms**
- **Reusable components**
## Identified Further Optimization Opportunities
### Short-term:
1. **Logging Framework:** Replace `println` with SLF4J
2. **Retry Logic:** Implement retry mechanisms for API calls
3. **Connection Pooling:** Optimize HTTP client configuration
4. **Request/Response Interceptors:** For monitoring and debugging
### Medium-term:
1. **Reactive Streams:** Migration to reactive data streams
2. **Offline Support:** Implementation of offline functionality
3. **Progressive Web App:** Extension of web app to PWA
4. **State Management:** Implementation of central state management
### Long-term:
1. **Microservices Gateway:** Implementation of an API gateway
2. **GraphQL Integration:** Migration from REST to GraphQL
3. **Real-time Updates:** WebSocket integration for live updates
4. **Mobile Apps:** Extension with native mobile apps
## Recommended Next Steps
1. **Update tests:** Existing tests are too tightly coupled to domain layer and should be refactored
2. **Introduce logging framework:** Use SLF4J instead of println
3. **Activate optimized build configurations:** Adopt the `.optimized` files as standard
4. **Implement monitoring:** Monitor cache statistics and API performance
5. **Expand documentation:** Create API documentation and developer guidelines
## Conclusion
The performed optimizations significantly improve the client implementations:
- **Reduced complexity** through fewer dependencies
- **Better maintainability** through shared base classes
- **Improved performance** through optimized caching strategies
- **More flexible configuration** through environment-based settings
- **Cleaner architecture** through API-only access to backend services
These optimizations lay a solid foundation for further development and scaling of the Meldestelle system.
---
*Last updated: July 25, 2025*
docs/client/CLIENT_OPTIMIZATION_SUMMARY.md
+120 -116
View File
@@ -1,105 +1,105 @@
# Client Implementation Optimization Summary
## Übersicht
## Overview
Dieses Dokument fasst die durchgeführten Optimierungen der Client-Implementierungen im Meldestelle-System zusammen. Die Optimierungen zielen darauf ab, Code-Duplikation zu reduzieren, die Architektur zu verbessern und die Build-Konfigurationen zu optimieren.
This document summarizes the optimizations performed on the client implementations in the Meldestelle system. The optimizations aim to reduce code duplication, improve architecture, and optimize build configurations.
## Durchgeführte Optimierungen
## Performed Optimizations
### 1. Konfigurierbare API-Client-Einstellungen ✅
### 1. Configurable API Client Settings ✅
**Datei:** `client/common-ui/src/main/kotlin/at/mocode/client/common/config/ApiConfig.kt`
**File:** `client/common-ui/src/main/kotlin/at/mocode/client/common/config/ApiConfig.kt`
**Verbesserungen:**
- Umgebungsvariablen-basierte Konfiguration für API-Einstellungen
- Konfigurierbare Base-URL, Timeouts, Cache-Einstellungen
- Unterstützung für System Properties und Umgebungsvariablen
- Logging-Konfiguration
**Improvements:**
- Environment variable-based configuration for API settings
- Configurable base URL, timeouts, cache settings
- Support for system properties and environment variables
- Logging configuration
**Vorteile:**
- Flexibilität für verschiedene Umgebungen (Dev, Test, Prod)
- Keine hardcodierten Werte mehr
- Einfache Konfiguration ohne Code-Änderungen
**Benefits:**
- Flexibility for different environments (Dev, Test, Prod)
- No more hardcoded values
- Easy configuration without code changes
### 2. Verbesserte Cache-Implementierung ✅
### 2. Improved Cache Implementation ✅
**Datei:** `client/common-ui/src/main/kotlin/at/mocode/client/common/cache/ApiCache.kt`
**File:** `client/common-ui/src/main/kotlin/at/mocode/client/common/cache/ApiCache.kt`
**Verbesserungen:**
- LRU (Least Recently Used) Eviction-Strategie
- Thread-sichere Implementierung mit ReentrantReadWriteLock
- Konfigurierbare Cache-Größe und TTL
- Pattern-basierte Cache-Invalidierung
- Cache-Statistiken und Cleanup-Funktionen
**Improvements:**
- LRU (Least Recently Used) eviction strategy
- Thread-safe implementation with ReentrantReadWriteLock
- Configurable cache size and TTL
- Pattern-based cache invalidation
- Cache statistics and cleanup functions
**Vorteile:**
- Bessere Speicherverwaltung durch Größenbegrenzung
- Verbesserte Performance durch intelligente Eviction
- Konsistente Daten durch automatische Invalidierung
- Monitoring-Möglichkeiten durch Statistiken
**Benefits:**
- Better memory management through size limitation
- Improved performance through intelligent eviction
- Consistent data through automatic invalidation
- Monitoring capabilities through statistics
### 3. Base Repository Klasse ✅
### 3. Base Repository Class ✅
**Datei:** `client/common-ui/src/main/kotlin/at/mocode/client/common/repository/BaseClientRepository.kt`
**File:** `client/common-ui/src/main/kotlin/at/mocode/client/common/repository/BaseClientRepository.kt`
**Verbesserungen:**
- Gemeinsame CRUD-Operationen für alle Repositories
- Einheitliche Fehlerbehandlung
- Konsistente Logging-Mechanismen
- Cache-Invalidierung nach Änderungsoperationen
- Wiederverwendbare Suchmethoden
**Improvements:**
- Common CRUD operations for all repositories
- Unified error handling
- Consistent logging mechanisms
- Cache invalidation after modification operations
- Reusable search methods
**Vorteile:**
- Eliminierung von Code-Duplikation zwischen Repositories
- Konsistente Fehlerbehandlung über alle Repositories
- Einfachere Wartung und Erweiterung
- Reduzierte Entwicklungszeit für neue Repositories
**Benefits:**
- Elimination of code duplication between repositories
- Consistent error handling across all repositories
- Easier maintenance and extension
- Reduced development time for new repositories
### 4. Optimierte Repository-Implementierung ✅
### 4. Optimized Repository Implementation ✅
**Datei:** `client/common-ui/src/main/kotlin/at/mocode/client/common/repository/OptimizedClientPersonRepository.kt`
**File:** `client/common-ui/src/main/kotlin/at/mocode/client/common/repository/OptimizedClientPersonRepository.kt`
**Verbesserungen:**
- Nutzung der BaseClientRepository-Klasse
- Automatische Cache-Invalidierung nach Änderungen
- Verbesserte Fehlerbehandlung
- Konsistente Logging-Mechanismen
**Improvements:**
- Usage of BaseClientRepository class
- Automatic cache invalidation after changes
- Improved error handling
- Consistent logging mechanisms
**Vorteile:**
- Weniger Code-Duplikation
- Bessere Wartbarkeit
- Konsistente Funktionalität
**Benefits:**
- Less code duplication
- Better maintainability
- Consistent functionality
### 5. Optimierte Build-Konfigurationen ✅
### 5. Optimized Build Configurations ✅
#### Desktop App (`client/desktop-app/build.gradle.kts.optimized`)
**Entfernte unnötige Dependencies:**
- Spring Boot (nicht für Desktop-Client benötigt)
- Redis-Dependencies (Redisson, Lettuce)
- Direkte Domain-Modul-Dependencies
- Unnötige Infrastructure-Dependencies
**Removed unnecessary dependencies:**
- Spring Boot (not needed for desktop client)
- Redis dependencies (Redisson, Lettuce)
- Direct domain module dependencies
- Unnecessary infrastructure dependencies
**Hinzugefügte Verbesserungen:**
- Desktop-spezifische Coroutines (swing statt javafx)
- Native Distribution-Konfiguration
- Plattform-spezifische Icons und Packaging
**Added improvements:**
- Desktop-specific coroutines (swing instead of javafx)
- Native distribution configuration
- Platform-specific icons and packaging
#### Web App (`client/web-app/build.gradle.kts.optimized`)
**Entfernte unnötige Dependencies:**
- Direkte Domain-Modul-Dependencies
- Members-Application-Layer-Dependencies
- Unnötige Infrastructure-Dependencies
**Removed unnecessary dependencies:**
- Direct domain module dependencies
- Members application layer dependencies
- Unnecessary infrastructure dependencies
**Hinzugefügte Verbesserungen:**
- Web-spezifische Compose-Dependencies
- Bessere Test-Dependencies (MockK, JUnit 5)
- Web-spezifische Coroutines
**Added improvements:**
- Web-specific Compose dependencies
- Better test dependencies (MockK, JUnit 5)
- Web-specific coroutines
## Architektur-Verbesserungen
## Architecture Improvements
### Vor der Optimierung:
### Before Optimization:
```
Desktop App
├── Spring Boot ❌
@@ -115,7 +115,7 @@ Web App
└── Code Duplication ❌
```
### Nach der Optimierung:
### After Optimization:
```
Desktop App
├── Minimal Dependencies ✅
@@ -130,60 +130,64 @@ Web App
└── Optimized Dependencies ✅
```
## Quantifizierte Verbesserungen
## Quantified Improvements
### Code-Reduktion:
- **Repository Code:** ~60% Reduktion durch BaseClientRepository
- **Build Dependencies:** ~40% Reduktion in Desktop App
- **Build Dependencies:** ~30% Reduktion in Web App
### Code Reduction:
- **Repository Code:** ~60% reduction through BaseClientRepository
- **Build Dependencies:** ~40% reduction in Desktop App
- **Build Dependencies:** ~30% reduction in Web App
### Performance-Verbesserungen:
- **Cache Efficiency:** LRU-Eviction statt einfacher TTL
- **Memory Usage:** Begrenzte Cache-Größe verhindert Memory Leaks
- **Build Time:** Weniger Dependencies = schnellere Builds
### Performance Improvements:
- **Cache Efficiency:** LRU eviction instead of simple TTL
- **Memory Usage:** Limited cache size prevents memory leaks
- **Build Time:** Fewer dependencies = faster builds
### Wartbarkeit:
- **Einheitliche Fehlerbehandlung** über alle Repositories
- **Konfigurierbare Einstellungen** ohne Code-Änderungen
- **Konsistente Logging-Mechanismen**
- **Wiederverwendbare Komponenten**
### Maintainability:
- **Unified error handling** across all repositories
- **Configurable settings** without code changes
- **Consistent logging mechanisms**
- **Reusable components**
## Identifizierte weitere Optimierungsmöglichkeiten
## Identified Further Optimization Opportunities
### Kurzfristig:
1. **Logging Framework:** Ersetzen von `println` durch SLF4J
2. **Retry Logic:** Implementierung von Retry-Mechanismen für API-Calls
3. **Connection Pooling:** Optimierung der HTTP-Client-Konfiguration
4. **Request/Response Interceptors:** Für Monitoring und Debugging
### Short-term:
1. **Logging Framework:** Replace `println` with SLF4J
2. **Retry Logic:** Implement retry mechanisms for API calls
3. **Connection Pooling:** Optimize HTTP client configuration
4. **Request/Response Interceptors:** For monitoring and debugging
### Mittelfristig:
1. **Reactive Streams:** Migration zu reaktiven Datenströmen
2. **Offline Support:** Implementierung von Offline-Funktionalität
3. **Progressive Web App:** Erweiterung der Web-App zu PWA
4. **State Management:** Implementierung von zentralem State Management
### Medium-term:
1. **Reactive Streams:** Migration to reactive data streams
2. **Offline Support:** Implementation of offline functionality
3. **Progressive Web App:** Extension of web app to PWA
4. **State Management:** Implementation of central state management
### Langfristig:
1. **Microservices Gateway:** Implementierung eines API-Gateways
2. **GraphQL Integration:** Migration von REST zu GraphQL
3. **Real-time Updates:** WebSocket-Integration für Live-Updates
4. **Mobile Apps:** Erweiterung um native Mobile Apps
### Long-term:
1. **Microservices Gateway:** Implementation of an API gateway
2. **GraphQL Integration:** Migration from REST to GraphQL
3. **Real-time Updates:** WebSocket integration for live updates
4. **Mobile Apps:** Extension with native mobile apps
## Empfohlene nächste Schritte
## Recommended Next Steps
1. **Tests aktualisieren:** Die bestehenden Tests sind zu stark an Domain-Layer gekoppelt und sollten refactored werden
2. **Logging Framework einführen:** SLF4J statt println verwenden
3. **Optimierte Build-Konfigurationen aktivieren:** Die `.optimized` Dateien als Standard übernehmen
4. **Monitoring implementieren:** Cache-Statistiken und API-Performance überwachen
5. **Dokumentation erweitern:** API-Dokumentation und Entwickler-Guidelines erstellen
1. **Update tests:** Existing tests are too tightly coupled to domain layer and should be refactored
2. **Introduce logging framework:** Use SLF4J instead of println
3. **Activate optimized build configurations:** Adopt the `.optimized` files as standard
4. **Implement monitoring:** Monitor cache statistics and API performance
5. **Expand documentation:** Create API documentation and developer guidelines
## Fazit
## Conclusion
Die durchgeführten Optimierungen verbessern die Client-Implementierungen erheblich:
The performed optimizations significantly improve the client implementations:
- **Reduzierte Komplexität** durch weniger Dependencies
- **Bessere Wartbarkeit** durch gemeinsame Base-Klassen
- **Verbesserte Performance** durch optimierte Caching-Strategien
- **Flexiblere Konfiguration** durch umgebungsbasierte Einstellungen
- **Sauberere Architektur** durch API-only Zugriff auf Backend-Services
- **Reduced complexity** through fewer dependencies
- **Better maintainability** through shared base classes
- **Improved performance** through optimized caching strategies
- **More flexible configuration** through environment-based settings
- **Cleaner architecture** through API-only access to backend services
Diese Optimierungen legen eine solide Grundlage für die weitere Entwicklung und Skalierung des Meldestelle-Systems.
These optimizations lay a solid foundation for further development and scaling of the Meldestelle system.
---
*Last updated: July 25, 2025*
docs/database/DATABASE_DIAGNOSTIC_REPORT-de.md
+148
View File
@@ -0,0 +1,148 @@
# Database Diagnostic Report - Exposed Framework Initialization
## Diagnose Ergebnisse
### ✅ Database.connect() Aufrufe identifiziert
**Zentrale Implementierung:**
- **DatabaseFactory.kt** (Zeile 66): `Database.connect(dataSource!!)`
- Verwendet HikariCP Connection Pooling
- Singleton-Pattern mit proper Konfiguration
- Unterstützt Verbindungsvalidierung und Leak-Detection
**Service-spezifische Konfigurationen:**
- **Events Service**: EventsDatabaseConfiguration.kt - verwendet DatabaseFactory.init()
- **Horses Service**: DatabaseConfiguration.kt - verwendet DatabaseFactory.init()
- **Members Service**: MembersDatabaseConfiguration.kt - verwendet DatabaseFactory.init()
- **Masterdata Service**: MasterdataDatabaseConfiguration.kt - verwendet DatabaseFactory.init()
**⚠️ PROBLEM IDENTIFIZIERT - Gateway Konfiguration:**
- **Gateway**: DatabaseConfig.kt (Zeile 25-30) - **direkter Database.connect() Aufruf**
```kotlin
Database.connect(
url = databaseUrl,
driver = "org.postgresql.Driver",
user = databaseUser,
password = databasePassword
)
```
### ✅ Exposed-Operationen (Transaktionen, Queries) lokalisiert
**Schema-Initialisierung (in @PostConstruct):**
- Alle Services: `transaction { SchemaUtils.createMissingTablesAndColumns(...) }`
- Gateway: `transaction { SchemaUtils.createMissingTablesAndColumns(...) }` für alle Kontexte
**Business Logic Transaktionen:**
- **TransactionalCreateHorseUseCase**: Verwendet `DatabaseFactory.dbQuery { ... }`
- **DatabaseMigrator**: Verwendet `transaction { ... }` für Migrationen
**Test-Transaktionen:**
- SimpleDatabaseTest.kt: Direkte `transaction { ... }` Aufrufe in Tests
### ✅ Initialisierungsreihenfolge analysiert
**Korrekte Reihenfolge in Services:**
1. `@PostConstruct` → `DatabaseFactory.init(config)` → `Database.connect()`
2. Sofort danach: `transaction { SchemaUtils.createMissingTablesAndColumns(...) }`
3. Business Logic: `DatabaseFactory.dbQuery { ... }` für Transaktionen
**⚠️ PROBLEM - Gateway Initialisierung:**
1. Ktor Application.configureDatabase() → direkter `Database.connect()`
2. Sofort danach: `transaction { ... }` für alle Service-Schemas
## 🚨 Identifizierte Probleme
### 1. **Inkonsistente Database.connect() Implementierung**
- **Services**: Verwenden zentralen DatabaseFactory mit Connection Pooling
- **Gateway**: Direkter Database.connect() ohne Connection Pooling
- **Risiko**: Unterschiedliche Verbindungsqualität und -management
### 2. **Potentielle Race Conditions**
- Gateway und Services initialisieren unabhängig voneinander
- Beide versuchen, Schemas für dieselben Tabellen zu erstellen
- **Risiko**: Konflikte bei paralleler Initialisierung
### 3. **Verletzung der Separation of Concerns**
- Gateway verwaltet Schemas für alle Services
- Services verwalten ihre eigenen Schemas
- **Risiko**: Doppelte Schema-Initialisierung
### 4. **Fehlende Initialisierungsreihenfolge-Garantien**
- Keine explizite Abhängigkeitsreihenfolge zwischen Gateway und Services
- **Risiko**: Exposed-Operationen vor Database.connect()
## ✅ Empfehlungen
### 1. **Gateway auf DatabaseFactory umstellen**
```kotlin
// Statt direktem Database.connect():
fun Application.configureDatabase() {
val config = DatabaseConfig.fromEnv() // oder aus Ktor Config
DatabaseFactory.init(config)
// Schema-Initialisierung entfernen oder koordinieren
}
```
### 2. **Schema-Initialisierung koordinieren**
**Option A**: Nur Services verwalten ihre Schemas (empfohlen)
```kotlin
// Gateway: Nur Verbindung, keine Schema-Initialisierung
fun Application.configureDatabase() {
DatabaseFactory.init(DatabaseConfig.fromEnv())
}
```
**Option B**: Zentralisierte Schema-Verwaltung
```kotlin
// Separater DatabaseSchemaInitializer mit @Order Annotation
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
class DatabaseSchemaInitializer {
@PostConstruct
fun initializeAllSchemas() {
// Schema initialization logic
}
}
```
### 3. **Startup-Reihenfolge sicherstellen**
```kotlin
// Services mit @DependsOn
@Configuration
@DependsOn("databaseInitializer")
class HorsesDatabaseConfiguration {
// Configuration logic
}
```
### 4. **Einheitliche Konfiguration**
```kotlin
// Alle Komponenten verwenden DatabaseFactory
class SomeService {
suspend fun doSomething() {
DatabaseFactory.dbQuery {
// Exposed operations
}
}
}
```
## 📋 Zusammenfassung
**✅ Korrekt implementiert:**
- Alle Services verwenden proper @PostConstruct → Database.connect() → Exposed operations Reihenfolge
- DatabaseFactory bietet robuste Connection Pool Konfiguration
- Business Logic verwendet korrekte Transaktionsmuster
**⚠️ Zu beheben:**
- Gateway Database.connect() Inkonsistenz
- Potentielle Race Conditions bei Schema-Initialisierung
- Fehlende Startup-Reihenfolge-Koordination
**🎯 Priorität:**
1. **Hoch**: Gateway auf DatabaseFactory umstellen
2. **Mittel**: Schema-Initialisierung koordinieren
3. **Niedrig**: Startup-Reihenfolge explizit definieren
Die Reihenfolge der Initialisierung ist grundsätzlich korrekt, aber die Inkonsistenz zwischen Gateway und Services sollte behoben werden, um potentielle Probleme zu vermeiden.
docs/database/DATABASE_DIAGNOSTIC_REPORT-en.md
-152
View File
@@ -1,152 +0,0 @@
# Database Diagnostic Report - Exposed Framework Initialization
## Diagnostic Results
### ✅ Database.connect() Calls Identified
**Central Implementation:**
- **DatabaseFactory.kt** (Line 66): `Database.connect(dataSource!!)`
- Uses HikariCP Connection Pooling
- Singleton pattern with proper configuration
- Supports connection validation and leak detection
**Service-specific Configurations:**
- **Events Service**: EventsDatabaseConfiguration.kt - uses DatabaseFactory.init()
- **Horses Service**: DatabaseConfiguration.kt - uses DatabaseFactory.init()
- **Members Service**: MembersDatabaseConfiguration.kt - uses DatabaseFactory.init()
- **Masterdata Service**: MasterdataDatabaseConfiguration.kt - uses DatabaseFactory.init()
**⚠️ PROBLEM IDENTIFIED - Gateway Configuration:**
- **Gateway**: DatabaseConfig.kt (Lines 25-30) - **direct Database.connect() call**
```kotlin
Database.connect(
url = databaseUrl,
driver = "org.postgresql.Driver",
user = databaseUser,
password = databasePassword
)
```
### ✅ Exposed Operations (Transactions, Queries) Located
**Schema Initialization (in @PostConstruct):**
- All Services: `transaction { SchemaUtils.createMissingTablesAndColumns(...) }`
- Gateway: `transaction { SchemaUtils.createMissingTablesAndColumns(...) }` for all contexts
**Business Logic Transactions:**
- **TransactionalCreateHorseUseCase**: Uses `DatabaseFactory.dbQuery { ... }`
- **DatabaseMigrator**: Uses `transaction { ... }` for migrations
**Test Transactions:**
- SimpleDatabaseTest.kt: Direct `transaction { ... }` calls in tests
### ✅ Initialization Order Analyzed
**Correct Order in Services:**
1. `@PostConstruct` → `DatabaseFactory.init(config)` → `Database.connect()`
2. Immediately after: `transaction { SchemaUtils.createMissingTablesAndColumns(...) }`
3. Business Logic: `DatabaseFactory.dbQuery { ... }` for transactions
**⚠️ PROBLEM - Gateway Initialization:**
1. Ktor Application.configureDatabase() → direct `Database.connect()`
2. Immediately after: `transaction { ... }` for all service schemas
## 🚨 Identified Problems
### 1. **Inconsistent Database.connect() Implementation**
- **Services**: Use central DatabaseFactory with Connection Pooling
- **Gateway**: Direct Database.connect() without Connection Pooling
- **Risk**: Different connection quality and management
### 2. **Potential Race Conditions**
- Gateway and services initialize independently
- Both attempt to create schemas for the same tables
- **Risk**: Conflicts during parallel initialization
### 3. **Violation of Separation of Concerns**
- Gateway manages schemas for all services
- Services manage their own schemas
- **Risk**: Duplicate schema initialization
### 4. **Missing Initialization Order Guarantees**
- No explicit dependency order between Gateway and Services
- **Risk**: Exposed operations before Database.connect()
## ✅ Recommendations
### 1. **Switch Gateway to DatabaseFactory**
```kotlin
// Instead of direct Database.connect():
fun Application.configureDatabase() {
val config = DatabaseConfig.fromEnv() // or from Ktor Config
DatabaseFactory.init(config)
// Remove or coordinate schema initialization
}
```
### 2. **Coordinate Schema Initialization**
**Option A**: Only services manage their schemas (recommended)
```kotlin
// Gateway: Only connection, no schema initialization
fun Application.configureDatabase() {
DatabaseFactory.init(DatabaseConfig.fromEnv())
}
```
**Option B**: Centralized schema management
```kotlin
// Separate DatabaseSchemaInitializer with @Order annotation
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
class DatabaseSchemaInitializer {
@PostConstruct
fun initializeAllSchemas() {
// Schema initialization logic
}
}
```
### 3. **Ensure Startup Order**
```kotlin
// Services with @DependsOn
@Configuration
@DependsOn("databaseInitializer")
class HorsesDatabaseConfiguration {
// Configuration logic
}
```
### 4. **Unified Configuration**
```kotlin
// All components use DatabaseFactory
class SomeService {
suspend fun doSomething() {
DatabaseFactory.dbQuery {
// Exposed operations
}
}
}
```
## 📋 Summary
**✅ Correctly implemented:**
- All services use proper @PostConstruct → Database.connect() → Exposed operations sequence
- DatabaseFactory provides robust Connection Pool configuration
- Business logic uses correct transaction patterns
**⚠️ To be fixed:**
- Gateway Database.connect() inconsistency
- Potential race conditions in schema initialization
- Missing startup order coordination
**🎯 Priority:**
1. **High**: Switch Gateway to DatabaseFactory
2. **Medium**: Coordinate schema initialization
3. **Low**: Explicitly define startup order
The initialization sequence is fundamentally correct, but the inconsistency between Gateway and Services should be resolved to avoid potential problems.
---
*Last updated: July 25, 2025*
docs/database/DATABASE_DIAGNOSTIC_REPORT.md
+78 -74
View File
@@ -1,23 +1,23 @@
# Database Diagnostic Report - Exposed Framework Initialization
## Diagnose Ergebnisse
## Diagnostic Results
### ✅ Database.connect() Aufrufe identifiziert
### ✅ Database.connect() Calls Identified
**Zentrale Implementierung:**
- **DatabaseFactory.kt** (Zeile 66): `Database.connect(dataSource!!)`
- Verwendet HikariCP Connection Pooling
- Singleton-Pattern mit proper Konfiguration
- Unterstützt Verbindungsvalidierung und Leak-Detection
**Central Implementation:**
- **DatabaseFactory.kt** (Line 66): `Database.connect(dataSource!!)`
- Uses HikariCP Connection Pooling
- Singleton pattern with proper configuration
- Supports connection validation and leak detection
**Service-spezifische Konfigurationen:**
- **Events Service**: EventsDatabaseConfiguration.kt - verwendet DatabaseFactory.init()
- **Horses Service**: DatabaseConfiguration.kt - verwendet DatabaseFactory.init()
- **Members Service**: MembersDatabaseConfiguration.kt - verwendet DatabaseFactory.init()
- **Masterdata Service**: MasterdataDatabaseConfiguration.kt - verwendet DatabaseFactory.init()
**Service-specific Configurations:**
- **Events Service**: EventsDatabaseConfiguration.kt - uses DatabaseFactory.init()
- **Horses Service**: DatabaseConfiguration.kt - uses DatabaseFactory.init()
- **Members Service**: MembersDatabaseConfiguration.kt - uses DatabaseFactory.init()
- **Masterdata Service**: MasterdataDatabaseConfiguration.kt - uses DatabaseFactory.init()
**⚠️ PROBLEM IDENTIFIZIERT - Gateway Konfiguration:**
- **Gateway**: DatabaseConfig.kt (Zeile 25-30) - **direkter Database.connect() Aufruf**
**⚠️ PROBLEM IDENTIFIED - Gateway Configuration:**
- **Gateway**: DatabaseConfig.kt (Lines 25-30) - **direct Database.connect() call**
```kotlin
Database.connect(
url = databaseUrl,
@@ -27,75 +27,75 @@
)
```
### ✅ Exposed-Operationen (Transaktionen, Queries) lokalisiert
### ✅ Exposed Operations (Transactions, Queries) Located
**Schema-Initialisierung (in @PostConstruct):**
- Alle Services: `transaction { SchemaUtils.createMissingTablesAndColumns(...) }`
- Gateway: `transaction { SchemaUtils.createMissingTablesAndColumns(...) }` für alle Kontexte
**Schema Initialization (in @PostConstruct):**
- All Services: `transaction { SchemaUtils.createMissingTablesAndColumns(...) }`
- Gateway: `transaction { SchemaUtils.createMissingTablesAndColumns(...) }` for all contexts
**Business Logic Transaktionen:**
- **TransactionalCreateHorseUseCase**: Verwendet `DatabaseFactory.dbQuery { ... }`
- **DatabaseMigrator**: Verwendet `transaction { ... }` für Migrationen
**Business Logic Transactions:**
- **TransactionalCreateHorseUseCase**: Uses `DatabaseFactory.dbQuery { ... }`
- **DatabaseMigrator**: Uses `transaction { ... }` for migrations
**Test-Transaktionen:**
- SimpleDatabaseTest.kt: Direkte `transaction { ... }` Aufrufe in Tests
**Test Transactions:**
- SimpleDatabaseTest.kt: Direct `transaction { ... }` calls in tests
### ✅ Initialisierungsreihenfolge analysiert
### ✅ Initialization Order Analyzed
**Korrekte Reihenfolge in Services:**
**Correct Order in Services:**
1. `@PostConstruct` → `DatabaseFactory.init(config)` → `Database.connect()`
2. Sofort danach: `transaction { SchemaUtils.createMissingTablesAndColumns(...) }`
3. Business Logic: `DatabaseFactory.dbQuery { ... }` für Transaktionen
2. Immediately after: `transaction { SchemaUtils.createMissingTablesAndColumns(...) }`
3. Business Logic: `DatabaseFactory.dbQuery { ... }` for transactions
**⚠️ PROBLEM - Gateway Initialisierung:**
1. Ktor Application.configureDatabase() → direkter `Database.connect()`
2. Sofort danach: `transaction { ... }` für alle Service-Schemas
**⚠️ PROBLEM - Gateway Initialization:**
1. Ktor Application.configureDatabase() → direct `Database.connect()`
2. Immediately after: `transaction { ... }` for all service schemas
## 🚨 Identifizierte Probleme
## 🚨 Identified Problems
### 1. **Inkonsistente Database.connect() Implementierung**
- **Services**: Verwenden zentralen DatabaseFactory mit Connection Pooling
- **Gateway**: Direkter Database.connect() ohne Connection Pooling
- **Risiko**: Unterschiedliche Verbindungsqualität und -management
### 1. **Inconsistent Database.connect() Implementation**
- **Services**: Use central DatabaseFactory with Connection Pooling
- **Gateway**: Direct Database.connect() without Connection Pooling
- **Risk**: Different connection quality and management
### 2. **Potentielle Race Conditions**
- Gateway und Services initialisieren unabhängig voneinander
- Beide versuchen, Schemas für dieselben Tabellen zu erstellen
- **Risiko**: Konflikte bei paralleler Initialisierung
### 2. **Potential Race Conditions**
- Gateway and services initialize independently
- Both attempt to create schemas for the same tables
- **Risk**: Conflicts during parallel initialization
### 3. **Verletzung der Separation of Concerns**
- Gateway verwaltet Schemas für alle Services
- Services verwalten ihre eigenen Schemas
- **Risiko**: Doppelte Schema-Initialisierung
### 3. **Violation of Separation of Concerns**
- Gateway manages schemas for all services
- Services manage their own schemas
- **Risk**: Duplicate schema initialization
### 4. **Fehlende Initialisierungsreihenfolge-Garantien**
- Keine explizite Abhängigkeitsreihenfolge zwischen Gateway und Services
- **Risiko**: Exposed-Operationen vor Database.connect()
### 4. **Missing Initialization Order Guarantees**
- No explicit dependency order between Gateway and Services
- **Risk**: Exposed operations before Database.connect()
## ✅ Empfehlungen
## ✅ Recommendations
### 1. **Gateway auf DatabaseFactory umstellen**
### 1. **Switch Gateway to DatabaseFactory**
```kotlin
// Statt direktem Database.connect():
// Instead of direct Database.connect():
fun Application.configureDatabase() {
val config = DatabaseConfig.fromEnv() // oder aus Ktor Config
val config = DatabaseConfig.fromEnv() // or from Ktor Config
DatabaseFactory.init(config)
// Schema-Initialisierung entfernen oder koordinieren
// Remove or coordinate schema initialization
}
```
### 2. **Schema-Initialisierung koordinieren**
**Option A**: Nur Services verwalten ihre Schemas (empfohlen)
### 2. **Coordinate Schema Initialization**
**Option A**: Only services manage their schemas (recommended)
```kotlin
// Gateway: Nur Verbindung, keine Schema-Initialisierung
// Gateway: Only connection, no schema initialization
fun Application.configureDatabase() {
DatabaseFactory.init(DatabaseConfig.fromEnv())
}
```
**Option B**: Zentralisierte Schema-Verwaltung
**Option B**: Centralized schema management
```kotlin
// Separater DatabaseSchemaInitializer mit @Order Annotation
// Separate DatabaseSchemaInitializer with @Order annotation
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
class DatabaseSchemaInitializer {
@@ -106,9 +106,9 @@ class DatabaseSchemaInitializer {
}
```
### 3. **Startup-Reihenfolge sicherstellen**
### 3. **Ensure Startup Order**
```kotlin
// Services mit @DependsOn
// Services with @DependsOn
@Configuration
@DependsOn("databaseInitializer")
class HorsesDatabaseConfiguration {
@@ -116,9 +116,9 @@ class HorsesDatabaseConfiguration {
}
```
### 4. **Einheitliche Konfiguration**
### 4. **Unified Configuration**
```kotlin
// Alle Komponenten verwenden DatabaseFactory
// All components use DatabaseFactory
class SomeService {
suspend fun doSomething() {
DatabaseFactory.dbQuery {
@@ -128,21 +128,25 @@ class SomeService {
}
```
## 📋 Zusammenfassung
## 📋 Summary
**✅ Korrekt implementiert:**
- Alle Services verwenden proper @PostConstruct → Database.connect() → Exposed operations Reihenfolge
- DatabaseFactory bietet robuste Connection Pool Konfiguration
- Business Logic verwendet korrekte Transaktionsmuster
**✅ Correctly implemented:**
- All services use proper @PostConstruct → Database.connect() → Exposed operations sequence
- DatabaseFactory provides robust Connection Pool configuration
- Business logic uses correct transaction patterns
**⚠️ Zu beheben:**
- Gateway Database.connect() Inkonsistenz
- Potentielle Race Conditions bei Schema-Initialisierung
- Fehlende Startup-Reihenfolge-Koordination
**⚠️ To be fixed:**
- Gateway Database.connect() inconsistency
- Potential race conditions in schema initialization
- Missing startup order coordination
**🎯 Priorität:**
1. **Hoch**: Gateway auf DatabaseFactory umstellen
2. **Mittel**: Schema-Initialisierung koordinieren
3. **Niedrig**: Startup-Reihenfolge explizit definieren
**🎯 Priority:**
1. **High**: Switch Gateway to DatabaseFactory
2. **Medium**: Coordinate schema initialization
3. **Low**: Explicitly define startup order
Die Reihenfolge der Initialisierung ist grundsätzlich korrekt, aber die Inkonsistenz zwischen Gateway und Services sollte behoben werden, um potentielle Probleme zu vermeiden.
The initialization sequence is fundamentally correct, but the inconsistency between Gateway and Services should be resolved to avoid potential problems.
---
*Last updated: July 25, 2025*
docs/development/getting-started-de.md
-607
View File
@@ -1,607 +0,0 @@
# Entwicklungsanleitung - Erste Schritte
## Überblick
Diese Anleitung hilft neuen Entwicklern beim Einstieg in das Meldestelle-Projekt. Sie deckt alle notwendigen Schritte ab, von der initialen Einrichtung bis zur ersten erfolgreichen Entwicklungsumgebung.
## Voraussetzungen
### System-Anforderungen
- **Betriebssystem**: Windows 10+, macOS 10.15+, oder Linux (Ubuntu 20.04+ empfohlen)
- **RAM**: Mindestens 8GB (16GB empfohlen)
- **Speicher**: Mindestens 10GB freier Speicherplatz
- **Netzwerk**: Stabile Internetverbindung für Downloads
### Erforderliche Software
#### 1. Java Development Kit (JDK)
```bash
# Java 21 installieren (empfohlen: Eclipse Temurin)
# Windows (mit Chocolatey)
choco install temurin21
# macOS (mit Homebrew)
brew install --cask temurin21
# Linux (Ubuntu/Debian)
sudo apt update
sudo apt install openjdk-21-jdk
# Verifizierung
java -version
javac -version
```
#### 2. Docker und Docker Compose
```bash
# Docker Desktop installieren (Windows/macOS)
# Herunterladen von: https://www.docker.com/products/docker-desktop
# Linux (Ubuntu)
sudo apt update
sudo apt install docker.io docker-compose
sudo usermod -aG docker $USER
# Verifizierung
docker --version
docker-compose --version
```
#### 3. Git
```bash
# Windows (mit Chocolatey)
choco install git
# macOS (mit Homebrew)
brew install git
# Linux (Ubuntu)
sudo apt install git
# Verifizierung
git --version
```
#### 4. IDE (Empfohlen: IntelliJ IDEA)
```bash
# IntelliJ IDEA Community Edition
# Herunterladen von: https://www.jetbrains.com/idea/download/
# Oder mit Package Manager
# Windows (Chocolatey)
choco install intellijidea-community
# macOS (Homebrew)
brew install --cask intellij-idea-ce
# Linux (Snap)
sudo snap install intellij-idea-community --classic
```
## Projekt-Setup
### 1. Repository klonen
```bash
# Repository klonen
git clone <repository-url>
cd Meldestelle
# Branch-Status prüfen
git status
git branch -a
```
### 2. Umgebungsvariablen konfigurieren
```bash
# .env-Datei erstellen (falls nicht vorhanden)
cp .env.example .env
# .env-Datei bearbeiten
nano .env # oder mit bevorzugtem Editor
```
#### Wichtige Umgebungsvariablen
```bash
# Anwendungskonfiguration
APP_ENVIRONMENT=development
APP_NAME=meldestelle
APP_VERSION=1.0.0
# Datenbank-Konfiguration
DATABASE_URL=jdbc:postgresql://localhost:5432/meldestelle
DATABASE_USERNAME=meldestelle
DATABASE_PASSWORD=password
# Redis-Konfiguration
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
# Keycloak-Konfiguration
KEYCLOAK_URL=http://localhost:8080
KEYCLOAK_REALM=meldestelle
KEYCLOAK_CLIENT_ID=meldestelle-client
# Kafka-Konfiguration
KAFKA_BOOTSTRAP_SERVERS=localhost:9092
KAFKA_GROUP_ID=meldestelle-group
```
### 3. Docker-Infrastruktur starten
```bash
# Alle Services starten
docker-compose up -d
# Status überprüfen
docker-compose ps
# Logs anzeigen (optional)
docker-compose logs -f
# Einzelne Services starten (falls gewünscht)
docker-compose up -d postgres redis keycloak
```
#### Service-Übersicht
| Service | Port | Beschreibung | URL |
|---------|------|--------------|-----|
| PostgreSQL | 5432 | Hauptdatenbank | localhost:5432 |
| Redis | 6379 | Cache & Event Store | localhost:6379 |
| Keycloak | 8080 | Authentifizierung | http://localhost:8080 |
| Kafka | 9092 | Messaging | localhost:9092 |
| Zookeeper | 2181 | Kafka Koordination | localhost:2181 |
| Zipkin | 9411 | Distributed Tracing | http://localhost:9411 |
| Prometheus | 9090 | Metriken | http://localhost:9090 |
| Grafana | 3000 | Dashboards | http://localhost:3000 |
### 4. Umgebung validieren
```bash
# Validierungsskript ausführen
./validate-env.sh
# Oder manuell prüfen
docker-compose ps
curl http://localhost:8080/auth/realms/meldestelle
```
## IDE-Konfiguration
### IntelliJ IDEA Setup
#### 1. Projekt öffnen
1. IntelliJ IDEA starten
2. "Open" wählen
3. Meldestelle-Projektverzeichnis auswählen
4. "Open as Project" bestätigen
#### 2. Kotlin-Plugin aktivieren
1. File → Settings (Ctrl+Alt+S)
2. Plugins → Marketplace
3. "Kotlin" suchen und installieren
4. IDE neu starten
#### 3. Gradle-Konfiguration
1. File → Settings → Build → Gradle
2. "Use Gradle from" → "gradle-wrapper.properties file"
3. "Gradle JVM" → Java 21 auswählen
4. "Apply" und "OK"
#### 4. Code-Style konfigurieren
1. File → Settings → Editor → Code Style
2. Scheme → "Project" auswählen
3. Kotlin → Tabs and Indents:
- Tab size: 4
- Indent: 4
- Continuation indent: 8
#### 5. Nützliche Plugins installieren
- **Docker**: Docker-Integration
- **Database Tools**: Datenbankzugriff
- **GitToolBox**: Erweiterte Git-Features
- **Rainbow Brackets**: Bessere Klammer-Visualisierung
- **String Manipulation**: Text-Utilities
### VS Code Setup (Alternative)
#### 1. Erforderliche Extensions
```bash
# Extension Pack for Java
code --install-extension vscjava.vscode-java-pack
# Kotlin Language
code --install-extension fwcd.kotlin
# Docker
code --install-extension ms-azuretools.vscode-docker
# GitLens
code --install-extension eamodio.gitlens
```
#### 2. Workspace-Konfiguration
```json
{
"java.home": "/path/to/java-21",
"java.configuration.updateBuildConfiguration": "automatic",
"kotlin.languageServer.enabled": true,
"docker.showStartPage": false
}
```
Erstellen Sie diese Datei als `.vscode/settings.json` im Projektverzeichnis.
## Projekt-Architektur verstehen
### Modulare Struktur
```
Meldestelle/
├── core/ # Shared Kernel
│ ├── core-domain/ # Gemeinsame Domain-Modelle
│ └── core-utils/ # Utilities und Konfiguration
├── members/ # Mitgliederverwaltung
│ ├── members-domain/ # Domain Layer
│ ├── members-application/ # Application Layer
│ ├── members-infrastructure/ # Infrastructure Layer
│ ├── members-api/ # API Layer
│ └── members-service/ # Service Layer
├── horses/ # Pferderegistrierung
├── events/ # Veranstaltungsverwaltung
├── masterdata/ # Stammdatenverwaltung
├── infrastructure/ # Infrastruktur-Services
├── client/ # Client-Anwendungen
└── docs/ # Dokumentation
```
### Clean Architecture Prinzipien
1. **Domain Layer**: Geschäftslogik und Entitäten
2. **Application Layer**: Use Cases und Orchestrierung
3. **Infrastructure Layer**: Datenbankzugriff und externe Services
4. **API Layer**: REST-Controller und DTOs
5. **Service Layer**: Spring Boot Anwendungen
### Technologie-Stack
- **Backend**: Kotlin + Spring Boot
- **Datenbank**: PostgreSQL + Exposed ORM
- **Caching**: Redis
- **Messaging**: Apache Kafka
- **Authentifizierung**: Keycloak + JWT
- **Monitoring**: Prometheus + Grafana
- **Tracing**: Zipkin
- **Frontend**: Jetpack Compose (Desktop/Web)
- **Build**: Gradle mit Kotlin DSL
## Erste Entwicklungsschritte
### 1. Projekt kompilieren
```bash
# Vollständigen Build ausführen
./gradlew build
# Nur kompilieren (ohne Tests)
./gradlew compileKotlin
# Spezifisches Modul kompilieren
./gradlew :members:members-service:build
```
### 2. Tests ausführen
```bash
# Alle Tests
./gradlew test
# Modul-spezifische Tests
./gradlew :members:test
# Integration Tests
./gradlew integrationTest
# Test-Reports anzeigen
open build/reports/tests/test/index.html
```
### 3. Services starten
```bash
# Einzelnen Service starten
./gradlew :members:members-service:bootRun
# Mit spezifischem Profil
./gradlew :members:members-service:bootRun --args='--spring.profiles.active=dev'
# API Gateway starten
./gradlew :infrastructure:gateway:bootRun
```
### 4. Datenbank-Migrationen
```bash
# Flyway-Migrationen ausführen
./gradlew flywayMigrate
# Migration-Status prüfen
./gradlew flywayInfo
# Datenbank zurücksetzen (Vorsicht!)
./gradlew flywayClean
```
## Entwicklungsworkflows
### Feature-Entwicklung
#### 1. Feature Branch erstellen
```bash
# Neuen Feature Branch erstellen
git checkout -b feature/neue-funktion
# Branch auf Remote pushen
git push -u origin feature/neue-funktion
```
#### 2. Code-Änderungen
```bash
# Änderungen committen
git add .
git commit -m "feat: neue Funktion implementiert"
# Code-Style prüfen
./gradlew ktlintCheck
# Code formatieren
./gradlew ktlintFormat
```
#### 3. Tests und Qualitätssicherung
```bash
# Tests ausführen
./gradlew test
# Code-Coverage prüfen
./gradlew jacocoTestReport
open build/reports/jacoco/test/html/index.html
# Statische Code-Analyse
./gradlew detekt
```
#### 4. Pull Request erstellen
1. Änderungen auf Remote Branch pushen
2. Pull Request im Repository erstellen
3. Code Review abwarten
4. Nach Approval mergen
### Debugging
#### 1. Service-Debugging
```bash
# Service mit Debug-Port starten
./gradlew :members:members-service:bootRun --debug-jvm
# Oder mit spezifischem Port
./gradlew :members:members-service:bootRun -Dspring-boot.run.jvmArguments="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005"
```
#### 2. IntelliJ Remote Debugging
1. Run → Edit Configurations
2. "+" → Remote JVM Debug
3. Port: 5005 (oder gewählter Port)
4. Debug-Session starten
#### 3. Logs analysieren
```bash
# Service-Logs anzeigen
docker-compose logs -f members-service
# Alle Logs
docker-compose logs -f
# Spezifische Log-Level
export LOGGING_LEVEL_ROOT=DEBUG
./gradlew :members:members-service:bootRun
```
### API-Testing
#### 1. Swagger UI verwenden
```bash
# Service starten
./gradlew :members:members-service:bootRun
# Swagger UI öffnen
open http://localhost:8082/swagger-ui.html
```
#### 2. cURL-Beispiele
```bash
# Alle Mitglieder abrufen
curl -H "Authorization: Bearer <token>" \
http://localhost:8082/api/members
# Neues Mitglied erstellen
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{"firstName":"Max","lastName":"Mustermann","email":"max@example.com","membershipNumber":"M2024001","membershipStartDate":"2024-01-01"}' \
http://localhost:8082/api/members
```
#### 3. Postman Collections
```bash
# Postman Collections importieren
# Dateien in docs/postman/ verwenden
```
## Häufige Probleme und Lösungen
### Docker-Probleme
#### Services starten nicht
```bash
# Ports prüfen
netstat -tulpn | grep :5432
# Docker-Logs prüfen
docker-compose logs postgres
# Services neu starten
docker-compose down
docker-compose up -d
```
#### Speicherplatz-Probleme
```bash
# Nicht verwendete Images entfernen
docker system prune -a
# Volumes aufräumen
docker volume prune
```
### Build-Probleme
#### Gradle-Cache-Probleme
```bash
# Gradle-Cache löschen
./gradlew clean
rm -rf ~/.gradle/caches
# Dependencies neu laden
./gradlew build --refresh-dependencies
```
#### Kotlin-Compiler-Probleme
```bash
# Kotlin-Daemon stoppen
./gradlew --stop
# Build-Verzeichnis löschen
./gradlew clean
# Neu kompilieren
./gradlew build
```
### Datenbank-Probleme
#### Verbindungsfehler
```bash
# PostgreSQL-Status prüfen
docker-compose ps postgres
# Datenbank-Logs prüfen
docker-compose logs postgres
# Verbindung testen
psql -h localhost -p 5432 -U meldestelle -d meldestelle
```
#### Migration-Fehler
```bash
# Migration-Status prüfen
./gradlew flywayInfo
# Fehlgeschlagene Migration reparieren
./gradlew flywayRepair
# Datenbank zurücksetzen (Entwicklung)
docker-compose down -v
docker-compose up -d postgres
./gradlew flywayMigrate
```
## Nützliche Befehle
### Gradle-Tasks
```bash
# Alle verfügbaren Tasks anzeigen
./gradlew tasks
# Abhängigkeiten anzeigen
./gradlew dependencies
# Projekt-Informationen
./gradlew projects
# Build-Scan erstellen
./gradlew build --scan
```
### Docker-Befehle
```bash
# Container-Status
docker-compose ps
# Logs verfolgen
docker-compose logs -f [service-name]
# Container neu starten
docker-compose restart [service-name]
# In Container einloggen
docker-compose exec postgres psql -U meldestelle
```
### Git-Workflows
```bash
# Aktuellen Status prüfen
git status
# Änderungen stagen
git add .
# Commit mit konventioneller Nachricht
git commit -m "feat(members): neue Validierung hinzugefügt"
# Branch wechseln
git checkout main
git pull origin main
```
## Weiterführende Ressourcen
### Dokumentation
- [API-Dokumentation](../api/README.md)
- [Architektur-Dokumentation](../architecture/)
- [Deployment-Anleitung](../README-PRODUCTION.md)
### Externe Ressourcen
- [Kotlin-Dokumentation](https://kotlinlang.org/docs/)
- [Spring Boot-Dokumentation](https://spring.io/projects/spring-boot)
- [Docker-Dokumentation](https://docs.docker.com/)
- [PostgreSQL-Dokumentation](https://www.postgresql.org/docs/)
### Community und Support
- **Issue Tracker**: GitHub Issues
- **Diskussionen**: GitHub Discussions
- **Code Reviews**: Pull Requests
- **Dokumentation**: Wiki
## Nächste Schritte
Nach erfolgreichem Setup:
1. **Code-Basis erkunden**: Beginnen Sie mit dem `members`-Modul
2. **Tests ausführen**: Verstehen Sie die Test-Struktur
3. **Erste Änderung**: Implementieren Sie eine kleine Verbesserung
4. **Code Review**: Erstellen Sie einen Pull Request
5. **Dokumentation**: Erweitern Sie die Dokumentation
---
**Letzte Aktualisierung**: 25. Juli 2025
**Version**: 1.0
**Zielgruppe**: Neue Entwickler
Bei Fragen oder Problemen erstellen Sie bitte ein Issue im Repository oder wenden Sie sich an das Entwicklungsteam.
docs/how-to/deploy-proxmox-nginx.md
+53
View File
@@ -0,0 +1,53 @@
---
owner: ops-team
status: active
review_cycle: 180d
last_reviewed: 2025-10-15
summary: Anleitung zur Installation und Konfiguration des Nginx Reverse Proxys auf dem Proxmox-Host für die Meldestelle-Services.
---
# How-To: Proxmox/Nginx Reverse Proxy deployen
Diese Anleitung beschreibt die Einrichtung des Nginx Reverse Proxys auf dem Proxmox-Host. Die Beispielkonfiguration liegt im Repository und wird unverändert übernommen.
- Beispielkonfiguration: proxmox-nginx/meldestelle.conf
## Voraussetzungen
- Proxmox-Host mit root-/sudo-Zugang
- Installiertes Nginx (`apt install nginx`)
- Lokale Container-Services laufen auf dem Host und sind über `localhost` erreichbar (Web 4000, Gateway 8081, VNC 6080)
## Schritte
1) Konfigurationsdatei auf den Host kopieren
```bash
sudo cp docs/proxmox-nginx/meldestelle.conf /etc/nginx/sites-available/
```
2) Site aktivieren (Symlink anlegen)
```bash
sudo ln -s /etc/nginx/sites-available/meldestelle.conf /etc/nginx/sites-enabled/
```
3) Nginx Konfiguration testen und neu laden
```bash
sudo nginx -t && sudo systemctl reload nginx
```
4) DNS konfigurieren (Beispiele)
- meldestelle.yourdomain.com → öffentliche IP deines Proxmox-Hosts
- api.meldestelle.yourdomain.com → öffentliche IP deines Proxmox-Hosts
- vnc.meldestelle.yourdomain.com → öffentliche IP deines Proxmox-Hosts
5) Health-Checks
```bash
curl -i http://api.meldestelle.yourdomain.com/actuator/health
curl -i http://meldestelle.yourdomain.com/health
```
## HTTPS (optional)
In der Beispielkonfiguration sind HTTPS-Serverblöcke und HTTP→HTTPS Redirects als Kommentar enthalten. Aktiviere diese Blöcke, wenn du Zertifikate (Let's Encrypt/Cloudflare) eingerichtet hast. Datei: proxmox-nginx/meldestelle.conf
## Fehlerbehebung
- 502 Bad Gateway: Zielcontainer läuft nicht oder Port falsch → Dienste starten (`make full-up`) und Ports prüfen.
- CORS-Fehler: API ausschließlich über die `api.*`-Domain aufrufen; Web-App über `meldestelle.*`.
- Änderungen ohne Effekt: `nginx -t` ausführen und `systemctl reload nginx`.
docs/how-to/start-local.md
+67
View File
@@ -0,0 +1,67 @@
---
owner: project-maintainers
status: active
review_cycle: 90d
last_reviewed: 2025-10-15
summary: Kürzeste Anleitung, um das komplette System lokal zu starten und zu prüfen, ob alles läuft.
---
# How-To: Lokale Umgebung starten (Quickstart)
Diese Kurz-Anleitung bringt deine lokale Umgebung in wenigen Minuten zum Laufen.
## Starten
- Komplettes System (Infra + Services + Clients)
```bash
make full-up
```
- Nur Backend (Infra + Gateway + Microservices)
```bash
make services-up
```
- Nur Clients (Infra + Web-App)
```bash
make clients-up
```
Logs ansehen (z. B. Backend):
```bash
make services-logs
```
## Wichtige URLs
- Web App: http://localhost:4000
- API Gateway: http://localhost:8081 (Health: /actuator/health)
- Keycloak (Auth): http://localhost:8180
- Consul (Service Discovery): http://localhost:8500
Weitere Ports findest du unter: reference/ports-and-urls.md
## Health-Checks
```bash
# Gateway
curl -i http://localhost:8081/actuator/health
# Web-App (falls vorhanden)
curl -i http://localhost:4000/health || true
```
## Auth (Keycloak)
- Admin-Login (default): http://localhost:8180
- Username: KC_BOOTSTRAP_ADMIN_USERNAME (default: admin)
- Password: KC_BOOTSTRAP_ADMIN_PASSWORD (default: admin)
- Beim ersten Start wird der Realm aus docker/services/keycloak/meldestelle-realm.json importiert.
## Häufige Probleme
- Dienste nicht erreichbar → Containers laufen? `make full-logs` bzw. `make services-logs` prüfen.
- 401/403 beim API-Aufruf → Prüfen, ob ein gültiges Bearer-Token gesendet wird und Keycloak erreichbar ist.
- CORS im Browser → API über das Gateway (http://localhost:8081) aufrufen und nicht direkt die Services (8082–8086).
- Port-Kollisionen → Belegte Ports mit `lsof -i :PORT` prüfen oder Ports anpassen.
## Stoppen
```bash
make full-down
# oder spezifisch: make services-down / make clients-down / make infrastructure-down
```
docs/index.html
-6388
View File
File diff suppressed because one or more lines are too long
docs/index.md
+26
View File
@@ -0,0 +1,26 @@
---
owner: project-maintainers
status: active
review_cycle: 90d
last_reviewed: 2025-10-15
summary: Schlanker Einstiegspunkt in die Dokumentation der Meldestelle. Nur die wichtigsten Links für Start, Überblick, API, Produktion und aktuelles Vorhaben.
---
# Meldestelle – Dokumentation (Startseite)
Willkommen! Das ist der zentrale Einstieg in die Projektdokumentation. Starte hier.
## Start
- Schnellstart lokal: how-to/start-local.md
- Gesamtüberblick: overview/system-overview.md
## API
- API-Übersicht: api/README.md
## Betrieb
- Produktion (Proxmox/Nginx): how-to/deploy-proxmox-nginx.md
## Aktuelles Vorhaben
- Now-Page: now/current.md
Hinweis: Diese Seite ist der einzige offizielle Einstiegspunkt. Ältere Indizes (z. B. INDEX.md oder bilingualer Index) sind historisch bzw. entfernt.
docs/now/README.md
+31
View File
@@ -0,0 +1,31 @@
---
owner: project-maintainers
status: active
last_reviewed: 2025-10-15
review_cycle: 90d
summary: Anleitung zur Nutzung der Now-Page (Initiativen-One‑Pager) als zentraler Steuerungs- und Übersichtspunkt.
---
# Now-Page – Nutzung & Workflow
Die Now-Page ist ein schlanker One‑Pager für dein aktuelles Vorhaben. Sie beantwortet stets fünf Fragen: Was, Warum, Wie, Was ist zu tun, und Was ist als Nächstes dran.
## Struktur
- Aktive Seite: `docs/now/current.md`
- Vorlage: `docs/now/TEMPLATE.md`
- Archiv (optional): `docs/now/archive/` (einfach Dateien hinein verschieben)
## So verwendest du die Now-Page
1. Neue Initiative starten: Kopiere `TEMPLATE.md` nach `current.md` und fülle sie aus.
2. Kurz halten: 1 Seite, maximal 5–10 Tasks. Große Aufgaben in kleinere Schneiden.
3. Pflege-Ritual: Bei Änderung von Fokus/Status/Plan kurz aktualisieren, `last_reviewed` anpassen.
4. Abschluss: `status: done` setzen, 3 Bulletpoints „Lessons Learned“ ergänzen und Datei nach `now/archive/` verschieben.
5. Dauerhafte Entscheidungen: Als ADR in `docs/architecture/adr/` festhalten und aus der Now‑Page verlinken.
## Tipps
- Verlinke nur, was du beim Arbeiten wirklich brauchst (PRs, Issues, wichtige How‑Tos).
- Nutze die Now‑Page als Daily/Nächstes‑To‑Do‑Quelle statt vieler verstreuter Notizen.
- Optional in CI: Einen „Stale‑Check“ einführen, der warnt, wenn `current.md` länger als `review_cycle` nicht aktualisiert wurde.
## Navigation
- Die Startseite (docs/index.md) verlinkt direkt auf `now/current.md`, damit du jederzeit mit einem Klick am aktuellen Fokus bist.
docs/now/TEMPLATE.md
+39
View File
@@ -0,0 +1,39 @@
---
owner: <dein-name-oder-team>
status: active # active | blocked | done
timeframe: YYYY-MM-DD → YYYY-MM-DD
last_reviewed: YYYY-MM-DD
review_cycle: 7d # erinnert dich wöchentlich ans Aktualisieren
summary: One-Pager-Template für das aktuell wichtigste Vorhaben (Now-Page).
---
# Aktuelle Initiative: <Titel>
## 1) Vision (Was?)
Ein Satz Zielbild. Was soll am Ende anders/besser sein? Optional: In/Out of Scope.
- In Scope: …
- Out of Scope: …
## 2) Why (Warum so?)
Problem, Zielmetriken/Erfolgskriterien, Alternativen/Trade-offs.
- Erfolg messbar an: <Metriken/Kriterien>
- Falls dauerhaft relevant: verweise auf ADR (`docs/adr/...`).
## 3) How (Wie umsetzen?)
Kurzarchitektur, Ansatz, Risiken/Abhängigkeiten. 5–10 Zeilen genügen.
- Ansatz: …
- Risiken: …
- Abhängigkeiten: …
## 4) Plan (Was ist jetzt zu tun?)
Milestones + nächste konkrete Schritte. Max. 5–10 Tasks, sonst zu groß schneiden.
- [ ] Schritt 1 (heute)
- [ ] Schritt 2 (diese Woche)
- [ ] Schritt 3 (nächste Woche)
## 5) Status & Nächster Fokus
- Status: active | blocked | done
- Nächster Fokus (heute): <1–2 Sätze>
## 6) Referenzen
Links zu PRs, Issues, Diagrammen, Konfigs (nur die, die man wirklich braucht).
docs/now/current.md
+43
View File
@@ -0,0 +1,43 @@
---
owner: stefan
status: active
timeframe: 2025-10-15 → 2025-10-29
last_reviewed: 2025-10-15
review_cycle: 7d
summary: Minimal‑Doku + Now‑Page etablieren, um Übersicht zurückzugewinnen.
---
# Aktuelle Initiative: Doku verschlanken & Now‑Page einführen
## 1) Vision (Was?)
Eine verlässliche, minimale Doku (≤5 Seiten) + ein stets aktueller One‑Pager für das laufende Vorhaben.
- In Scope: Start/Overview/API/Prod-HowTo/Now-Page
- Out of Scope: Vollständige Übersetzungen, alte Berichte/Prosa
## 2) Why (Warum so?)
Zu viele, verstreute Dokumente erzeugen Drift und Entscheidungsunsicherheit. Ziel: Orientierung in <2 Min. wiederfinden.
- Erfolg messbar an: 1 Einstiegspunkt, 0 Broken Links, Validierung grün
- Dauerhaft relevante Entscheidungen künftig als ADR, aus Now‑Page verlinkt
## 3) How (Wie umsetzen?)
- Behalten: `docs/index.md`, `overview/system-overview.md`, `how-to/*`, `api/README.md`, `now/current.md`
- Entfernen/Archivieren: `Tagebuch/`, alte Indizes
- CI beibehalten (Link‑Check optional), später Stale‑Check für Now‑Page ergänzen
## 4) Plan (Was ist jetzt zu tun?)
- [ ] Index minimalisieren und nur auf Kernseiten verlinken
- [ ] System Overview anlegen und Ports/Health bündeln
- [ ] Now‑Page Template + current.md erstellen
- [ ] Alte Indizes und Tagebuch entfernen
- [ ] Validierung laufen lassen und etwaige Links reparieren
- [ ] Nächste Initiative vorbereiten: Git‑Flow & GitHub Actions Strategy
## 5) Status & Nächster Fokus
- Status: active
- Nächster Fokus: Validierung ausführen und offene Link‑Themen bereinigen; danach Git‑Flow/GitHub‑Actions planen
## 6) Referenzen
- Start lokal: `docs/how-to/start-local.md`
- Übersicht: `docs/overview/system-overview.md`
- Produktion/Nginx: `docs/how-to/deploy-proxmox-nginx.md`
- API: `docs/api/README.md`
docs/overview/system-overview.md
+79
View File
@@ -0,0 +1,79 @@
---
owner: project-owner
status: active
last_reviewed: 2025-10-15
review_cycle: 90d
summary: Gesamtüberblick – Was ist vorhanden, wie funktioniert es, wie starte/deploye ich es.
---
# Meldestelle – System Overview (Kurz & vollständig)
## Was ist vorhanden (Bausteine)
- Clients
- Web App (Port 4000)
- optional Desktop/noVNC (Port 6080)
- Gateway & Services
- API Gateway (Spring Cloud Gateway, Port 8081)
- Microservices: Members (8083), Horses (8084), Events (8085), Masterdata (8086), Ping (8082)
- Infrastruktur
- Postgres (5432), Redis (6379), Keycloak (8180), Consul (8500)
- Reverse Proxy (Produktion)
- Nginx auf Proxmox-Host
- vHosts: `meldestelle.yourdomain.com` (Web), `api.meldestelle.yourdomain.com` (API), `vnc.meldestelle.yourdomain.com` (VNC)
## Wie funktioniert es (Ablauf & Verantwortungen)
- Einstieg nur über das API-Gateway (Security, CORS, Rate-Limits, Observability, Routing)
- Authentifizierung via Keycloak (OIDC/JWT)
- Web holt Token bei Keycloak → sendet Requests mit `Authorization: Bearer <JWT>`
- Gateway validiert JWT (JWKs), injiziert Kontext, routet an Services
- Service Discovery über Consul (Gateway ↔ Services)
- Persistenz: Services schreiben/lesen in Postgres; Redis optional für Cache
- Produktion: Öffentliche Zugriffe laufen über Nginx-vHosts → Gateway/Web/noVNC in Docker
## Starten & Stoppen (lokal)
- Komplettes System: `make full-up`
- Nur Infrastruktur: `make infrastructure-up`
- Nur Backend (inkl. Gateway): `make services-up`
- Nur Clients (inkl. Web): `make clients-up`
- Stoppen: `make full-down` (bzw. `*-down`)
- Logs: `make full-logs` (bzw. `services-logs`, `infrastructure-logs`)
## Health, URLs & Ports
- Web: `http://localhost:4000` → Health: `/health`
- Gateway: `http://localhost:8081` → Health: `/actuator/health`
- Services (dev): Ping 8082, Members 8083, Horses 8084, Events 8085, Masterdata 8086
- Keycloak: `http://localhost:8180`
- Consul UI: `http://localhost:8500`
- Postgres: `localhost:5432`
- Redis: `localhost:6379`
- noVNC: `http://localhost:6080`
## Auth-Flow (kurz)
1. Web ruft geschützte Seite → Redirect zu Keycloak `/authorize`
2. Login → Code → Token-Tausch (ID/Access Token)
3. Web ruft Gateway mit `Bearer <JWT>` auf → Gateway prüft Token → leitet an Service
## Produktion (Proxmox/Nginx)
- Datei: `docs/proxmox-nginx/meldestelle.conf`
- vHosts:
- `meldestelle.yourdomain.com` → Web (`localhost:4000`)
- `api.meldestelle.yourdomain.com` → Gateway (`localhost:8081`)
- `vnc.meldestelle.yourdomain.com` → noVNC (`localhost:6080`)
- Health-Checks:
- `curl -i http://api.meldestelle.yourdomain.com/actuator/health`
- `curl -i http://meldestelle.yourdomain.com/health`
## Konfiguration auf einen Blick (Defaults)
- Postgres: `POSTGRES_USER=meldestelle`, `POSTGRES_PASSWORD=meldestelle`, `POSTGRES_DB=meldestelle`
- Keycloak Admin: `KC_BOOTSTRAP_ADMIN_USERNAME=admin`, `KC_BOOTSTRAP_ADMIN_PASSWORD=admin`
- Gateway: Port 8081, Profil `dev` (per `SPRING_PROFILES_ACTIVE`)
## Troubleshooting (Top 5)
- 401/403 am Gateway: Token fehlt/abgelaufen? Keycloak auf `http://localhost:8180` erreichbar?
- 502/Bad Gateway: Zielservice down? Logs prüfen (`make services-logs`).
- CORS im Browser: API über `api.meldestelle.*` bzw. `localhost:8081` aufrufen.
- Consul leer: Services nicht registriert → Services neu starten.
- Port-Konflikt: Belegte Ports mit `lsof -i :<port>` prüfen, Prozesse beenden.
## Diagramme (PlantUML)
Siehe `docs/architecture/c4/` – Context & Container sowie Login‑Sequenz. In CI zu SVG rendern.
docs/reference/ports-and-urls.md
+35
View File
@@ -0,0 +1,35 @@
---
owner: project-maintainers
status: active
review_cycle: 180d
last_reviewed: 2025-10-15
summary: Konsolidierte Übersicht aller relevanten lokalen Ports/URLs sowie der produktiven Domains (hinter Nginx).
---
# Referenz: Ports & URLs
## Lokal (Standard-Setup)
- Web App: http://localhost:4000
- API Gateway: http://localhost:8081
- Health: http://localhost:8081/actuator/health
- Services (nur lokal):
- Ping Service: http://localhost:8082
- Members Service: http://localhost:8083
- Horses Service: http://localhost:8084
- Events Service: http://localhost:8085
- Masterdata Service: http://localhost:8086
- Keycloak (Auth): http://localhost:8180
- Consul (Service Discovery): http://localhost:8500
- Postgres: localhost:5432
- Redis: localhost:6379
- noVNC (Desktop): http://localhost:6080
Hinweis: In Produktion sind die einzelnen Services (8082–8086) nicht öffentlich erreichbar. Alle API-Aufrufe laufen über das Gateway.
## Produktion (hinter Nginx)
- Web App: http://meldestelle.yourdomain.com
- API Gateway: http://api.meldestelle.yourdomain.com
- Health: http://api.meldestelle.yourdomain.com/actuator/health
- VNC (optional): http://vnc.meldestelle.yourdomain.com
Optional HTTPS: gleiche Hosts mit https://, sobald Zertifikate aktiv sind.
infrastructure/gateway/src/main/kotlin/at/mocode/infrastructure/gateway/config/GatewayConfig.kt
+1 -1
View File
@@ -20,7 +20,7 @@ import kotlin.uuid.Uuid
*/
/**
* Global Filter für Korrelations-IDs zur Request-Verfolgung.
* Global Filter für Correlations-IDs zur Request-Verfolgung.
*/
@Component
class CorrelationIdFilter : GlobalFilter, Ordered {
infrastructure/gateway/src/main/kotlin/at/mocode/infrastructure/gateway/metrics/GatewayMetricsConfig.kt
+1 -1
View File
@@ -75,7 +75,7 @@ class GatewayMetricsConfig {
* Bean für Request Duration Timer - entfernt um Konflikte mit dem WebFilter zu vermeiden.
* Die Request-Zeiten werden automatisch im GatewayMetricsWebFilter erfasst.
*/
// @Bean - Entfernt um Prometheus Meter-Konflikte zu vermeiden
// @Bean - entfernt, um Prometheus Meter-Konflikte zu vermeiden,
// fun requestTimer(meterRegistry: MeterRegistry): Timer { ... }
/**
infrastructure/gateway/src/main/kotlin/at/mocode/infrastructure/gateway/security/SecurityConfig.kt
+2 -2
View File
@@ -66,7 +66,7 @@ class SecurityConfig(
*/
@Bean
fun reactiveJwtDecoder(
@Value("\${spring.security.oauth2.resourceserver.jwt.jwk-set-uri:}") jwkSetUri: String
@Value($$"${spring.security.oauth2.resourceserver.jwt.jwk-set-uri:}") jwkSetUri: String
): ReactiveJwtDecoder {
return if (jwkSetUri.isNotBlank()) {
try {
@@ -114,7 +114,7 @@ class SecurityConfig(
}
/**
* Konfigurations-Properties für alle sicherheitsrelevanten Einstellungen des Gateways.
* Configurations-Properties für alle sicherheitsrelevanten Einstellungen des Gateways.
*/
@ConfigurationProperties(prefix = "gateway.security")
data class GatewaySecurityProperties(
logs/gateway.log
+190 -82
View File
@@ -1,84 +1,192 @@
2025-10-13 13:04:36.468 [background-preinit] INFO [] o.h.validator.internal.util.Version - HV000001: Hibernate Validator 8.0.3.Final
2025-10-13 13:04:36.510 [main] INFO [] a.m.i.gateway.GatewayApplicationKt - Starting GatewayApplicationKt using Java 21.0.8 with PID 170664 (/home/stefan/WsMeldestelle/Meldestelle/infrastructure/gateway/build/classes/kotlin/main started by stefan in /home/stefan/WsMeldestelle/Meldestelle)
2025-10-13 13:04:36.511 [main] DEBUG [] a.m.i.gateway.GatewayApplicationKt - Running with Spring Boot v3.5.5, Spring v6.2.10
2025-10-13 13:04:36.511 [main] INFO [] a.m.i.gateway.GatewayApplicationKt - The following 1 profile is active: "dev"
2025-10-13 13:04:37.697 [main] INFO [] o.s.d.r.c.RepositoryConfigurationDelegate - Multiple Spring Data modules found, entering strict repository configuration mode
2025-10-13 13:04:37.699 [main] INFO [] o.s.d.r.c.RepositoryConfigurationDelegate - Bootstrapping Spring Data Redis repositories in DEFAULT mode.
2025-10-13 13:04:37.732 [main] INFO [] o.s.d.r.c.RepositoryConfigurationDelegate - Finished Spring Data repository scanning in 19 ms. Found 0 Redis repository interfaces.
2025-10-13 13:04:37.986 [main] INFO [] o.s.cloud.context.scope.GenericScope - BeanFactory id=62ead487-39a4-3fc3-b0b8-d0378aec5250
2025-10-13 13:04:39.373 [main] WARN [] o.s.b.w.r.c.AnnotationConfigReactiveWebServerApplicationContext - Exception encountered during context initialization - cancelling refresh attempt: org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'org.springframework.security.config.annotation.web.reactive.WebFluxSecurityConfiguration': Unsatisfied dependency expressed through method 'setSecurityWebFilterChains' parameter 0: Error creating bean with name 'securityWebFilterChain' defined in class path resource [at/mocode/infrastructure/gateway/security/SecurityConfig.class]: Failed to instantiate [org.springframework.security.web.server.SecurityWebFilterChain]: Factory method 'securityWebFilterChain' threw exception with message: No qualifying bean of type 'org.springframework.security.oauth2.jwt.ReactiveJwtDecoder' available
2025-10-13 13:04:39.400 [main] INFO [] o.s.b.a.l.ConditionEvaluationReportLogger -
2025-10-15 10:31:21.532 [background-preinit] INFO [] o.h.validator.internal.util.Version - HV000001: Hibernate Validator 8.0.3.Final
2025-10-15 10:31:21.556 [main] INFO [] a.m.i.gateway.GatewayApplicationKt - Starting GatewayApplicationKt using Java 21.0.8 with PID 20139 (/home/stefan/WsMeldestelle/Meldestelle/infrastructure/gateway/build/classes/kotlin/main started by stefan in /home/stefan/WsMeldestelle/Meldestelle)
2025-10-15 10:31:21.556 [main] DEBUG [] a.m.i.gateway.GatewayApplicationKt - Running with Spring Boot v3.5.6, Spring v6.2.11
2025-10-15 10:31:21.556 [main] INFO [] a.m.i.gateway.GatewayApplicationKt - The following 1 profile is active: "dev"
2025-10-15 10:31:22.587 [main] INFO [] o.s.cloud.context.scope.GenericScope - BeanFactory id=4eb90187-1826-32ce-9dc7-fa80cb000915
2025-10-15 10:31:24.216 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [After]
2025-10-15 10:31:24.216 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [Before]
2025-10-15 10:31:24.217 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [Between]
2025-10-15 10:31:24.217 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [Cookie]
2025-10-15 10:31:24.217 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [Header]
2025-10-15 10:31:24.217 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [Host]
2025-10-15 10:31:24.217 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [Method]
2025-10-15 10:31:24.217 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [Path]
2025-10-15 10:31:24.217 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [Query]
2025-10-15 10:31:24.217 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [ReadBody]
2025-10-15 10:31:24.217 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [RemoteAddr]
2025-10-15 10:31:24.217 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [XForwardedRemoteAddr]
2025-10-15 10:31:24.217 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [Weight]
2025-10-15 10:31:24.217 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [CloudFoundryRouteService]
2025-10-15 10:31:24.751 [main] INFO [] o.s.b.a.e.web.EndpointLinksResolver - Exposing 6 endpoints beneath base path '/actuator'
2025-10-15 10:31:25.256 [main] WARN [] o.s.c.l.c.LoadBalancerCacheAutoConfiguration$LoadBalancerCaffeineWarnLogger - Spring Cloud LoadBalancer is currently working with the default cache. While this cache implementation is useful for development and tests, it's recommended to use Caffeine cache in production.You can switch to using Caffeine cache, by adding it and org.springframework.cache.caffeine.CaffeineCacheManager to the classpath.
2025-10-15 10:31:25.331 [catalogWatchTaskScheduler-1] ERROR [] o.s.c.c.discovery.ConsulCatalogWatch - Error watching Consul CatalogServices
com.ecwid.consul.transport.TransportException: org.apache.http.conn.HttpHostConnectException: Connect to localhost:8500 [localhost/127.0.0.1, localhost/0:0:0:0:0:0:0:1] failed: Verbindungsaufbau abgelehnt
at com.ecwid.consul.transport.AbstractHttpTransport.executeRequest(AbstractHttpTransport.java:83)
at com.ecwid.consul.transport.AbstractHttpTransport.makeGetRequest(AbstractHttpTransport.java:36)
at com.ecwid.consul.v1.ConsulRawClient.makeGetRequest(ConsulRawClient.java:139)
at com.ecwid.consul.v1.catalog.CatalogConsulClient.getCatalogServices(CatalogConsulClient.java:143)
at com.ecwid.consul.v1.ConsulClient.getCatalogServices(ConsulClient.java:400)
at org.springframework.cloud.consul.discovery.ConsulCatalogWatch.catalogServicesWatch(ConsulCatalogWatch.java:131)
at org.springframework.scheduling.support.DelegatingErrorHandlingRunnable.run(DelegatingErrorHandlingRunnable.java:54)
at java.base/java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:572)
at java.base/java.util.concurrent.FutureTask.runAndReset(FutureTask.java:358)
at java.base/java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.run(ScheduledThreadPoolExecutor.java:305)
at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1144)
at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:642)
at java.base/java.lang.Thread.run(Thread.java:1583)
Caused by: org.apache.http.conn.HttpHostConnectException: Connect to localhost:8500 [localhost/127.0.0.1, localhost/0:0:0:0:0:0:0:1] failed: Verbindungsaufbau abgelehnt
at org.apache.http.impl.conn.DefaultHttpClientConnectionOperator.connect(DefaultHttpClientConnectionOperator.java:156)
at org.apache.http.impl.conn.PoolingHttpClientConnectionManager.connect(PoolingHttpClientConnectionManager.java:376)
at org.apache.http.impl.execchain.MainClientExec.establishRoute(MainClientExec.java:393)
at org.apache.http.impl.execchain.MainClientExec.execute(MainClientExec.java:236)
at org.apache.http.impl.execchain.ProtocolExec.execute(ProtocolExec.java:186)
at org.apache.http.impl.execchain.RetryExec.execute(RetryExec.java:89)
at org.apache.http.impl.execchain.RedirectExec.execute(RedirectExec.java:110)
at org.apache.http.impl.client.InternalHttpClient.doExecute(InternalHttpClient.java:185)
at org.apache.http.impl.client.CloseableHttpClient.execute(CloseableHttpClient.java:72)
at org.apache.http.impl.client.CloseableHttpClient.execute(CloseableHttpClient.java:221)
at org.apache.http.impl.client.CloseableHttpClient.execute(CloseableHttpClient.java:165)
at org.apache.http.impl.client.CloseableHttpClient.execute(CloseableHttpClient.java:140)
at com.ecwid.consul.transport.AbstractHttpTransport.executeRequest(AbstractHttpTransport.java:70)
... 12 common frames omitted
Caused by: java.net.ConnectException: Verbindungsaufbau abgelehnt
at java.base/sun.nio.ch.Net.pollConnect(Native Method)
at java.base/sun.nio.ch.Net.pollConnectNow(Net.java:682)
at java.base/sun.nio.ch.NioSocketImpl.timedFinishConnect(NioSocketImpl.java:542)
at java.base/sun.nio.ch.NioSocketImpl.connect(NioSocketImpl.java:592)
at java.base/java.net.SocksSocketImpl.connect(SocksSocketImpl.java:327)
at java.base/java.net.Socket.connect(Socket.java:751)
at org.apache.http.conn.socket.PlainConnectionSocketFactory.connectSocket(PlainConnectionSocketFactory.java:75)
at org.apache.http.impl.conn.DefaultHttpClientConnectionOperator.connect(DefaultHttpClientConnectionOperator.java:142)
... 24 common frames omitted
2025-10-15 10:31:25.350 [main] INFO [] o.s.b.w.e.netty.NettyWebServer - Netty started on port 8080 (http)
2025-10-15 10:31:25.352 [main] INFO [] o.s.c.c.s.ConsulServiceRegistry - Registering service with consul: NewService{id='meldestelle-8080-b001fd13-0b36-40e4-afae-566661a43ceb', name='meldestelle', tags=[], address='fedora', meta={secure=false}, port=8080, enableTagOverride=null, check=Check{script='null', dockerContainerID='null', shell='null', interval='10s', ttl='null', http='http://fedora:8080/actuator/health', method='null', header={}, tcp='null', timeout='null', deregisterCriticalServiceAfter='null', tlsSkipVerify=null, status='null', grpc='null', grpcUseTLS=null}, checks=null}
2025-10-15 10:31:25.361 [main] ERROR [] o.s.c.c.s.ConsulServiceRegistry - Error registering service with consul: NewService{id='meldestelle-8080-b001fd13-0b36-40e4-afae-566661a43ceb', name='meldestelle', tags=[], address='fedora', meta={secure=false}, port=8080, enableTagOverride=null, check=Check{script='null', dockerContainerID='null', shell='null', interval='10s', ttl='null', http='http://fedora:8080/actuator/health', method='null', header={}, tcp='null', timeout='null', deregisterCriticalServiceAfter='null', tlsSkipVerify=null, status='null', grpc='null', grpcUseTLS=null}, checks=null}
com.ecwid.consul.transport.TransportException: org.apache.http.conn.HttpHostConnectException: Connect to localhost:8500 [localhost/127.0.0.1, localhost/0:0:0:0:0:0:0:1] failed: Verbindungsaufbau abgelehnt
at com.ecwid.consul.transport.AbstractHttpTransport.executeRequest(AbstractHttpTransport.java:83)
at com.ecwid.consul.transport.AbstractHttpTransport.makePutRequest(AbstractHttpTransport.java:49)
at com.ecwid.consul.v1.ConsulRawClient.makePutRequest(ConsulRawClient.java:163)
at com.ecwid.consul.v1.agent.AgentConsulClient.agentServiceRegister(AgentConsulClient.java:273)
at com.ecwid.consul.v1.ConsulClient.agentServiceRegister(ConsulClient.java:310)
at org.springframework.cloud.consul.serviceregistry.ConsulServiceRegistry.register(ConsulServiceRegistry.java:67)
at org.springframework.cloud.consul.serviceregistry.ConsulServiceRegistry.register(ConsulServiceRegistry.java:43)
at org.springframework.cloud.client.serviceregistry.AbstractAutoServiceRegistration.register(AbstractAutoServiceRegistration.java:264)
at org.springframework.cloud.consul.serviceregistry.ConsulAutoServiceRegistration.register(ConsulAutoServiceRegistration.java:80)
at org.springframework.cloud.client.serviceregistry.AbstractAutoServiceRegistration.start(AbstractAutoServiceRegistration.java:156)
at org.springframework.cloud.consul.serviceregistry.ConsulAutoServiceRegistration.start(ConsulAutoServiceRegistration.java:70)
at org.springframework.cloud.consul.serviceregistry.ConsulAutoServiceRegistrationListener.onApplicationEvent(ConsulAutoServiceRegistrationListener.java:60)
at org.springframework.context.event.SimpleApplicationEventMulticaster.doInvokeListener(SimpleApplicationEventMulticaster.java:185)
at org.springframework.context.event.SimpleApplicationEventMulticaster.invokeListener(SimpleApplicationEventMulticaster.java:178)
at org.springframework.context.event.SimpleApplicationEventMulticaster.multicastEvent(SimpleApplicationEventMulticaster.java:156)
at org.springframework.context.support.AbstractApplicationContext.publishEvent(AbstractApplicationContext.java:454)
at org.springframework.context.support.AbstractApplicationContext.publishEvent(AbstractApplicationContext.java:387)
at org.springframework.boot.web.reactive.context.WebServerManager.start(WebServerManager.java:57)
at org.springframework.boot.web.reactive.context.WebServerStartStopLifecycle.start(WebServerStartStopLifecycle.java:41)
at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:405)
at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:394)
at org.springframework.context.support.DefaultLifecycleProcessor$LifecycleGroup.start(DefaultLifecycleProcessor.java:586)
at java.base/java.lang.Iterable.forEach(Iterable.java:75)
at org.springframework.context.support.DefaultLifecycleProcessor.startBeans(DefaultLifecycleProcessor.java:364)
at org.springframework.context.support.DefaultLifecycleProcessor.onRefresh(DefaultLifecycleProcessor.java:310)
at org.springframework.context.support.AbstractApplicationContext.finishRefresh(AbstractApplicationContext.java:1006)
at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:630)
at org.springframework.boot.web.reactive.context.ReactiveWebServerApplicationContext.refresh(ReactiveWebServerApplicationContext.java:66)
at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:752)
at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:439)
at org.springframework.boot.SpringApplication.run(SpringApplication.java:318)
at org.springframework.boot.SpringApplication.run(SpringApplication.java:1361)
at org.springframework.boot.SpringApplication.run(SpringApplication.java:1350)
at at.mocode.infrastructure.gateway.GatewayApplicationKt.main(GatewayApplication.kt:13)
Caused by: org.apache.http.conn.HttpHostConnectException: Connect to localhost:8500 [localhost/127.0.0.1, localhost/0:0:0:0:0:0:0:1] failed: Verbindungsaufbau abgelehnt
at org.apache.http.impl.conn.DefaultHttpClientConnectionOperator.connect(DefaultHttpClientConnectionOperator.java:156)
at org.apache.http.impl.conn.PoolingHttpClientConnectionManager.connect(PoolingHttpClientConnectionManager.java:376)
at org.apache.http.impl.execchain.MainClientExec.establishRoute(MainClientExec.java:393)
at org.apache.http.impl.execchain.MainClientExec.execute(MainClientExec.java:236)
at org.apache.http.impl.execchain.ProtocolExec.execute(ProtocolExec.java:186)
at org.apache.http.impl.execchain.RetryExec.execute(RetryExec.java:89)
at org.apache.http.impl.execchain.RedirectExec.execute(RedirectExec.java:110)
at org.apache.http.impl.client.InternalHttpClient.doExecute(InternalHttpClient.java:185)
at org.apache.http.impl.client.CloseableHttpClient.execute(CloseableHttpClient.java:72)
at org.apache.http.impl.client.CloseableHttpClient.execute(CloseableHttpClient.java:221)
at org.apache.http.impl.client.CloseableHttpClient.execute(CloseableHttpClient.java:165)
at org.apache.http.impl.client.CloseableHttpClient.execute(CloseableHttpClient.java:140)
at com.ecwid.consul.transport.AbstractHttpTransport.executeRequest(AbstractHttpTransport.java:70)
... 33 common frames omitted
Caused by: java.net.ConnectException: Verbindungsaufbau abgelehnt
at java.base/sun.nio.ch.Net.pollConnect(Native Method)
at java.base/sun.nio.ch.Net.pollConnectNow(Net.java:682)
at java.base/sun.nio.ch.NioSocketImpl.timedFinishConnect(NioSocketImpl.java:542)
at java.base/sun.nio.ch.NioSocketImpl.connect(NioSocketImpl.java:592)
at java.base/java.net.SocksSocketImpl.connect(SocksSocketImpl.java:327)
at java.base/java.net.Socket.connect(Socket.java:751)
at org.apache.http.conn.socket.PlainConnectionSocketFactory.connectSocket(PlainConnectionSocketFactory.java:75)
at org.apache.http.impl.conn.DefaultHttpClientConnectionOperator.connect(DefaultHttpClientConnectionOperator.java:142)
... 45 common frames omitted
2025-10-15 10:31:27.376 [main] WARN [] o.s.b.w.r.c.AnnotationConfigReactiveWebServerApplicationContext - Exception encountered during context initialization - cancelling refresh attempt: org.springframework.context.ApplicationContextException: Failed to start bean 'webServerStartStop'
2025-10-15 10:31:27.401 [main] INFO [] o.s.b.a.l.ConditionEvaluationReportLogger -
Error starting ApplicationContext. To display the condition evaluation report re-run your application with 'debug' enabled.
2025-10-13 13:04:39.429 [main] ERROR [] o.s.b.d.LoggingFailureAnalysisReporter -
***************************
APPLICATION FAILED TO START
***************************
Description:
Parameter 0 of method setSecurityWebFilterChains in org.springframework.security.config.annotation.web.reactive.WebFluxSecurityConfiguration required a bean of type 'org.springframework.security.oauth2.jwt.ReactiveJwtDecoder' that could not be found.
Action:
Consider defining a bean of type 'org.springframework.security.oauth2.jwt.ReactiveJwtDecoder' in your configuration.
2025-10-13 13:05:28.345 [background-preinit] INFO [] o.h.validator.internal.util.Version - HV000001: Hibernate Validator 8.0.3.Final
2025-10-13 13:05:28.370 [main] INFO [] a.m.i.gateway.GatewayApplicationKt - Starting GatewayApplicationKt using Java 21.0.8 with PID 171968 (/home/stefan/WsMeldestelle/Meldestelle/infrastructure/gateway/build/classes/kotlin/main started by stefan in /home/stefan/WsMeldestelle/Meldestelle)
2025-10-13 13:05:28.370 [main] DEBUG [] a.m.i.gateway.GatewayApplicationKt - Running with Spring Boot v3.5.5, Spring v6.2.10
2025-10-13 13:05:28.370 [main] INFO [] a.m.i.gateway.GatewayApplicationKt - The following 1 profile is active: "dev"
2025-10-13 13:05:29.337 [main] INFO [] o.s.d.r.c.RepositoryConfigurationDelegate - Multiple Spring Data modules found, entering strict repository configuration mode
2025-10-13 13:05:29.339 [main] INFO [] o.s.d.r.c.RepositoryConfigurationDelegate - Bootstrapping Spring Data Redis repositories in DEFAULT mode.
2025-10-13 13:05:29.364 [main] INFO [] o.s.d.r.c.RepositoryConfigurationDelegate - Finished Spring Data repository scanning in 15 ms. Found 0 Redis repository interfaces.
2025-10-13 13:05:29.600 [main] INFO [] o.s.cloud.context.scope.GenericScope - BeanFactory id=62ead487-39a4-3fc3-b0b8-d0378aec5250
2025-10-13 13:05:30.899 [main] WARN [] o.s.b.w.r.c.AnnotationConfigReactiveWebServerApplicationContext - Exception encountered during context initialization - cancelling refresh attempt: org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'org.springframework.security.config.annotation.web.reactive.WebFluxSecurityConfiguration': Unsatisfied dependency expressed through method 'setSecurityWebFilterChains' parameter 0: Error creating bean with name 'securityWebFilterChain' defined in class path resource [at/mocode/infrastructure/gateway/security/SecurityConfig.class]: Failed to instantiate [org.springframework.security.web.server.SecurityWebFilterChain]: Factory method 'securityWebFilterChain' threw exception with message: No qualifying bean of type 'org.springframework.security.oauth2.jwt.ReactiveJwtDecoder' available
2025-10-13 13:05:30.913 [main] INFO [] o.s.b.a.l.ConditionEvaluationReportLogger -
Error starting ApplicationContext. To display the condition evaluation report re-run your application with 'debug' enabled.
2025-10-13 13:05:30.935 [main] ERROR [] o.s.b.d.LoggingFailureAnalysisReporter -
***************************
APPLICATION FAILED TO START
***************************
Description:
Parameter 0 of method setSecurityWebFilterChains in org.springframework.security.config.annotation.web.reactive.WebFluxSecurityConfiguration required a bean of type 'org.springframework.security.oauth2.jwt.ReactiveJwtDecoder' that could not be found.
Action:
Consider defining a bean of type 'org.springframework.security.oauth2.jwt.ReactiveJwtDecoder' in your configuration.
2025-10-13 13:13:52.530 [background-preinit] INFO [] o.h.validator.internal.util.Version - HV000001: Hibernate Validator 8.0.3.Final
2025-10-13 13:13:52.555 [main] INFO [] a.m.i.gateway.GatewayApplicationKt - Starting GatewayApplicationKt using Java 21.0.8 with PID 186912 (/home/stefan/WsMeldestelle/Meldestelle/infrastructure/gateway/build/classes/kotlin/main started by stefan in /home/stefan/WsMeldestelle/Meldestelle)
2025-10-13 13:13:52.556 [main] DEBUG [] a.m.i.gateway.GatewayApplicationKt - Running with Spring Boot v3.5.5, Spring v6.2.10
2025-10-13 13:13:52.556 [main] INFO [] a.m.i.gateway.GatewayApplicationKt - The following 1 profile is active: "dev"
2025-10-13 13:13:53.557 [main] INFO [] o.s.d.r.c.RepositoryConfigurationDelegate - Multiple Spring Data modules found, entering strict repository configuration mode
2025-10-13 13:13:53.559 [main] INFO [] o.s.d.r.c.RepositoryConfigurationDelegate - Bootstrapping Spring Data Redis repositories in DEFAULT mode.
2025-10-13 13:13:53.582 [main] INFO [] o.s.d.r.c.RepositoryConfigurationDelegate - Finished Spring Data repository scanning in 11 ms. Found 0 Redis repository interfaces.
2025-10-13 13:13:53.818 [main] INFO [] o.s.cloud.context.scope.GenericScope - BeanFactory id=975b4235-9f71-3915-8b41-1672bffbac8a
2025-10-13 13:13:55.925 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [After]
2025-10-13 13:13:55.925 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [Before]
2025-10-13 13:13:55.926 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [Between]
2025-10-13 13:13:55.926 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [Cookie]
2025-10-13 13:13:55.926 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [Header]
2025-10-13 13:13:55.926 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [Host]
2025-10-13 13:13:55.926 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [Method]
2025-10-13 13:13:55.926 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [Path]
2025-10-13 13:13:55.926 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [Query]
2025-10-13 13:13:55.926 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [ReadBody]
2025-10-13 13:13:55.926 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [RemoteAddr]
2025-10-13 13:13:55.926 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [XForwardedRemoteAddr]
2025-10-13 13:13:55.926 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [Weight]
2025-10-13 13:13:55.926 [main] INFO [] o.s.c.g.r.RouteDefinitionRouteLocator - Loaded RoutePredicateFactory [CloudFoundryRouteService]
2025-10-13 13:13:56.504 [main] INFO [] o.s.b.a.e.web.EndpointLinksResolver - Exposing 6 endpoints beneath base path '/actuator'
2025-10-13 13:13:57.065 [main] WARN [] o.s.c.l.c.LoadBalancerCacheAutoConfiguration$LoadBalancerCaffeineWarnLogger - Spring Cloud LoadBalancer is currently working with the default cache. While this cache implementation is useful for development and tests, it's recommended to use Caffeine cache in production.You can switch to using Caffeine cache, by adding it and org.springframework.cache.caffeine.CaffeineCacheManager to the classpath.
2025-10-13 13:13:57.150 [main] INFO [] o.s.b.w.e.netty.NettyWebServer - Netty started on port 8080 (http)
2025-10-13 13:13:57.153 [main] INFO [] o.s.c.c.s.ConsulServiceRegistry - Registering service with consul: NewService{id='meldestelle-8080-f1cacd41-0219-47ee-8249-1bbafe9ec3c8', name='meldestelle', tags=[], address='fedora', meta={secure=false}, port=8080, enableTagOverride=null, check=Check{script='null', dockerContainerID='null', shell='null', interval='10s', ttl='null', http='http://fedora:8080/actuator/health', method='null', header={}, tcp='null', timeout='null', deregisterCriticalServiceAfter='null', tlsSkipVerify=null, status='null', grpc='null', grpcUseTLS=null}, checks=null}
2025-10-13 13:13:57.286 [main] INFO [] a.m.i.gateway.GatewayApplicationKt - Started GatewayApplicationKt in 5.08 seconds (process running for 5.695)
2025-10-13 13:14:38.993 [SpringApplicationShutdownHook] INFO [] o.s.b.w.e.netty.GracefulShutdown - Commencing graceful shutdown. Waiting for active requests to complete
2025-10-13 13:14:38.995 [netty-shutdown] INFO [] o.s.b.w.e.netty.GracefulShutdown - Graceful shutdown complete
2025-10-13 13:14:41.016 [SpringApplicationShutdownHook] INFO [] o.s.c.c.s.ConsulServiceRegistry - Deregistering service with consul: meldestelle-8080-f1cacd41-0219-47ee-8249-1bbafe9ec3c8
2025-10-15 10:31:27.416 [main] ERROR [] o.s.boot.SpringApplication - Application run failed
org.springframework.context.ApplicationContextException: Failed to start bean 'webServerStartStop'
at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:408)
at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:394)
at org.springframework.context.support.DefaultLifecycleProcessor$LifecycleGroup.start(DefaultLifecycleProcessor.java:586)
at java.base/java.lang.Iterable.forEach(Iterable.java:75)
at org.springframework.context.support.DefaultLifecycleProcessor.startBeans(DefaultLifecycleProcessor.java:364)
at org.springframework.context.support.DefaultLifecycleProcessor.onRefresh(DefaultLifecycleProcessor.java:310)
at org.springframework.context.support.AbstractApplicationContext.finishRefresh(AbstractApplicationContext.java:1006)
at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:630)
at org.springframework.boot.web.reactive.context.ReactiveWebServerApplicationContext.refresh(ReactiveWebServerApplicationContext.java:66)
at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:752)
at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:439)
at org.springframework.boot.SpringApplication.run(SpringApplication.java:318)
at org.springframework.boot.SpringApplication.run(SpringApplication.java:1361)
at org.springframework.boot.SpringApplication.run(SpringApplication.java:1350)
at at.mocode.infrastructure.gateway.GatewayApplicationKt.main(GatewayApplication.kt:13)
Caused by: com.ecwid.consul.transport.TransportException: org.apache.http.conn.HttpHostConnectException: Connect to localhost:8500 [localhost/127.0.0.1, localhost/0:0:0:0:0:0:0:1] failed: Verbindungsaufbau abgelehnt
at com.ecwid.consul.transport.AbstractHttpTransport.executeRequest(AbstractHttpTransport.java:83)
at com.ecwid.consul.transport.AbstractHttpTransport.makePutRequest(AbstractHttpTransport.java:49)
at com.ecwid.consul.v1.ConsulRawClient.makePutRequest(ConsulRawClient.java:163)
at com.ecwid.consul.v1.agent.AgentConsulClient.agentServiceRegister(AgentConsulClient.java:273)
at com.ecwid.consul.v1.ConsulClient.agentServiceRegister(ConsulClient.java:310)
at org.springframework.cloud.consul.serviceregistry.ConsulServiceRegistry.register(ConsulServiceRegistry.java:67)
at org.springframework.cloud.consul.serviceregistry.ConsulServiceRegistry.register(ConsulServiceRegistry.java:43)
at org.springframework.cloud.client.serviceregistry.AbstractAutoServiceRegistration.register(AbstractAutoServiceRegistration.java:264)
at org.springframework.cloud.consul.serviceregistry.ConsulAutoServiceRegistration.register(ConsulAutoServiceRegistration.java:80)
at org.springframework.cloud.client.serviceregistry.AbstractAutoServiceRegistration.start(AbstractAutoServiceRegistration.java:156)
at org.springframework.cloud.consul.serviceregistry.ConsulAutoServiceRegistration.start(ConsulAutoServiceRegistration.java:70)
at org.springframework.cloud.consul.serviceregistry.ConsulAutoServiceRegistrationListener.onApplicationEvent(ConsulAutoServiceRegistrationListener.java:60)
at org.springframework.context.event.SimpleApplicationEventMulticaster.doInvokeListener(SimpleApplicationEventMulticaster.java:185)
at org.springframework.context.event.SimpleApplicationEventMulticaster.invokeListener(SimpleApplicationEventMulticaster.java:178)
at org.springframework.context.event.SimpleApplicationEventMulticaster.multicastEvent(SimpleApplicationEventMulticaster.java:156)
at org.springframework.context.support.AbstractApplicationContext.publishEvent(AbstractApplicationContext.java:454)
at org.springframework.context.support.AbstractApplicationContext.publishEvent(AbstractApplicationContext.java:387)
at org.springframework.boot.web.reactive.context.WebServerManager.start(WebServerManager.java:57)
at org.springframework.boot.web.reactive.context.WebServerStartStopLifecycle.start(WebServerStartStopLifecycle.java:41)
at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:405)
... 14 common frames omitted
Caused by: org.apache.http.conn.HttpHostConnectException: Connect to localhost:8500 [localhost/127.0.0.1, localhost/0:0:0:0:0:0:0:1] failed: Verbindungsaufbau abgelehnt
at org.apache.http.impl.conn.DefaultHttpClientConnectionOperator.connect(DefaultHttpClientConnectionOperator.java:156)
at org.apache.http.impl.conn.PoolingHttpClientConnectionManager.connect(PoolingHttpClientConnectionManager.java:376)
at org.apache.http.impl.execchain.MainClientExec.establishRoute(MainClientExec.java:393)
at org.apache.http.impl.execchain.MainClientExec.execute(MainClientExec.java:236)
at org.apache.http.impl.execchain.ProtocolExec.execute(ProtocolExec.java:186)
at org.apache.http.impl.execchain.RetryExec.execute(RetryExec.java:89)
at org.apache.http.impl.execchain.RedirectExec.execute(RedirectExec.java:110)
at org.apache.http.impl.client.InternalHttpClient.doExecute(InternalHttpClient.java:185)
at org.apache.http.impl.client.CloseableHttpClient.execute(CloseableHttpClient.java:72)
at org.apache.http.impl.client.CloseableHttpClient.execute(CloseableHttpClient.java:221)
at org.apache.http.impl.client.CloseableHttpClient.execute(CloseableHttpClient.java:165)
at org.apache.http.impl.client.CloseableHttpClient.execute(CloseableHttpClient.java:140)
at com.ecwid.consul.transport.AbstractHttpTransport.executeRequest(AbstractHttpTransport.java:70)
... 33 common frames omitted
Caused by: java.net.ConnectException: Verbindungsaufbau abgelehnt
at java.base/sun.nio.ch.Net.pollConnect(Native Method)
at java.base/sun.nio.ch.Net.pollConnectNow(Net.java:682)
at java.base/sun.nio.ch.NioSocketImpl.timedFinishConnect(NioSocketImpl.java:542)
at java.base/sun.nio.ch.NioSocketImpl.connect(NioSocketImpl.java:592)
at java.base/java.net.SocksSocketImpl.connect(SocksSocketImpl.java:327)
at java.base/java.net.Socket.connect(Socket.java:751)
at org.apache.http.conn.socket.PlainConnectionSocketFactory.connectSocket(PlainConnectionSocketFactory.java:75)
at org.apache.http.impl.conn.DefaultHttpClientConnectionOperator.connect(DefaultHttpClientConnectionOperator.java:142)
... 45 common frames omitted
scripts/validation/validate-docs.sh
+35
View File
@@ -197,6 +197,39 @@ calculate_completeness_score() {
fi
}
# Optional external link check (lychee)
link_check() {
log_info "Running external link check (if 'lychee' is available)..."
((CHECKS++))
if command -v lychee &> /dev/null; then
# Allow common transient codes and skip localhost links
lychee --no-progress --accept 200,204,301,302,429 --exclude "localhost|127.0.0.1|yourdomain.com" docs/**/*.md || {
log_error "Lychee reported broken external links"
}
else
log_warning "'lychee' not found, skipping external link check"
fi
}
# Optional PlantUML render check
plantuml_check() {
log_info "Rendering PlantUML diagrams to validate syntax (if 'plantuml' is available)..."
((CHECKS++))
if command -v plantuml &> /dev/null; then
# Render to SVG; failures should surface as non-zero exit
# Note: This may produce SVGs next to the .puml files in CI workspace
if compgen -G "docs/architecture/**/*.puml" > /dev/null; then
plantuml -tsvg -failfast2 docs/architecture/**/*.puml || log_error "PlantUML rendering failed"
elif compgen -G "docs/**/*.puml" > /dev/null; then
plantuml -tsvg -failfast2 docs/**/*.puml || log_error "PlantUML rendering failed"
else
log_warning "No .puml files found to render"
fi
else
log_warning "'plantuml' not found, skipping diagram rendering"
fi
}
# Main execution
main() {
echo "📚 Meldestelle Documentation Validation"
@@ -208,6 +241,8 @@ main() {
check_documentation_consistency
check_api_documentation
check_code_examples
link_check
plantuml_check
calculate_completeness_score
echo ""