Fix: Test-Commit für VCS-Integration (MP-8) (#15)
* MP-8 OTHER Implementiere JWT-Authentifizierungs-Filter im Gateway * Fix(ci): Update upload-artifact action to v4 * Fix(ci): Add start command for Keycloak and failure logs * Fix(ci): Remove invalid 'command' property from Keycloak service * Fix(ci): Use KC_DEV_MODE env var to start Keycloak * Fix(ci): Keycloak service was removed from GitHub Actions services and replaced with a manual docker run step that starts Keycloak with the start-dev command. * dev(ci): vereinheitliche Keycloak auf 26.4.2; aktiviere Health im CI (MP-8) * Fix(ci): Stabilize Keycloak startup in integration tests via matrix - Add `dev-file` Keycloak variant to matrix for stability fallback. - Improve wait logic and health checks for Keycloak and Postgres. - Unify Keycloak version to 26.4.2 across codebase. - Add log dumps on failure. * Fix(ci): Die betroffene Datei docs/Visionen-Ideen/Infrastruktur-Strategie_DSGVO-Konformität.md endet aktuell mit genau einer leeren Zeile (Zeile 87). Das entspricht der Regel MD047 („Files should end with a single newline character“). Damit ist deine Korrektur korrekt. * Fix(ci): Repository-wide auto-fix for Markdown files was implemented with a GitHub Actions workflow and a local helper script. EditorConfig and markdownlint ignore files were added to ensure consistent formatting. Instructions for using the auto-fix both via GitHub Actions and locally were provided. * fix(gradle): build.gradle.kts jsBrowser testTask disabled * fix(gradle): build.gradle.kts jsBrowser testTask disabled * Fix(ci): Stabilize integration tests with Keycloak matrix build (MP-8) Introduces a matrix strategy (`keycloak_db: [postgres, dev-file]`) in the integration-tests workflow to mitigate flaky Keycloak starts when using the Postgres service container. - Adds a `dev-file` Keycloak variant for stability fallback. - Improves wait logic and health checks for Keycloak/Postgres. - Unifies Keycloak version to 26.4.2 across codebase (Dockerfile, Compose, ADR, README, tests). - Adds log dumps on failure in CI. - Ensures `KC_HEALTH_ENABLED=true` is set. - Updates related documentation (README, Schlachtplan). - Includes broader Docker SSoT cleanup (versions.toml as source, script updates, env file cleanup, validator hardening). This resolves recurring CI failures related to Keycloak startup and ensures required checks for PRs (#15) are reliable, while also improving overall Docker build consistency. * feat(docs, ci): Implement YouTrack SSoT strategy with Dokka sync (MP-8) - Add Dokka multi-module Gradle configuration and KDoc style guide. - Add GitHub Actions workflow (docs-kdoc-sync.yml) and Python script (youtrack-sync-kb.py) to sync Dokka GFM output to YouTrack KB. - Extend front-matter schema (bc, doc_type) and update relevant pages/stubs. - Adapt CI scripts (validate-frontmatter, check-docs-drift, ci-docs link ignore). - Update README.md to reference YouTrack KB. * feat(docs, ci): Implement YouTrack SSoT strategy with Dokka sync (MP-8) - Add Dokka multi-module Gradle configuration and KDoc style guide. - Add GitHub Actions workflow (docs-kdoc-sync.yml) and Python script (youtrack-sync-kb.py) to sync Dokka GFM output to YouTrack KB. - Extend front-matter schema (bc, doc_type) and update relevant pages/stubs. - Adapt CI scripts (validate-frontmatter, check-docs-drift, ci-docs link ignore). - Update README.md to reference YouTrack KB. * Fix(ci): Replace OpenAPI validator with Spectral Replaces the deprecated 'char0n/swagger-editor-validate' action, which failed due to sandbox issues in GitHub Actions, with the modern '@stoplight/spectral-cli'. This ensures robust OpenAPI specification validation without requiring a headless browser environment. The 'generate-api-docs' job now depends on the successful completion of the Spectral validation. Part of resolving CI failures for PR #15 (MP-8). * Fix(ci): Specify spectral:oas ruleset for OpenAPI validation (MP-8) * Fix(ci): Remove explicit ruleset argument for Spectral validation (MP-8) * Fix(ci): Added a .spectral.yaml file to fix Spectral linting errors. Corrected markdown lint issues in two documentation files. Updated README.md with a new guidelines section to fix link validation errors. * Fix(ci): Markdownlint errors were fixed by adding required blank lines. The Guidelines Validation error was resolved by updating the README.md link. The API Documentation Generator workflow was stabilized by updating paths, tasks, and validation steps. * Fix(ci): Alle vier fehlerhaften GitHub-Action-Prüfungen wurden behoben. Fehler in der OpenAPI-Spezifikation, Probleme mit der Markdown-Linting-Analyse und Validierungsfehler bei Querverweisen wurden korrigiert. Die README.md enthält nun alle erforderlichen Links zu den Richtlinien. * Fix(ci): Markdown linting errors in docs/api/README.md were fixed by specifying languages in fenced code blocks. OpenAPI specification errors in documentation.yaml were resolved by correcting example property types to strings. Cross-reference validation errors in README.md were fixed by adding the missing link to project-standards/coding-standards.md. * Fix(ci): Duplicate heading errors in docs/api/members-api.md were fixed. Cross-reference validation errors for docker-architecture.md were resolved. All originally reported issues passed validation successfully. * Fix(ci): The markdown heading levels in docs/api/members-api.md were corrected from h5 to h4 to fix linting errors. The missing cross-reference link from technology-guides/docker/docker-development.md to docker-overview.md was added. These fixes resolved the original validation and linting errors causing the process to fail. * Fix(ci): Duplicate heading warnings in docs/api/members-api.md were resolved. Cross-reference validation for docker-development.md to docker-architecture.md was fixed. A new unrelated warning about docker-production.md was identified but not addressed. * refactor(ci,docs): Simplify CI pipeline and migrate docs to YouTrack SSoT BREAKING CHANGE: Documentation structure radically simplified - Consolidate 9 GitHub Actions workflows into 1 main pipeline (ci-main.yml) - Remove redundant workflows: ci-docs, markdownlint-autofix, guidelines-validation, api-docs - Delete documentation migrated to YouTrack: api/, BCs/, Visionen-Ideen/, reference/, now/, overview/ - Keep only ADRs, C4 diagrams, and essential dev guides in repo - Update README.md with YouTrack KB links - Create new docs/README.md as documentation gateway - Relax markdown-lint config for pragmatic developer experience Kept workflows: - ssot-guard.yml (Docker SSoT validation) - docs-kdoc-sync.yml (KDoc → YouTrack sync) - integration-tests.yml (Integration tests) - deploy-proxmox.yml (Deployment) - youtrack-sync.yml (YouTrack integration) Related: MP-DOCS-001 * refactor(ci,docs): Simplify CI pipeline and migrate docs to YouTrack SSoT BREAKING CHANGE: Documentation structure radically simplified - Consolidate 9 GitHub Actions workflows into 1 main pipeline (ci-main.yml) - Remove redundant workflows: ci-docs, markdownlint-autofix, guidelines-validation, api-docs - Delete documentation migrated to YouTrack: api/, BCs/, Visionen-Ideen/, reference/, now/, overview/ - Keep only ADRs, C4 diagrams, and essential dev guides in repo - Update README.md with YouTrack KB links - Create new docs/README.md as documentation gateway - Relax markdown-lint config for pragmatic developer experience Kept workflows: - ssot-guard.yml (Docker SSoT validation) - docs-kdoc-sync.yml (KDoc → YouTrack sync) - integration-tests.yml (Integration tests) - deploy-proxmox.yml (Deployment) - youtrack-sync.yml (YouTrack integration) Related: MP-DOCS-001 * refactor(ci,docs): README.md und einige andere Dokumentationen überarbeitet. ports-and-urls.md hinzugefügt. Related: MP-DOCS-001 * refactor(ci,docs): Die Markdownlint-Fehler in README.md und docs/README.md wurden behoben, indem die Überschriftenebenen angepasst, überflüssige Satzzeichen am Ende entfernt und die notwendigen Leerzeilen um Überschriften, Listen, Tabellen und Codeblöcke eingefügt wurden. Das problematische Leerzeichen am Ende in docs/README.md wurde ebenfalls entfernt. Die Dateien entsprechen nun den vorgegebenen Markdownlint-Regeln und sollten die CI-Validierung bestehen. Related: MP-DOCS-001 * refactor(ci,docs): Docker guideline cross-references were fixed and normalized to lowercase labels. Validation scripts confirmed zero cross-reference warnings and consistent metadata. Documentation was updated with a changelog and enhanced README navigation. Related: MP-DOCS-001 * refactor(ci,docs): Docker guideline cross-references were fixed and normalized to lowercase labels. Validation scripts confirmed zero cross-reference warnings and consistent metadata. Documentation was updated with a changelog and enhanced README navigation. Related: MP-DOCS-001 * refactor(ci,docs): Dead links in docs/architecture/adr were fixed by updating URLs to stable sources and adding an ignore pattern for a placeholder link. Specific ADR files had their broken links replaced with valid ones. The markdown-link-check GitHub Action is expected to pass with zero dead links now. Related: MP-DOCS-001 * refactor(ci,docs): Links in ADR checked Related: MP-DOCS-001 * refactor(ci,docs): Links in ADR checked Related: MP-DOCS-001 * refactor(ci,docs): Markdown Regeln ausgebessert Related: MP-DOCS-001 * refactor(ci,docs): Markdown Regeln ausgebessert Related: MP-DOCS-001 * refactor(ci,docs): Markdown Regeln ausgebessert Related: MP-DOCS-001 * Chore: Rerun CI checks with updated branch protection rules
This commit is contained in:
StefanMo
@@ -1,387 +1,376 @@
|
||||
# Meldestelle
|
||||
|
||||
## Überblick
|
||||
> Modulares System für Pferdesportveranstaltungen mit Domain-Driven Design
|
||||
|
||||
Meldestelle ist ein modulares System zur Verwaltung von Pferdesportveranstaltungen. Das System ermöglicht die Registrierung von Pferden, Mitgliedern und Veranstaltungen sowie die Verwaltung von Stammdaten.
|
||||
[](https://github.com/StefanMoCoAt/meldestelle/actions)
|
||||
[](https://github.com/StefanMoCoAt/meldestelle/actions)
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
|
||||
Das Projekt wurde kürzlich auf eine modulare Architektur migriert, um die Wartbarkeit und Erweiterbarkeit zu verbessern.
|
||||
---
|
||||
|
||||
## Systemanforderungen
|
||||
|
||||
- Java 21
|
||||
- Kotlin 2.2.10
|
||||
- Gradle 9.0.0 (automatischer Download über Gradle Wrapper)
|
||||
- Docker und Docker Compose (v2.0+)
|
||||
|
||||
## Infrastruktur
|
||||
|
||||
Das System nutzt folgende Dienste:
|
||||
|
||||
- **PostgreSQL 16**: Primäre Datenbank
|
||||
- **Redis 7**: Caching
|
||||
- **Keycloak 23.0**: Authentifizierung und Autorisierung
|
||||
- **Kafka 7.5.0**: Messaging und Event-Streaming
|
||||
- **Zipkin**: Distributed Tracing
|
||||
- **Prometheus & Grafana**: Monitoring (optional)
|
||||
|
||||
## Projektstruktur
|
||||
|
||||
Das Projekt ist in folgende Hauptmodule unterteilt:
|
||||
|
||||
- **core**: Gemeinsame Kernkomponenten
|
||||
- core-domain: Domänenmodelle und Geschäftslogik
|
||||
- core-utils: Allgemeine Hilfsfunktionen
|
||||
|
||||
- **masterdata**: Umfassende Verwaltung von Stammdaten für Pferdesportveranstaltungen
|
||||
- **Funktionalität**: Länder (ISO-Codes, EU/EWR-Mitgliedschaft), Bundesländer (OEPS/ISO-Codes), Altersklassen (Teilnahmeberechtigung), Turnierplätze (Typ, Abmessungen, Boden)
|
||||
- **API-Endpunkte**: 37 REST-Endpunkte mit vollständiger CRUD-Funktionalität
|
||||
- **Geschäftslogik**: Validierung, Duplikatsprüfung, Berechtigung, Eignung für Disziplinen
|
||||
- masterdata-api: REST-Controller und DTO-Definitionen
|
||||
- masterdata-application: Use Cases und Geschäftslogik
|
||||
- masterdata-domain: Domänenmodelle und Repository-Interfaces
|
||||
- masterdata-infrastructure: Datenbankzugriff und Persistierung
|
||||
- masterdata-service: Spring Boot Service-Implementierung
|
||||
|
||||
- **members**: Mitgliederverwaltung
|
||||
- members-api: API-Definitionen
|
||||
- members-application: Anwendungslogik
|
||||
- members-domain: Domänenmodelle
|
||||
- members-infrastructure: Infrastrukturkomponenten
|
||||
- members-service: Service-Implementierung
|
||||
|
||||
- **horses**: Pferderegistrierung
|
||||
- horses-api: API-Definitionen
|
||||
- horses-application: Anwendungslogik
|
||||
- horses-domain: Domänenmodelle
|
||||
- horses-infrastructure: Infrastrukturkomponenten
|
||||
- horses-service: Service-Implementierung
|
||||
|
||||
- **events**: Veranstaltungsverwaltung
|
||||
- events-api: API-Definitionen
|
||||
- events-application: Anwendungslogik
|
||||
- events-domain: Domänenmodelle
|
||||
- events-infrastructure: Infrastrukturkomponenten
|
||||
- events-service: Service-Implementierung
|
||||
|
||||
- **infrastructure**: Gemeinsame Infrastrukturkomponenten
|
||||
- auth: Authentifizierung
|
||||
- cache: Caching
|
||||
- event-store: Event-Speicher
|
||||
- gateway: API-Gateway
|
||||
- messaging: Messaging-Infrastruktur
|
||||
- monitoring: Monitoring-Komponenten
|
||||
|
||||
- **client**: Client-Anwendungen
|
||||
- common-ui: Gemeinsame UI-Komponenten
|
||||
- desktop-app: Desktop-Anwendung
|
||||
- web-app: Web-Anwendung
|
||||
|
||||
## Installation und Setup
|
||||
|
||||
### Voraussetzungen
|
||||
|
||||
Stellen Sie sicher, dass Java 21, Docker und Docker Compose installiert sind.
|
||||
|
||||
### Docker-Infrastruktur
|
||||
|
||||
Das System bietet verschiedene Docker-Konfigurationen für unterschiedliche Umgebungen:
|
||||
|
||||
#### Entwicklungsumgebung (Schnellstart)
|
||||
## 🚀 Quick Start
|
||||
|
||||
```bash
|
||||
# Infrastruktur starten
|
||||
docker compose up -d
|
||||
# 1) Repository klonen
|
||||
git clone https://github.com/StefanMoCoAt/meldestelle.git
|
||||
cd meldestelle
|
||||
|
||||
# Status überprüfen
|
||||
docker compose ps
|
||||
# 2) (Optional, falls SSoT Compose-Files erst generiert werden müssen)
|
||||
# DOCKER_SSOT_MODE=envless bash scripts/generate-compose-files.sh all development
|
||||
|
||||
# Logs anzeigen
|
||||
docker compose logs -f
|
||||
```
|
||||
# 3) Infrastruktur starten
|
||||
docker compose -f docker-compose.yml up -d
|
||||
|
||||
Dies startet alle erforderlichen Dienste wie PostgreSQL, Redis, Keycloak, Kafka, Zipkin und optional Prometheus und Grafana.
|
||||
|
||||
#### Produktionsumgebung
|
||||
|
||||
Für die Produktionsumgebung siehe **[README-PRODUCTION.md](Tagebuch/README-PRODUCTION.md)** - enthält:
|
||||
- Umfassende Sicherheitskonfiguration
|
||||
- SSL/TLS-Setup
|
||||
- Detaillierte Troubleshooting-Anleitung
|
||||
- Backup- und Wiederherstellungsverfahren
|
||||
|
||||
#### Umgebungsvariablen
|
||||
|
||||
Für die Konfiguration von Umgebungsvariablen siehe **[README-ENV.md](Tagebuch/README-ENV.md)** - enthält:
|
||||
- Vollständige Umgebungsvariablen-Dokumentation
|
||||
- Validierungsskripte
|
||||
- Konfigurationsbeispiele
|
||||
|
||||
### Validierung und Troubleshooting
|
||||
|
||||
```bash
|
||||
# Umgebungsvariablen validieren
|
||||
./validate-env.sh
|
||||
|
||||
# Docker-Compose Konfiguration validieren
|
||||
./validate-docker-compose.sh
|
||||
|
||||
# Service-Status überprüfen
|
||||
docker-compose ps
|
||||
|
||||
# Service-Logs anzeigen
|
||||
docker-compose logs [service-name]
|
||||
```
|
||||
|
||||
### Projekt bauen
|
||||
|
||||
```bash
|
||||
./gradlew build
|
||||
```
|
||||
|
||||
### Dienste starten
|
||||
|
||||
```bash
|
||||
# Gateway starten
|
||||
./gradlew :infrastructure:gateway:bootRun
|
||||
|
||||
# Masterdata-Service starten
|
||||
./gradlew :masterdata:masterdata-service:bootRun
|
||||
|
||||
# Members-Service starten
|
||||
# 4) Services starten (Beispiel)
|
||||
./gradlew :members:members-service:bootRun
|
||||
|
||||
# Horses-Service starten
|
||||
./gradlew :horses:horses-service:bootRun
|
||||
|
||||
# Events-Service starten
|
||||
./gradlew :events:events-service:bootRun
|
||||
# oder – falls zentral gewollt und unterstützt
|
||||
# ./gradlew bootRun
|
||||
```
|
||||
|
||||
### Client-Anwendungen starten
|
||||
**Vollständige Anleitung**: [docs/how-to/start-local.md](docs/how-to/start-local.md)
|
||||
|
||||
Die Client-Anwendungen sind als ein gemeinsames Kotlin Multiplatform (KMP) Modul `:client` organisiert und liefern:
|
||||
- Desktop (JVM) über Compose Desktop
|
||||
- Web (Kotlin/JS im Browser) über Compose Multiplatform
|
||||
- Optional: WASM mit Flag -PenableWasm=true
|
||||
---
|
||||
|
||||
## 📚 Dokumentation
|
||||
|
||||
### Single Source of Truth: YouTrack
|
||||
|
||||
Die Hauptdokumentation befindet sich in der **YouTrack Wissensdatenbank**:
|
||||
|
||||
👉 **[Meldestelle Command Center](https://meldestelle-pro.youtrack.cloud/articles/MP-A-24)**
|
||||
|
||||
#### In YouTrack
|
||||
|
||||
- 🏗️ **Bounded Context Dokumentation** (Members, Horses, Events, Masterdata)
|
||||
- 📡 **API-Referenz** (automatisch aus KDoc generiert)
|
||||
- 🚀 **Deployment-Guides** (Proxmox, Cloudflare, Nginx)
|
||||
- 🔐 **Infrastruktur-Konfigurationen** (Netzwerk, Datenbanken, Keycloak)
|
||||
- 💡 **Roadmap & Visionen**
|
||||
|
||||
#### Im Repository
|
||||
|
||||
- [📖 docs/README.md](docs/README.md) - Übersicht aller Repository-Dokumentation
|
||||
- [🏛️ Architecture Decision Records](docs/architecture/adr)
|
||||
- [📐 C4-Diagramme](docs/architecture/c4)
|
||||
- [🛠️ Developer Guides](docs/how-to)
|
||||
- [📑 Projekt-Guidelines (Master)](.junie/guidelines/master-guideline.md)
|
||||
|
||||
Zusätzliche zentrale Guidelines:
|
||||
|
||||
- [Coding Standards](.junie/guidelines/project-standards/coding-standards.md)
|
||||
- [Testing Standards](.junie/guidelines/project-standards/testing-standards.md)
|
||||
- [Documentation Standards](.junie/guidelines/project-standards/documentation-standards.md)
|
||||
- [Architecture Principles](.junie/guidelines/project-standards/architecture-principles.md)
|
||||
- [Web App Guideline](.junie/guidelines/technology-guides/web-app-guideline.md)
|
||||
- Docker Guides:
|
||||
- [Docker Overview](.junie/guidelines/technology-guides/docker/docker-overview.md)
|
||||
- [Docker Architecture](.junie/guidelines/technology-guides/docker/docker-architecture.md)
|
||||
- [Docker Development](.junie/guidelines/technology-guides/docker/docker-development.md)
|
||||
- [Docker Production](.junie/guidelines/technology-guides/docker/docker-production.md)
|
||||
- [Docker Monitoring](.junie/guidelines/technology-guides/docker/docker-monitoring.md)
|
||||
- [Docker Troubleshooting](.junie/guidelines/technology-guides/docker/docker-troubleshooting.md)
|
||||
- Process Guide: [Trace Bullet](.junie/guidelines/process-guides/trace-bullet-guideline.md)
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architektur
|
||||
|
||||
### Bounded Contexts (DDD)
|
||||
|
||||
Das System ist in unabhängige Domänen aufgeteilt:
|
||||
|
||||
- **Members**: Mitgliederverwaltung
|
||||
- **Horses**: Pferderegistrierung
|
||||
- **Events**: Veranstaltungsverwaltung
|
||||
- **Masterdata**: Stammdaten (Länder, Altersklassen, Turnierplätze)
|
||||
|
||||
### Technische Architektur
|
||||
|
||||
- **Microservices**: Unabhängige Services mit API Gateway
|
||||
- **Event-Driven**: Apache Kafka für asynchrone Kommunikation
|
||||
- **Polyglot Persistence**: PostgreSQL + Redis
|
||||
- **Container-First**: Docker & Docker Compose
|
||||
|
||||
**Details**: [ADR-0002 Domain-Driven Design](docs/architecture/adr/0002-domain-driven-design-de.md)
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Tech Stack
|
||||
|
||||
| Komponente | Technologie | Version |
|
||||
|----------------|-------------------------------|---------|
|
||||
| **Backend** | Kotlin + Spring Boot | 3.x |
|
||||
| **JVM** | Java | 21 |
|
||||
| **Build** | Gradle | 9.1.0 |
|
||||
| **Datenbank** | PostgreSQL | 16 |
|
||||
| **Cache** | Redis | 7 |
|
||||
| **Messaging** | Apache Kafka | 7.4.0 |
|
||||
| **Auth** | Keycloak | 26.4.2 |
|
||||
| **Monitoring** | Prometheus + Grafana + Zipkin | - |
|
||||
| **Container** | Docker + Docker Compose | v2.0+ |
|
||||
|
||||
---
|
||||
|
||||
### 📦 Projektstruktur
|
||||
|
||||
```plaintext
|
||||
Meldestelle/
|
||||
├── 🗂️ client/ # Client-Anwendungen
|
||||
│ ├── desktop-app/
|
||||
│ └── web-app/
|
||||
├── 🗂️ core/ # Gemeinsame Kern-Komponenten
|
||||
│ ├── core-domain/
|
||||
│ └── core-utils/
|
||||
├── 🗂️ docs/ # Minimale Entwickler-Dokumentation
|
||||
│ ├── architecture/
|
||||
│ └── how-to/
|
||||
├── 🗂️ events/ # Bounded Context: Veranstaltungsverwaltung
|
||||
│ └── (analog zu members)
|
||||
├── 🗂️ horses/ # Bounded Context: Pferderegistrierung
|
||||
│ └── (analog zu members)
|
||||
├── 🗂️ infrastructure/ # Technische Infrastruktur
|
||||
│ ├── auth/ # Authentifizierung
|
||||
│ ├── cache/ # Caching (Redis)
|
||||
│ ├── gateway/ # API Gateway (Spring Cloud Gateway)
|
||||
│ ├── messaging/ # Kafka-Integration
|
||||
│ └── monitoring/ # Observability
|
||||
├── 🗂️ masterdata/ # Bounded Context: Stammdaten
|
||||
│ └── (analog zu members)
|
||||
└── 🗂️ members/ # Bounded Context: Mitgliederverwaltung
|
||||
├── members-api/
|
||||
├── members-application/
|
||||
├── members-domain/
|
||||
├── members-infrastructure/
|
||||
└── members-service/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Docker Single Source of Truth (SSoT)
|
||||
|
||||
Alle Versionen zentral in **`docker/versions.toml`**:
|
||||
|
||||
### SSoT – Schnellstart (präzisiert)
|
||||
|
||||
```bash
|
||||
# Desktop (JVM) starten
|
||||
./gradlew :client:run
|
||||
# Versionen anzeigen
|
||||
bash scripts/docker-build.sh --versions
|
||||
|
||||
# Web (WASM) – Development-Server mit Live-Reload
|
||||
./gradlew :client:wasmJsBrowserDevelopmentRun
|
||||
# Compose-Files generieren (Kompatibilitätsmodus)
|
||||
bash scripts/generate-compose-files.sh all development
|
||||
|
||||
# Web (WASM) – Production-Build (mit optionaler Bundle-Analyse)
|
||||
ANALYZE_BUNDLE=true ./gradlew :client:wasmJsBrowserProductionWebpack
|
||||
# Konsistenz validieren (Kompatibilitätsmodus)
|
||||
bash scripts/validate-docker-consistency.sh all
|
||||
```
|
||||
|
||||
Ausgabeorte (Build-Artefakte):
|
||||
- Desktop-Distributionen: client/build/compose/binaries
|
||||
- WASM Production Build: client/build/dist/wasmJs/productionExecutable
|
||||
|
||||
## Entwicklung
|
||||
|
||||
### Aktuelle Migrationshinweise
|
||||
|
||||
Das Projekt wurde kürzlich von einer monolithischen Struktur zu einer modularen Architektur migriert. Die Migration umfasste:
|
||||
|
||||
- Umzug von `:shared-kernel` zu `core`-Modulen
|
||||
- Umzug von `:master-data` zu `masterdata`-Modulen
|
||||
- Umzug von `:member-management` zu `members`-Modulen
|
||||
- Umzug von `:horse-registry` zu `horses`-Modulen
|
||||
- Umzug von `:event-management` zu `events`-Modulen
|
||||
- Umzug von `:api-gateway` zu `infrastructure/gateway`
|
||||
- Umzug von `:composeApp` zu `client`-Modulen
|
||||
|
||||
Es gibt noch einige offene Probleme, insbesondere bei den Client-Modulen, die Kotlin Multiplatform und Compose Multiplatform verwenden.
|
||||
|
||||
#### Status der Client-Module (nach Migration)
|
||||
- Build-Status: :client baut erfolgreich für JVM, JS und WASM (Chrome/Karma-Tests sind bewusst deaktiviert, siehe unten)
|
||||
- Desktop: Compose Desktop App startet über :client:run; API-Basisadresse via Umgebungsvariable API_BASE_URL (Default: http://localhost:8081)
|
||||
- Web/WASM: Development-Server (:client:wasmJsBrowserDevelopmentRun) und Production-Build (:client:wasmJsBrowserProductionWebpack) funktionieren; API-Aufruf erfolgt same-origin über /api/ping (hinter dem Gateway)
|
||||
- HTTP-Client: Minimaler Ktor-Client (ohne überflüssige Plugins) zur Reduzierung der Bundle-Größe
|
||||
- UI: Platzhalter-/Demo-Features (Ping, Platform-Info, Conditional Panels) vorhanden; Domänenseiten für masterdata/members/horses/events noch ausständig
|
||||
|
||||
Bekannte Einschränkungen & offene Punkte:
|
||||
- End-to-End-Navigation zu allen Domänen (masterdata, members, horses, events) fehlt noch
|
||||
- Authentifizierung/Session-Handling im Client noch nicht integriert (Gateway/Keycloak folgt)
|
||||
- Browser-basierte Unit-Tests (Karma/ChromeHeadless) sind abgeschaltet, um lokale Sandbox-Probleme zu vermeiden; JS-Tests laufen unter Node/Mocha
|
||||
|
||||
#### WASM-Bundle-Analyse & Optimierung
|
||||
- Aktivieren über Umgebungsvariable ANALYZE_BUNDLE=true beim Production-WebBuild:
|
||||
|
||||
ANALYZE_BUNDLE=true ./gradlew :client:wasmJsBrowserProductionWebpack
|
||||
|
||||
- Die Datei client/webpack.config.d/bundle-analyzer.js protokolliert die Asset-Größen und gibt Optimierungshinweise aus
|
||||
- client/webpack.config.d/wasm-optimization.js aktiviert Tree-Shaking, Chunk-Splitting und Produktionsoptimierungen
|
||||
- Weitere Tipps: Reduktion schwerer UI-Komponenten, Lazy Loading, Entfernen ungenutzter Abhängigkeiten
|
||||
|
||||
#### Integrationstests und E2E-Hinweise
|
||||
- Vorhandene Modul-Integrationstests können per ./gradlew test ausgeführt werden
|
||||
- Für manuelles E2E:
|
||||
1) docker compose up -d (Gateway + Services)
|
||||
2) Desktop-Client starten oder WASM-Dev-Server starten
|
||||
3) Ping im Client ausführen; Erwartung: Status OK vom Gateway-Endpunkt /api/ping
|
||||
|
||||
### Entwicklungsrichtlinien
|
||||
|
||||
- Verwenden Sie die in der Projektstruktur definierten Module
|
||||
- Folgen Sie den Architekturentscheidungen (ADRs) im Verzeichnis `docs/architecture/adr` (verfügbar in Deutsch mit Dateiendung `-de.md`)
|
||||
- Verwenden Sie die C4-Diagramme im Verzeichnis `docs/architecture/c4` für einen Überblick über die Systemarchitektur (verfügbar in Deutsch mit Dateiendung `-de.puml`)
|
||||
- Verwenden Sie die Datenmodelle aus `docs/architecture/data-model`
|
||||
|
||||
### Tests ausführen
|
||||
### SSoT – Zwei Betriebsmodi (konsistent)
|
||||
|
||||
```bash
|
||||
./gradlew test
|
||||
# 1) Kompatibilitätsmodus (compat)
|
||||
bash scripts/docker-versions-update.sh sync
|
||||
bash scripts/generate-compose-files.sh all development
|
||||
bash scripts/validate-docker-consistency.sh all
|
||||
|
||||
# 2) Env-less Modus (empfohlen)
|
||||
DOCKER_SSOT_MODE=envless bash scripts/docker-build.sh --versions
|
||||
DOCKER_SSOT_MODE=envless bash scripts/generate-compose-files.sh all development
|
||||
DOCKER_SSOT_MODE=envless bash scripts/validate-docker-consistency.sh all
|
||||
```
|
||||
|
||||
## Docker Troubleshooting (Entwicklungsumgebung)
|
||||
|
||||
### Häufige Probleme und Lösungen
|
||||
|
||||
#### 1. Services starten nicht
|
||||
```bash
|
||||
# Alle Services stoppen und neu starten
|
||||
docker compose down
|
||||
docker compose up -d
|
||||
|
||||
# Einzelnen Service neu starten
|
||||
docker compose restart [service-name]
|
||||
|
||||
# Service-Logs überprüfen
|
||||
docker compose logs [service-name]
|
||||
```
|
||||
|
||||
#### 2. Port bereits belegt
|
||||
```bash
|
||||
# Verwendete Ports prüfen
|
||||
netstat -tulpn | grep :[port]
|
||||
# oder
|
||||
lsof -i :[port]
|
||||
|
||||
# Ports in .env anpassen
|
||||
nano .env
|
||||
# Beispiel: API_PORT=8081 statt 8080
|
||||
```
|
||||
|
||||
#### 3. Datenbank-Verbindungsfehler
|
||||
```bash
|
||||
# PostgreSQL-Status prüfen
|
||||
docker compose exec postgres pg_isready -U meldestelle
|
||||
|
||||
# Datenbank-Logs anzeigen
|
||||
docker compose logs postgres
|
||||
|
||||
# Verbindung manuell testen
|
||||
docker compose exec postgres psql -U meldestelle -d meldestelle
|
||||
```
|
||||
|
||||
#### 4. Keycloak-Authentifizierung fehlgeschlagen
|
||||
```bash
|
||||
# Keycloak-Status prüfen
|
||||
docker compose logs keycloak
|
||||
|
||||
# Keycloak Admin-Console öffnen
|
||||
# http://localhost:8180/admin (admin/admin)
|
||||
|
||||
# Keycloak-Datenbank zurücksetzen
|
||||
docker compose down
|
||||
docker volume rm meldestelle_postgres-data
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
#### 5. Kafka-Verbindungsprobleme
|
||||
```bash
|
||||
# Kafka-Status prüfen
|
||||
docker compose exec kafka kafka-topics --bootstrap-server localhost:9092 --list
|
||||
|
||||
# Zookeeper-Status prüfen
|
||||
docker compose exec zookeeper nc -z localhost 2181
|
||||
|
||||
# Kafka-Logs anzeigen
|
||||
docker compose logs kafka zookeeper
|
||||
```
|
||||
|
||||
#### 6. Speicherplatz-Probleme
|
||||
```bash
|
||||
# Docker-Speicherverbrauch prüfen
|
||||
docker system df
|
||||
|
||||
# Ungenutzte Ressourcen bereinigen
|
||||
docker system prune -f
|
||||
|
||||
# Volumes bereinigen (ACHTUNG: Datenverlust!)
|
||||
docker system prune -f --volumes
|
||||
```
|
||||
|
||||
#### 7. Performance-Probleme
|
||||
```bash
|
||||
# Ressourcenverbrauch überwachen
|
||||
docker stats
|
||||
|
||||
# Container-Limits anpassen (in docker-compose.yml)
|
||||
# deploy:
|
||||
# resources:
|
||||
# limits:
|
||||
# memory: 1G
|
||||
# cpus: '0.5'
|
||||
```
|
||||
|
||||
### Nützliche Docker-Befehle
|
||||
Alternative (persistente Shell-Variante):
|
||||
|
||||
```bash
|
||||
# Alle Services mit Logs starten
|
||||
docker compose up
|
||||
|
||||
# Services im Hintergrund starten
|
||||
docker compose up -d
|
||||
|
||||
# Bestimmte Services starten
|
||||
docker compose up postgres redis
|
||||
|
||||
# Services stoppen
|
||||
docker compose stop
|
||||
|
||||
# Services stoppen und Container entfernen
|
||||
docker compose down
|
||||
|
||||
# Services mit Volume-Bereinigung stoppen
|
||||
docker compose down -v
|
||||
|
||||
# Container-Shell öffnen
|
||||
docker compose exec [service-name] /bin/bash
|
||||
# oder für Alpine-basierte Images:
|
||||
docker compose exec [service-name] /bin/sh
|
||||
|
||||
# Konfiguration validieren
|
||||
docker compose config
|
||||
|
||||
# Service-Status anzeigen
|
||||
docker compose ps
|
||||
|
||||
# Logs aller Services anzeigen
|
||||
docker compose logs
|
||||
|
||||
# Logs eines bestimmten Services verfolgen
|
||||
docker compose logs -f [service-name]
|
||||
export DOCKER_SSOT_MODE=envless
|
||||
bash scripts/docker-build.sh --versions
|
||||
bash scripts/generate-compose-files.sh all development
|
||||
bash scripts/validate-docker-consistency.sh all
|
||||
```
|
||||
|
||||
## Dokumentation
|
||||
#### CI-Schutz – lokal reproduzieren (getrennte/verkettete Befehle)
|
||||
|
||||
Weitere Dokumentation finden Sie im `docs`-Verzeichnis:
|
||||
```bash
|
||||
# Compat
|
||||
bash scripts/docker-versions-update.sh sync && \
|
||||
bash scripts/generate-compose-files.sh all development && \
|
||||
bash scripts/validate-docker-consistency.sh all && \
|
||||
git diff --name-only # sollte leer sein
|
||||
|
||||
- API-Dokumentation: `docs/api`
|
||||
- Architektur: `docs/architecture`
|
||||
- Entwicklungsrichtlinien: `docs/development`
|
||||
- Diagramme: `docs/diagrams`
|
||||
- Betriebsanleitung: `docs/operations`
|
||||
- Postman-Sammlungen: `docs/postman`
|
||||
# Env-less (Variante A: prefix)
|
||||
DOCKER_SSOT_MODE=envless bash scripts/generate-compose-files.sh all development && \
|
||||
DOCKER_SSOT_MODE=envless bash scripts/validate-docker-consistency.sh all && \
|
||||
git diff --name-only # sollte leer sein
|
||||
|
||||
## Lizenz
|
||||
# Env-less (Variante B: export)
|
||||
export DOCKER_SSOT_MODE=envless
|
||||
bash scripts/generate-compose-files.sh all development && \
|
||||
bash scripts/validate-docker-consistency.sh all && \
|
||||
git diff --name-only # sollte leer sein
|
||||
```
|
||||
|
||||
Siehe [LICENSE](LICENSE) Datei.
|
||||
### Deployment (klarstellen, falls SSoT vorausgeht)
|
||||
|
||||
## Stand
|
||||
```bash
|
||||
# Nur Infrastruktur
|
||||
# Wenn eine handgeschriebene docker-compose.yml existiert:
|
||||
docker compose -f docker-compose.yml up -d
|
||||
# Falls Compose-Files generiert werden:
|
||||
docker compose -f docker-compose.services.yml up -d
|
||||
|
||||
Letzte Aktualisierung: 14. September 2025
|
||||
# Services via Gradle
|
||||
a) Einzeldienst
|
||||
./gradlew :members:members-service:bootRun
|
||||
b) Falls unterstützt: alle (oder Aggregator)
|
||||
./gradlew bootRun
|
||||
```
|
||||
|
||||
**Details**: Siehe Abschnitt "Docker Single Source of Truth (SSoT)" weiter unten
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### Unit Tests
|
||||
|
||||
```bash
|
||||
./gradlew test
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
|
||||
```bash
|
||||
./gradlew integrationTest
|
||||
```
|
||||
|
||||
### Spezifisches Modul testen
|
||||
|
||||
```bash
|
||||
./gradlew :members:members-service:test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚢 Deployment
|
||||
|
||||
### Lokale Entwicklung
|
||||
|
||||
#### Nur Infrastruktur (Postgres, Redis, Kafka, Keycloak)
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.yml up -d
|
||||
```
|
||||
|
||||
#### Services über Gradle
|
||||
|
||||
```bash
|
||||
./gradlew bootRun
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Docker Single Source of Truth (SSoT)—Details
|
||||
|
||||
Dieser Abschnitt beschreibt den lokalen Workflow für die zentrale Docker-Versionsverwaltung.
|
||||
|
||||
### TL;DR – Zwei Betriebsmodi
|
||||
|
||||
- **Kompatibilitätsmodus (Standard)**: `build-args/*.env` werden aus `versions.toml` generiert
|
||||
|
||||
```bash
|
||||
bash scripts/docker-versions-update.sh sync
|
||||
bash scripts/generate-compose-files.sh all development
|
||||
bash scripts/validate-docker-consistency.sh all
|
||||
```
|
||||
|
||||
- **Env-less Modus (Empfohlen)**: Keine `build-args/*.env` nötig – direkter Export aus `versions.toml`
|
||||
|
||||
```bash
|
||||
DOCKER_SSOT_MODE=envless bash scripts/docker-build.sh --versions
|
||||
DOCKER_SSOT_MODE=envless bash scripts/generate-compose-files.sh all development
|
||||
DOCKER_SSOT_MODE=envless bash scripts/validate-docker-consistency.sh all
|
||||
```
|
||||
|
||||
### Makefile-Shortcuts
|
||||
|
||||
```bash
|
||||
make docker-sync # Kompatibilitätsmodus: Sync
|
||||
make docker-compose-gen # Compose-Files generieren
|
||||
make docker-validate # Validierung
|
||||
```
|
||||
|
||||
### Was ist die Single Source of Truth?
|
||||
|
||||
- **`docker/versions.toml`** enthält alle Versionsangaben (Gradle, Java, Node, Nginx, Postgres, Redis, etc.)
|
||||
- **Env-less**: `docker/build-args/*.env` sind optional; Variablen zur Laufzeit aus `versions.toml`
|
||||
- **docker-compose*.yml** werden generiert und referenzieren nur zentrale `DOCKER_*`-Variablen
|
||||
- **Dockerfiles** deklarieren ARGs ohne Default-Werte
|
||||
|
||||
### Versionen ändern
|
||||
|
||||
```bash
|
||||
bash scripts/docker-versions-update.sh update gradle 9.1.0
|
||||
bash scripts/docker-versions-update.sh update node 22.21.0
|
||||
bash scripts/docker-versions-update.sh update postgres 16-alpine
|
||||
```
|
||||
|
||||
Danach: `generate` + `validate` ausführen!
|
||||
|
||||
### CI-Schutz
|
||||
|
||||
Die CI validiert Docker SSoT in beiden Modi (Matrix: compat + envless).
|
||||
|
||||
**Lokal reproduzieren**:
|
||||
|
||||
#### Compat
|
||||
|
||||
```bash
|
||||
bash scripts/docker-versions-update.sh sync && \
|
||||
bash scripts/generate-compose-files.sh all development && \
|
||||
bash scripts/validate-docker-consistency.sh all && \
|
||||
git diff --name-only # sollte leer sein
|
||||
```
|
||||
|
||||
#### Env-less
|
||||
|
||||
```bash
|
||||
DOCKER_SSOT_MODE=envless bash scripts/generate-compose-files.sh all development && \
|
||||
DOCKER_SSOT_MODE=envless bash scripts/validate-docker-consistency.sh all && \
|
||||
git diff --name-only # sollte leer sein
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Automatisierte Workflows
|
||||
|
||||
| Workflow | Zweck | Trigger |
|
||||
|------------------------------------------------------------------|--------------------------------------|-------------------|
|
||||
| [ci-main.yml](.github/workflows/ci-main.yml) | Build, Test, OpenAPI-Lint, Docs-Lint | Push/PR |
|
||||
| [ssot-guard.yml](.github/workflows/ssot-guard.yml) | Docker SSoT Validierung | Push/PR |
|
||||
| [docs-kdoc-sync.yml](.github/workflows/docs-kdoc-sync.yml) | KDoc → YouTrack Sync | workflow_dispatch |
|
||||
| [integration-tests.yml](.github/workflows/integration-tests.yml) | Integration Tests | Push/PR |
|
||||
| [deploy-proxmox.yml](.github/workflows/deploy-proxmox.yml) | Deployment zu Proxmox | workflow_dispatch |
|
||||
|
||||
---
|
||||
|
||||
## 📜 Lizenz
|
||||
|
||||
[MIT License](LICENSE)
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Bitte lies [docs/how-to/branchschutz-und-pr-workflow.md](docs/how-to/branchschutz-und-pr-workflow.md) für den
|
||||
PR-Workflow.
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support & Kontakt
|
||||
|
||||
- **Bugs**: [GitHub Issues](https://github.com/StefanMoCoAt/meldestelle/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/StefanMoCoAt/meldestelle/discussions)
|
||||
- **Dokumentation**: [YouTrack Wissensdatenbank](https://meldestelle-pro.youtrack.cloud/articles/MP-A-24)
|
||||
|
||||
---
|
||||
|
||||
**Version**: 2.0.0 (nach Dokumentations-Refactoring)
|
||||
**letzte Aktualisierung**: 31. Oktober 2025
|
||||
|
||||
Reference in New Issue
Block a user