mocode-software/meldestelle

Fork 0

StefanMo b35c4087a2

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(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)

* 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

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): 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): Markdown Regeln ausgebessert
Related: MP-DOCS-001

* Chore: Rerun CI checks with updated branch protection rules

2025-11-07 12:26:33 +01:00

12 KiB

Raw Blame History

Meldestelle

Modulares System für Pferdesportveranstaltungen mit Domain-Driven Design

🚀 Quick Start

# 1) Repository klonen
git clone https://github.com/StefanMoCoAt/meldestelle.git
cd meldestelle

# 2) (Optional, falls SSoT Compose-Files erst generiert werden müssen)
# DOCKER_SSOT_MODE=envless bash scripts/generate-compose-files.sh all development

# 3) Infrastruktur starten
docker compose -f docker-compose.yml up -d

# 4) Services starten (Beispiel)
./gradlew :members:members-service:bootRun
# oder – falls zentral gewollt und unterstützt
# ./gradlew bootRun

Vollständige Anleitung: docs/how-to/start-local.md

📚 Dokumentation

Single Source of Truth: YouTrack

Die Hauptdokumentation befindet sich in der YouTrack Wissensdatenbank:

👉 Meldestelle Command Center

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 - Übersicht aller Repository-Dokumentation
🏛️ Architecture Decision Records
📐 C4-Diagramme
🛠️ Developer Guides
📑 Projekt-Guidelines (Master)

Zusätzliche zentrale Guidelines:

🏗️ 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

🛠️ 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

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)

# Versionen anzeigen
bash scripts/docker-build.sh --versions

# Compose-Files generieren (Kompatibilitätsmodus)
bash scripts/generate-compose-files.sh all development

# Konsistenz validieren (Kompatibilitätsmodus)
bash scripts/validate-docker-consistency.sh all

SSoT – Zwei Betriebsmodi (konsistent)

# 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

Alternative (persistente Shell-Variante):

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

CI-Schutz – lokal reproduzieren (getrennte/verkettete Befehle)

# 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

# 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

# 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

Deployment (klarstellen, falls SSoT vorausgeht)

# 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

# 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

 ./gradlew test

Integration Tests

 ./gradlew integrationTest

Spezifisches Modul testen

 ./gradlew :members:members-service:test

🚢 Deployment

Lokale Entwicklung

Nur Infrastruktur (Postgres, Redis, Kafka, Keycloak)

 docker compose -f docker-compose.yml up -d

Services über Gradle

 ./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 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

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

 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 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 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

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	Build, Test, OpenAPI-Lint, Docs-Lint	Push/PR
ssot-guard.yml	Docker SSoT Validierung	Push/PR
docs-kdoc-sync.yml	KDoc → YouTrack Sync	workflow_dispatch
integration-tests.yml	Integration Tests	Push/PR
deploy-proxmox.yml	Deployment zu Proxmox	workflow_dispatch

📜 Lizenz

MIT License

🤝 Contributing

Bitte lies docs/how-to/branchschutz-und-pr-workflow.md für den PR-Workflow.

📞 Support & Kontakt

Bugs: GitHub Issues
Discussions: GitHub Discussions
Dokumentation: YouTrack Wissensdatenbank

Version: 2.0.0 (nach Dokumentations-Refactoring)
letzte Aktualisierung: 31. Oktober 2025

12 KiB Raw Blame History Unescape Escape