Update setup guide and README to emphasize desktop-first development. Add detailed instructions for local setup, including prerequisites (JDK 25, Gradle 9.4.0, Docker), and clarify Docker backend stack as optional. Mark Sprint C tasks C-1 and C-2 as complete.
This commit is contained in:
parent
c6f28462eb
commit
7150622e1d
62
README.md
62
README.md
|
|
@ -1,6 +1,6 @@
|
|||
# Meldestelle
|
||||
|
||||
> Modulares System für Pferdesportveranstaltungen — gebaut mit Domain-Driven Design, Kotlin Multiplatform und Microservices.
|
||||
> Desktop‑First Meldestelle: Offline‑fähige Compose‑Desktop‑App mit optionalem Backend‑Stack. Domänengetrieben (DDD), Kotlin Multiplatform.
|
||||
|
||||
[](https://git.mo-code.at/mocode-software/meldestelle/actions)
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
|
|
@ -15,20 +15,28 @@ Die gesamte Projektdokumentation (Architektur, Fachdomäne, Entwickler-Anleitung
|
|||
|
||||
| Bereich | Inhalt |
|
||||
|-----------------------------------------------|---------------------------------------------|
|
||||
| [01_Architecture](./docs/01_Architecture) | Master Roadmap, ADRs, C4-Modelle |
|
||||
| [01_Architecture](./docs/01_Architecture) | Master Roadmap, ADRs, C4‑Modelle, Desktop‑Konzept |
|
||||
| [02_Guides](./docs/02_Guides) | Setup-Anleitungen, Entwickler-Guidelines |
|
||||
| [03_Domain](./docs/03_Domain) | Fachlichkeit, Turnierregeln, Entities |
|
||||
| [07_Infrastructure](./docs/07_Infrastructure) | Docker, Keycloak, CI/CD, Zora-Infrastruktur |
|
||||
|
||||
Wesentliche Architektur-Referenz: [Offline‑First Desktop & Backend (Kurzkonzept)](./docs/01_Architecture/konzept-offline-first-desktop-backend-de.md)
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Tech Stack
|
||||
## 🖥️ Primärer Fokus: Desktop‑App
|
||||
|
||||
- Compose Multiplatform (JVM Desktop) als primäre Zielplattform
|
||||
- Offline‑First: Lokale SQLDelight‑DB, Synchronisation optional
|
||||
- Multi‑Tenant‑Backend optional für Sync/Verwaltung (Schema‑per‑Tenant, vgl. ADR‑0021)
|
||||
|
||||
## 🏗️ Tech Stack (aktueller Stand)
|
||||
|
||||
| Schicht | Technologie |
|
||||
|-----------------------|---------------------------------------------------|
|
||||
| **Backend** | Kotlin, Spring Boot 3.x, Spring Cloud Gateway |
|
||||
| **Frontend** | Kotlin Multiplatform (KMP), Compose Multiplatform |
|
||||
| **Datenbank** | PostgreSQL + Exposed / JPA |
|
||||
| **Frontend (primär)** | Kotlin Multiplatform (KMP), Compose Multiplatform |
|
||||
| **Backend** | Kotlin (Ktor/Spring Boot), Spring Cloud Gateway |
|
||||
| **Datenbank** | SQLDelight (lokal), PostgreSQL (Backend) |
|
||||
| **Auth** | Keycloak (OAuth2 / OIDC) |
|
||||
| **Cache** | Valkey |
|
||||
| **Service Discovery** | Consul |
|
||||
|
|
@ -38,27 +46,51 @@ Die gesamte Projektdokumentation (Architektur, Fachdomäne, Entwickler-Anleitung
|
|||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start (Lokal)
|
||||
## 🚀 Quick Start (lokale Entwicklung)
|
||||
|
||||
Empfohlen: Starte die Desktop‑App direkt aus dem Repo. Der Backend‑Stack ist optional und wird nur für Sync/Integration benötigt.
|
||||
|
||||
### A) Desktop‑App starten (ohne Backend)
|
||||
|
||||
Voraussetzungen: JDK 21+, aktuelle Gradle Wrapper verwendet.
|
||||
|
||||
```bash
|
||||
# 1. Umgebungsvariablen vorbereiten (nur beim ersten Mal)
|
||||
cp .env.example .env
|
||||
# Desktop‑Shell ausführen (Compose Desktop)
|
||||
./gradlew :frontend:shells:meldestelle-desktop:run
|
||||
```
|
||||
|
||||
# 2. Infrastruktur starten (Postgres, Keycloak, Valkey, Consul, Zipkin)
|
||||
Hinweise:
|
||||
- Beim ersten Start wird die lokale Datenbank initialisiert (Offline‑First).
|
||||
- Architektur-Referenz: `docs/06_Frontend/MVVM_UDF_Pattern.md` (UDF/MVVM für ViewModels)
|
||||
|
||||
### B) Optional: Backend‑Stack per Docker starten
|
||||
|
||||
```bash
|
||||
# 1. Umgebungsvariablen (nur beim ersten Mal)
|
||||
cp .env.example .env || true
|
||||
|
||||
# 2. Infrastruktur (Postgres, Keycloak, Valkey, Consul, Zipkin)
|
||||
docker compose -f docker-compose.yaml -f dc-infra.yaml up -d
|
||||
|
||||
# 3. Backend-Services starten (Gateway, Ping-Service)
|
||||
# 3. Backend‑Services (Gateway, Masterdata, Ping, …)
|
||||
docker compose -f docker-compose.yaml -f dc-backend.yaml up -d
|
||||
|
||||
# 4. Ops-Stack starten (Prometheus, Grafana)
|
||||
# 4. Ops‑Stack (Prometheus, Grafana)
|
||||
docker compose -f docker-compose.yaml -f dc-ops.yaml up -d
|
||||
|
||||
# 5. Optional: Web-App starten
|
||||
# 5. Optional: Web‑Shell
|
||||
docker compose -f docker-compose.yaml -f dc-gui.yaml up -d
|
||||
```
|
||||
|
||||
> ⚠️ **Reihenfolge beachten:** Infra muss `healthy` sein, bevor Backend gestartet wird.
|
||||
> Keycloak benötigt ~60–90 Sekunden zum Hochfahren.
|
||||
> ⚠️ Reihenfolge beachten: Infra muss `healthy` sein, bevor Backend gestartet wird. Keycloak benötigt ~60–90 Sekunden.
|
||||
|
||||
---
|
||||
|
||||
## 🧭 Legacy (V1) Hinweise
|
||||
|
||||
- Ältere V1‑Abschnitte/Anleitungen (Web‑First/Microservices‑Only) gelten als DEPRECATED.
|
||||
- Verwende für lokale Entwicklung primär die Desktop‑App (siehe Quick Start). Docker‑Stacks sind optional für Integration/Sync.
|
||||
- In der Doku sind V1‑Seiten entsprechend markiert oder werden sukzessive bereinigt (siehe Roadmaps Sprint C‑4).
|
||||
|
||||
### Wichtige lokale Ports
|
||||
|
||||
|
|
|
|||
|
|
@ -7,14 +7,19 @@ tags: [setup, local, docker, gradle]
|
|||
|
||||
# Start Local (Lokales Setup)
|
||||
|
||||
Kurzanleitung, um das Projekt lokal in wenigen Minuten zu starten.
|
||||
Kurzanleitung, um das Projekt lokal in wenigen Minuten zu starten – Desktop‑First mit optionalem Docker‑Backend.
|
||||
|
||||
## Voraussetzungen
|
||||
- Docker und Docker Compose (v2)
|
||||
- Java 25 (JDK)
|
||||
- Git
|
||||
## Voraussetzungen (exakte Versionen)
|
||||
- Git ≥ 2.40
|
||||
- JDK 25 (Temurin/Eclipse Adoptium empfohlen) – Projekttoolchain lädt bei Bedarf automatisch
|
||||
- Gradle Wrapper 9.4.0 (wird über `./gradlew` automatisch verwendet)
|
||||
- Docker Engine ≥ 24, Docker Compose v2 ≥ 2.24
|
||||
|
||||
## Schnellstart
|
||||
Hinweise:
|
||||
- Die Java‑Toolchain wird per Gradle automatisch heruntergeladen (`org.gradle.java.installations.auto-download=true`). Ein lokal installiertes JDK 25 wird dennoch empfohlen für IDE‑Runs.
|
||||
- Auf Apple‑Silicon (arm64) sind die Docker‑Images optimiert; Keycloak nutzt `start --optimized`.
|
||||
|
||||
## Schnellstart (nur Backend in Docker)
|
||||
|
||||
```bash
|
||||
# 1) Repository klonen
|
||||
|
|
@ -25,7 +30,7 @@ cd meldestelle
|
|||
# Kopiere die Vorlage.
|
||||
cp .env.example .env
|
||||
|
||||
# 3) Infrastruktur starten (Postgres, Redis, Keycloak, Monitoring, Gateway)
|
||||
# 3) Infrastruktur starten (Postgres, Valkey, Keycloak, Tracing, Service Discovery)
|
||||
docker compose --profile infra up -d
|
||||
|
||||
# 4) Backend starten (Gateway + Ping Service)
|
||||
|
|
@ -33,10 +38,25 @@ docker compose --profile backend up -d
|
|||
```
|
||||
|
||||
Sobald die Infrastruktur läuft, erreichst du unter anderem:
|
||||
- Gateway: http://localhost:8081
|
||||
- Keycloak: http://localhost:8180
|
||||
- Grafana: http://localhost:3000
|
||||
- Prometheus: http://localhost:9090
|
||||
- Gateway (API): http://localhost:8081
|
||||
- Keycloak (IAM): http://localhost:8180
|
||||
- Zipkin (Tracing): http://localhost:9411
|
||||
- Consul (Service Discovery): http://localhost:8500
|
||||
- Optional Web‑App (falls `--profile gui` gebaut/gestartet): http://localhost:4000
|
||||
|
||||
## Desktop‑App starten (Compose Desktop)
|
||||
|
||||
Die Desktop‑App ist der primäre Entwicklungs‑Entry‑Point.
|
||||
|
||||
```bash
|
||||
# 1) Abhängigkeiten bauen (optional; Gradle lädt automatisch beim ersten Run)
|
||||
./gradlew :frontend:shells:meldestelle-desktop:build
|
||||
|
||||
# 2) Desktop‑App starten
|
||||
./gradlew :frontend:shells:meldestelle-desktop:run
|
||||
```
|
||||
|
||||
Voraussetzung: Für Features, die Backend‑Konnektivität benötigen (z. B. Login, Stammdaten), muss das Docker‑Backend (infra + backend) laufen. Für rein lokale/offline Flows kann die App auch ohne Docker gestartet werden.
|
||||
|
||||
## Tests ausführen
|
||||
```bash
|
||||
|
|
@ -58,9 +78,12 @@ Sobald die Infrastruktur läuft, erreichst du unter anderem:
|
|||
docker compose down -v
|
||||
docker compose --profile infra up -d
|
||||
```
|
||||
- Environment-Variablen: werden aus der `.env`-Datei im Root-Verzeichnis geladen.
|
||||
- Environment‑Variablen: werden aus der `.env`‑Datei im Root‑Verzeichnis geladen.
|
||||
- Gradle/Java Probleme? Stelle sicher, dass JDK 25 aktiv ist bzw. lasse die Gradle‑Toolchain das passende JDK laden.
|
||||
- ARM64 (Apple Silicon): Falls Images nicht starten, lösche alte Images und starte neu: `docker compose down -v && docker system prune -af && docker compose --profile infra up -d`.
|
||||
|
||||
## Weiterführende Hinweise
|
||||
- Architektur: `docs/01_Architecture/MASTER_ROADMAP_2026_Q1.md`
|
||||
- README Quick‑Start (Desktop‑First): `README.md`
|
||||
- Architektur‑Kurzkonzept (Offline‑First Desktop & Backend): `docs/01_Architecture/konzept-offline-first-desktop-backend-de.md`
|
||||
- ADRs: `docs/01_Architecture/adr/`
|
||||
- Aktuelle Reports: `docs/90_Reports/`
|
||||
|
|
|
|||
|
|
@ -57,14 +57,14 @@
|
|||
## 🟠 Sprint C — Priorität 2 (nächste Woche)
|
||||
|
||||
- [ ] **C-1** | `README.md` aktualisieren
|
||||
- [ ] Desktop-App als primären Fokus hervorheben
|
||||
- [ ] Schnellstart-Anleitung für lokale Entwicklungsumgebung prüfen
|
||||
- [ ] Veraltete V1-Abschnitte entfernen oder als deprecated markieren
|
||||
- [x] Desktop-App als primären Fokus hervorheben → `README.md` (03.04.2026)
|
||||
- [x] Schnellstart-Anleitung für lokale Entwicklungsumgebung prüfen → Desktop-Run (`:frontend:shells:meldestelle-desktop:run`) ergänzt (03.04.2026)
|
||||
- [x] Veraltete V1-Abschnitte entfernen oder als deprecated markieren → Abschnitt „Legacy (V1) Hinweise“ in `README.md` (03.04.2026)
|
||||
|
||||
- [ ] **C-2** | Setup-Guide aktualisieren
|
||||
- [ ] Schritt-für-Schritt: Projekt klonen → Docker starten → Desktop-App starten
|
||||
- [ ] Voraussetzungen (JDK, Gradle, Docker) mit exakten Versionen dokumentieren
|
||||
- [ ] Dokument in `docs/02_Guides/` ablegen
|
||||
- [x] **C-2** | Setup-Guide aktualisieren ✅ *3. April 2026*
|
||||
- [x] Schritt-für-Schritt: Projekt klonen → Docker starten → Desktop-App starten → `docs/02_Guides/start-local.md`
|
||||
- [x] Voraussetzungen (JDK, Gradle, Docker) mit exakten Versionen dokumentiert (JDK 25, Gradle 9.4.0, Compose v2)
|
||||
- [x] Dokument in `docs/02_Guides/` abgelegt/aktualisiert → `docs/02_Guides/start-local.md`
|
||||
|
||||
- [ ] **C-3** | Unterordner-Struktur in `docs/` prüfen
|
||||
- [ ] Überladene Verzeichnisse identifizieren
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user