StefanMoCoAt
5cc1ee6e4d
Integriert umfassende Makefile-Referenz in die Haupt-Dokumentation für bessere Auffindbarkeit und Developer Experience. Änderungen: - README.md: Erweitert "Makefile-Shortcuts" zu "Makefile-Befehle" - Hinzugefügt: Wichtigste Development-Befehle (full-up, services-up, dev-up, test, health-check) - Hinzugefügt: SSoT-Befehle (docker-sync, docker-compose-gen, docker-validate) - Hinzugefügt: Link zur vollständigen Referenz in docker-development.md - +20 Zeilen (Zeilen 292-319) - docs/how-to/start-local.md: Neue Sektion "Weitere Makefile-Befehle" - Hinzugefügt: Verweis auf `make help` - Hinzugefügt: Link zu Docker Development Guide Makefile-Referenz - +6 Zeilen (nach Zeile 39) Kontext: Diese Änderungen bauen auf der vollständigen Makefile-Dokumentation in .junie/guidelines/technology-guides/docker/docker-development.md auf (194 → 756 Zeilen, 50+ Befehle, erstellt am 2025-11-11). Nutzen: - Entwickler: Schnellerer Einstieg durch zentrale Übersicht - Onboarding: Alle wichtigen Befehle auf einen Blick - AI-Assistenten: Konsistente Command-Referenz - Dokumentation: Verbesserte Navigation zwischen How-To-Guides und Referenz Technische Details: Das Makefile umfasst 10 Befehlskategorien: 1. Development Workflow (dev-up, dev-down, dev-restart, dev-logs, dev-info) 2. Layer-spezifisch (infrastructure-*, services-*, clients-*) 3. Full System (full-up, full-down, full-restart, full-logs) 4. Build (build, build-service, build-client) 5. Test (test, test-e2e) 6. Environment (env-setup, env-dev, env-prod, env-staging, env-test, validate) 7. SSoT (versions-show, versions-update, docker-sync, docker-compose-gen, docker-validate, hooks-install) 8. Production (prod-up, prod-down, prod-restart, prod-logs) 9. Monitoring (status, health-check, logs, shell) 10. Cleanup (clean, clean-all) Related: - Vorherige Commits: Makefile-Optimierung (425 Zeilen, strukturiert) - Vorherige Commits: docker-development.md vollständige Aktualisierung - Vorherige Commits: Port-Korrekturen (8080 → 8081) Testing: - ✅ make help zeigt alle Befehle korrekt an - ✅ Links in Markdown funktionieren - ✅ Dokumentation konsistent mit aktuellem Makefile
397 lines
13 KiB
Markdown
397 lines
13 KiB
Markdown
# Meldestelle
|
||
|
||
> Modulares System für Pferdesportveranstaltungen mit Domain-Driven Design
|
||
|
||
[](https://github.com/StefanMoCoAt/meldestelle/actions)
|
||
[](https://github.com/StefanMoCoAt/meldestelle/actions)
|
||
[](https://opensource.org/licenses/MIT)
|
||
|
||
---
|
||
|
||
## 🚀 Quick Start
|
||
|
||
```bash
|
||
# 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](docs/how-to/start-local.md)
|
||
|
||
---
|
||
|
||
## 📚 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
|
||
# 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)
|
||
|
||
```bash
|
||
# 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):
|
||
|
||
```bash
|
||
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)
|
||
|
||
```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
|
||
|
||
# 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)
|
||
|
||
```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
|
||
|
||
# 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-Befehle
|
||
|
||
Das Projekt verwendet ein umfassendes Makefile mit ~50 Befehlen für alle Development-Workflows:
|
||
|
||
```bash
|
||
make help # Zeigt alle verfügbaren Befehle
|
||
```
|
||
|
||
**Wichtigste Befehle:**
|
||
|
||
```bash
|
||
make full-up # Startet komplettes System (Infra + Services + Clients)
|
||
make services-up # Startet Backend (Infra + Microservices)
|
||
make dev-up # Startet Development-Environment
|
||
make test # Führt Integration-Tests aus
|
||
make health-check # Prüft System-Health
|
||
```
|
||
|
||
**SSoT-Befehle:**
|
||
|
||
```bash
|
||
make docker-sync # Synchronisiert versions.toml -> build-args/*.env
|
||
make docker-compose-gen # Generiert Docker Compose Files
|
||
make docker-validate # Validiert Docker SSoT Konsistenz
|
||
```
|
||
|
||
**Vollständige Referenz:** [Docker Development Guide](.junie/guidelines/technology-guides/docker/docker-development.md#-vollständige-makefile-referenz)
|
||
|
||
### 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
|