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

Fix: Test-Commit für VCS-Integration (MP-8) (#15)

Browse Source 
* 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
2025-11-07 12:26:33 +01:00
committed by GitHub
parent 6850cd92d4
commit b35c4087a2
129 changed files with 4016 additions and 7131 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.junie/guidelines/technology-guides/docker/docker-architecture.md
+34 -26
View File
@@ -1,6 +1,7 @@
# Docker-Architektur und Services
---
guideline_type: "technology"
scope: "docker-architecture"
audience: ["developers", "ai-assistants", "devops"]
@@ -8,16 +9,19 @@ last_updated: "2025-09-15"
dependencies: ["docker-overview.md", "master-guideline.md"]
related_files: ["docker-compose.yml", "docker/versions.toml", "scripts/docker-versions-update.sh"]
ai_context: "Docker-Container-Architektur, Service-Definitionen und zentrale Versionsverwaltung"
---
## 🏗️ Architektur-Überblick
> **📖 Hinweis:** Für einen allgemeinen Überblick über die Docker-Infrastruktur siehe [docker-overview](docker-overview.md).
### Container-Kategorien
```mermaid
graph TB
subgraph "Infrastructure Services"
PG[PostgreSQL]
PG[PostgresQL]
RD[Redis]
KC[Keycloak]
KF[Kafka+Zookeeper]
@@ -51,20 +55,20 @@ graph TB
### Service-Ports Matrix
| Service | Development | Production | Health Check | Debug Port | Version |
|---------|------------|------------|--------------|------------|---------|
| PostgreSQL | 5432 | Internal | pg_isready -U meldestelle -d meldestelle | - | 16-alpine |
| Redis | 6379 | Internal | redis-cli ping | - | 7-alpine |
| Keycloak | 8180 | 8443 (HTTPS) | /health/ready | - | 26.0.7 |
| Kafka | 9092 | Internal | kafka-topics --bootstrap-server localhost:9092 --list | - | 7.4.0 |
| Zookeeper | 2181 | Internal | nc -z localhost 2181 | - | 7.4.0 |
| Consul | 8500 | Internal | /v1/status/leader | - | 1.15 |
| Auth Server | 8081 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
| Ping Service | 8082 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
| Monitoring Server | 8083 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
| Prometheus | 9090 | Internal | /-/healthy | - | v2.54.1 |
| Grafana | 3000 | 3443 (HTTPS) | /api/health | - | 11.3.0 |
| Nginx | - | 80/443 | /health | - | 1.25-alpine |
| Service | Development | Production | Health Check | Debug Port | Version |
|-------------------|-------------|--------------|-------------------------------------------------------|------------|-------------|
| PostgreSQL | 5432 | Internal | pg_isready -U meldestelle -d meldestelle | - | 16-alpine |
| Redis | 6379 | Internal | redis-cli ping | - | 7-alpine |
| Keycloak | 8180 | 8443 (HTTPS) | /health/ready | - | 26.0.7 |
| Kafka | 9092 | Internal | kafka-topics --bootstrap-server localhost:9092 --list | - | 7.4.0 |
| Zookeeper | 2181 | Internal | nc -z localhost 2181 | - | 7.4.0 |
| Consul | 8500 | Internal | /v1/status/leader | - | 1.15 |
| Auth Server | 8081 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
| Ping Service | 8082 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
| Monitoring Server | 8083 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
| Prometheus | 9090 | Internal | /-/healthy | - | v2.54.1 |
| Grafana | 3000 | 3443 (HTTPS) | /api/health | - | 11.3.0 |
| Nginx | - | 80/443 | /health | - | 1.25-alpine |
## 🎯 Zentrale Docker-Versionsverwaltung
@@ -93,18 +97,18 @@ ARG GRADLE_VERSION=9.0.0
```toml
# docker/versions.toml - SINGLE SOURCE OF TRUTH
[versions]
gradle = "9.0.0"
gradle = "9.1.0"
java = "21"
node = "20.12.0"
nginx = "1.25-alpine"
node = "22.21.0"
nginx = "1.28.0-alpine"
prometheus = "v2.54.1"
grafana = "11.3.0"
keycloak = "26.0.7"
keycloak = "26.4.2"
```
### 🏗️ Architektur der zentralen Versionsverwaltung
```
```plaintext
docker/
├── versions.toml # 🎯 Single Source of Truth
├── build-args/ # Auto-generierte Environment Files
@@ -118,10 +122,11 @@ docker/
### 📊 Hierarchische Versionsverwaltung
#### 1. **Globale Versionen** (`docker/build-args/global.env`)
Verwendet von **allen** Dockerfiles:
```bash
# --- Build Tools ---
GRADLE_VERSION=9.0.0
GRADLE_VERSION=9.1.0
JAVA_VERSION=21
# --- Build Metadata ---
@@ -136,7 +141,7 @@ ECLIPSE_TEMURIN_JRE_VERSION=21-jre-alpine
# --- Monitoring & Infrastructure Services ---
DOCKER_PROMETHEUS_VERSION=v2.54.1
DOCKER_GRAFANA_VERSION=11.3.0
DOCKER_KEYCLOAK_VERSION=26.0.7
DOCKER_KEYCLOAK_VERSION=26.4.2
```
#### 2. **Kategorie-spezifische Versionen**
@@ -151,8 +156,8 @@ MEMBERS_SERVICE_PORT=8083
**Clients** (`docker/build-args/clients.env`):
```bash
NODE_VERSION=20.11.0
NGINX_VERSION=1.25-alpine
NODE_VERSION=22.21.0
NGINX_VERSION=1.28.0-alpine
WEB_APP_PORT=4000
DESKTOP_APP_VNC_PORT=5901
```
@@ -201,7 +206,7 @@ AUTH_SERVER_PORT=8087
./scripts/docker-versions-update.sh update grafana 11.3.0
# Keycloak auf neueste Version upgraden
./scripts/docker-versions-update.sh update keycloak 26.0.7
./scripts/docker-versions-update.sh update keycloak 26.4.2
# Alle Environment-Dateien synchronisieren
./scripts/docker-versions-update.sh sync
@@ -210,12 +215,13 @@ AUTH_SERVER_PORT=8087
## 🎯 Für AI-Assistenten: Architektur-Schnellreferenz
### Service-Kategorien
- **Infrastructure:** PostgreSQL, Redis, Keycloak, Kafka, Zookeeper, Consul
- **Infrastructure:** PostgresQL, Redis, Keycloak, Kafka, Zookeeper, Consul
- **Application:** API Gateway, Auth Server, Monitoring Server, Ping Service
- **Clients:** Web App (Port 3000), Desktop App
- **Monitoring:** Prometheus (9090), Grafana (3000), Zipkin, Nginx
### Wichtige Befehle
```bash
# Service-Status prüfen
docker-compose ps
@@ -232,6 +238,7 @@ docker-compose restart <service-name>
```
### Zentrale Konfigurationsdateien
- `docker/versions.toml` - Alle Versionen
- `docker-compose.yml` - Haupt-Services
- `docker-compose.clients.yml` - Client-Anwendungen
@@ -240,6 +247,7 @@ docker-compose restart <service-name>
---
**Navigation:**
- [master-guideline](../../master-guideline.md) – Hauptrichtlinie für das Projekt
- [Docker-Overview](./docker-overview.md) - Grundlagen und Philosophie
- [Docker-Development](./docker-development.md) - Entwicklungsworkflow
- [Docker-Production](./docker-production.md) - Production-Deployment
.junie/guidelines/technology-guides/docker/docker-development.md
+21 -9
View File
@@ -1,6 +1,7 @@
# Docker-Development Workflow
---
guideline_type: "technology"
scope: "docker-development"
audience: ["developers", "ai-assistants"]
@@ -8,10 +9,16 @@ last_updated: "2025-09-15"
dependencies: ["docker-overview.md", "docker-architecture.md"]
related_files: ["docker-compose.yml", "docker-compose.override.yml", "Makefile"]
ai_context: "Entwicklungs-Workflow, Debugging und lokale Entwicklungsumgebung mit Docker"
---
## 🛠️ Development-Workflow
> **📖 Hinweis:** Für einen allgemeinen Überblick über die Docker-Infrastruktur
> siehe [docker-overview](docker-overview.md).
> Für Details zur Container-Architektur siehe [docker-architecture](docker-architecture.md).
> Für Production-Deployment siehe [docker-production](docker-production.md).
### Schnellstart-Befehle
```bash
@@ -116,15 +123,16 @@ curl -s http://localhost:8080/actuator/health | jq
### Häufige Entwicklungsaufgaben
| Aufgabe | Befehl | Beschreibung |
|---------|---------|--------------|
| Umgebung starten | `make dev-up` | Alle Services für Development |
| Service debuggen | `docker-compose exec <service> sh` | Shell im Container |
| Logs verfolgen | `docker-compose logs -f <service>` | Live-Logs anzeigen |
| Service neu bauen | `make service-build SERVICE=<name>` | Einzelnen Service rebuilden |
| Health-Check | `curl localhost:<port>/actuator/health` | Service-Status prüfen |
| Aufgabe | Befehl | Beschreibung |
|-------------------|-----------------------------------------|-------------------------------|
| Umgebung starten | `make dev-up` | Alle Services für Development |
| Service debuggen | `docker-compose exec <service> sh` | Shell im Container |
| Logs verfolgen | `docker-compose logs -f <service>` | Live-Logs anzeigen |
| Service neu bauen | `make service-build SERVICE=<name>` | Einzelnen Service rebuilden |
| Health-Check | `curl localhost:<port>/actuator/health` | Service-Status prüfen |
### Development-URLs
- **Grafana:** http://localhost:3000 (admin/admin)
- **Prometheus:** http://localhost:9090
- **API Gateway:** http://localhost:8080
@@ -132,6 +140,7 @@ curl -s http://localhost:8080/actuator/health | jq
- **Keycloak:** http://localhost:8180
### Debug-Ports
- **Spring-Services:** 5005 (Standard Java Debug)
- **Web-App:** Hot-Reload über Volume-Mapping
- **Client-Apps:** Port 4000 (Web), 5901 (Desktop VNC)
@@ -139,6 +148,7 @@ curl -s http://localhost:8080/actuator/health | jq
### Troubleshooting Development
#### Container startet nicht
```bash
# Container-Status prüfen
docker-compose ps
@@ -154,6 +164,7 @@ docker-compose build --no-cache <service-name>
```
#### Port-Konflikte
```bash
# Ports prüfen
netstat -tulpn | grep :<port>
@@ -163,6 +174,7 @@ docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d
```
#### Volume-Probleme
```bash
# Volumes prüfen
docker volume ls
@@ -177,5 +189,5 @@ docker-compose exec <service> ls -la /path/to/volume
- [Docker-Overview](./docker-overview.md) - Grundlagen und Philosophie
- [Docker-Architecture](./docker-architecture.md) - Container-Services und Struktur
- [Docker-Production](./docker-production.md) - Production-Deployment
- [Docker-Monitoring](./docker-monitoring.md) - Observability
- [Docker-Troubleshooting](./docker-troubleshooting.md) - Problemlösung
- [docker-monitoring](./docker-monitoring.md) - Observability
- [docker-troubleshooting](./docker-troubleshooting.md) - Problemlösung
.junie/guidelines/technology-guides/docker/docker-monitoring.md
+24 -19
View File
@@ -1,6 +1,7 @@
# Docker-Monitoring und Observability
---
guideline_type: "technology"
scope: "docker-monitoring"
audience: ["developers", "devops", "ai-assistants"]
@@ -8,6 +9,7 @@ last_updated: "2025-09-15"
dependencies: ["docker-overview.md", "docker-architecture.md"]
related_files: ["docker-compose.yml", "config/monitoring/*", "config/grafana/*", "config/prometheus/*"]
ai_context: "Monitoring-Setup, Prometheus-Metriken, Grafana-Dashboards, Health-Checks und Log-Aggregation"
---
## 📊 Monitoring und Observability
@@ -44,13 +46,13 @@ labels:
### Health Check Matrix
| Service | Endpoint | Erwartung | Timeout |
|---------|----------|-----------|---------|
| API Gateway | `/actuator/health` | `{"status":"UP"}` | 15s |
| Ping Service | `/actuator/health/readiness` | HTTP 200 | 3s |
| PostgreSQL | `pg_isready` | Connection OK | 5s |
| Redis | `redis-cli ping` | PONG | 5s |
| Keycloak | `/health/ready` | HTTP 200 | 5s |
| Service | Endpoint | Erwartung | Timeout |
|--------------|------------------------------|-------------------|---------|
| API Gateway | `/actuator/health` | `{"status":"UP"}` | 15s |
| Ping Service | `/actuator/health/readiness` | HTTP 200 | 3s |
| PostgreSQL | `pg_isready` | Connection OK | 5s |
| Redis | `redis-cli ping` | PONG | 5s |
| Keycloak | `/health/ready` | HTTP 200 | 5s |
### Log Aggregation
@@ -65,6 +67,7 @@ docker-compose logs --follow --tail=100 api-gateway | jq -r '.message'
## 🎯 AI-Assistenten: Monitoring-Schnellreferenz
### Monitoring-URLs
- **Grafana Dashboard:** http://localhost:3000 (admin/admin)
- **Prometheus Targets:** http://localhost:9090/targets
- **Prometheus Metrics:** http://localhost:9090/metrics
@@ -72,13 +75,13 @@ docker-compose logs --follow --tail=100 api-gateway | jq -r '.message'
### Wichtige Metrics
| Metric-Typ | Beispiel | Beschreibung |
|------------|----------|--------------|
| JVM Memory | `jvm_memory_used_bytes` | Speicherverbrauch Java-Services |
| HTTP Requests | `http_requests_total` | API-Request-Zähler |
| Database Connections | `hikaricp_connections` | Pool-Verbindungen |
| Kafka Lag | `kafka_consumer_lag` | Consumer-Verzögerung |
| Custom Business | `meldestelle_registrations_total` | Fachliche KPIs |
| Metric-Typ | Beispiel | Beschreibung |
|----------------------|-----------------------------------|---------------------------------|
| JVM Memory | `jvm_memory_used_bytes` | Speicherverbrauch Java-Services |
| HTTP Requests | `http_requests_total` | API-Request-Zähler |
| Database Connections | `hikaricp_connections` | Pool-Verbindungen |
| Kafka Lag | `kafka_consumer_lag` | Consumer-Verzögerung |
| Custom Business | `meldestelle_registrations_total` | Fachliche KPIs |
### Health-Check Befehle
@@ -115,6 +118,7 @@ docker-compose logs api-gateway | grep -i "took\|duration\|time"
### Dashboard-Setup
#### Infrastructure-Dashboard
```json
{
"dashboard": {
@@ -142,6 +146,7 @@ docker-compose logs api-gateway | grep -i "took\|duration\|time"
```
#### Application-Dashboard
```json
{
"dashboard": {
@@ -245,8 +250,8 @@ scrape_configs:
---
**Navigation:**
- [Docker-Overview](./docker-overview.md) - Grundlagen und Philosophie
- [Docker-Architecture](./docker-architecture.md) - Container-Services und Struktur
- [Docker-Development](./docker-development.md) - Entwicklungsworkflow
- [Docker-Production](./docker-production.md) - Production-Deployment
- [Docker-Troubleshooting](./docker-troubleshooting.md) - Problemlösung
- [docker-overview](./docker-overview.md) - Grundlagen und Philosophie
- [docker-architecture](./docker-architecture.md) - Container-Services und Struktur
- [docker-development](./docker-development.md) - Entwicklungsworkflow
- [docker-production](./docker-production.md) - Production-Deployment
- [docker-troubleshooting](./docker-troubleshooting.md) - Problemlösung
.junie/guidelines/technology-guides/docker/docker-overview.md
+11 -5
View File
@@ -1,6 +1,7 @@
# Docker-Overview und Philosophie
---
guideline_type: "technology"
scope: "docker-overview"
audience: ["developers", "ai-assistants", "devops"]
@@ -8,6 +9,7 @@ last_updated: "2025-09-15"
dependencies: ["master-guideline.md"]
related_files: ["docker-compose.yml", "docker/versions.toml"]
ai_context: "Docker-Philosophie und allgemeine Prinzipien für das Meldestelle-Projekt"
---
## 🚀 Überblick und Philosophie
@@ -29,6 +31,7 @@ Das Meldestelle-Projekt implementiert eine **moderne, sicherheitsorientierte Con
> - Monitoring läuft unter `http://localhost:3001` (Grafana)
### Zentrale Dateien für AI-Referenz
- `docker/versions.toml` - Single Source of Truth für alle Versionen
- `docker-compose.yml` - Haupt-Service-Orchestrierung
- `scripts/docker-versions-update.sh` - Automatische Version-Updates
@@ -37,27 +40,30 @@ Das Meldestelle-Projekt implementiert eine **moderne, sicherheitsorientierte Con
## 📋 Docker-Guidelines Navigation
Für spezifische Docker-Themen siehe:
- [Docker-Architektur](./docker-architecture.md) - Container-Services und Struktur
- [Docker-Development](./docker-development.md) - Entwicklungsworkflow
- [Docker-Production](./docker-production.md) - Production-Deployment
- [Docker-Monitoring](./docker-monitoring.md) - Observability und Überwachung
- [Docker-Troubleshooting](./docker-troubleshooting.md) - Problemlösung
- [docker-architecture](./docker-architecture.md) - Container-Services und Struktur
- [docker-development](./docker-development.md) - Entwicklungsworkflow
- [docker-production](./docker-production.md) - Production-Deployment
- [docker-monitoring](./docker-monitoring.md) - Observability und Überwachung
- [docker-troubleshooting](./docker-troubleshooting.md) - Problemlösung
## Grundprinzipien
### Sicherheitsaspekte
- **Non-Root-Container**: Alle Container laufen mit dediziertem User
- **Minimale Base-Images**: Verwendung schlanker Images (Alpine, Distroless)
- **Security-Scans**: Regelmäßige Vulnerability-Checks
- **Network-Segmentierung**: Isolierte Docker-Networks
### Performance-Optimierung
- **Multi-Stage-Builds**: Schlanke Production-Images
- **Layer-Caching**: Optimale Build-Performance
- **Resource-Limits**: Definierte CPU/Memory-Constraints
- **Health-Checks**: Proaktive Service-Überwachung
### Wartbarkeit
- **Standardisierte Templates**: Konsistente Dockerfile-Struktur
- **Zentrale Konfiguration**: Environment-basierte Konfiguration
- **Dokumentation**: Umfassende README-Dateien pro Service
.junie/guidelines/technology-guides/docker/docker-production.md
+16 -12
View File
@@ -1,6 +1,7 @@
# Docker-Production Deployment
---
guideline_type: "technology"
scope: "docker-production"
audience: ["developers", "devops", "ai-assistants"]
@@ -8,6 +9,7 @@ last_updated: "2025-09-15"
dependencies: ["docker-overview.md", "docker-architecture.md"]
related_files: ["docker-compose.yml", "config/nginx/nginx.prod.conf", "config/ssl/*"]
ai_context: "Production-Deployment, Security-Hardening, SSL/TLS-Konfiguration und Ressourcenverwaltung"
---
## 🚀 Production-Deployment
@@ -136,12 +138,14 @@ services:
## 🎯 AI-Assistenten: Production-Schnellreferenz
### Production-Domains
- **API:** api.meldestelle.at (HTTPS)
- **Auth:** auth.meldestelle.at (HTTPS)
- **Monitoring:** monitor.meldestelle.at (HTTPS)
- **Metrics:** metrics.meldestelle.at (HTTPS)
### Security-Checkliste
- [ ] SSL/TLS-Zertifikate installiert und gültig
- [ ] Alle Passwörter mit `openssl rand -base64 32` generiert
- [ ] Nginx Security Headers konfiguriert
@@ -151,13 +155,13 @@ services:
### Production-Befehle
| Aufgabe | Befehl | Beschreibung |
|---------|---------|--------------|
| Zertifikat erneuern | `certbot renew` | Let's Encrypt Zertifikate |
| SSL-Status prüfen | `openssl s_client -connect api.meldestelle.at:443` | SSL-Verbindung testen |
| Resource-Usage | `docker stats` | Container-Ressourcen |
| Security-Scan | `docker scan <image>` | Vulnerability Check |
| Log-Rotation | `docker system prune -f` | Alte Logs bereinigen |
| Aufgabe | Befehl | Beschreibung |
|---------------------|----------------------------------------------------|---------------------------|
| Zertifikat erneuern | `certbot renew` | Let's Encrypt Zertifikate |
| SSL-Status prüfen | `openssl s_client -connect api.meldestelle.at:443` | SSL-Verbindung testen |
| Resource-Usage | `docker stats` | Container-Ressourcen |
| Security-Scan | `docker scan <image>` | Vulnerability Check |
| Log-Rotation | `docker system prune -f` | Alte Logs bereinigen |
### Environment-Variablen Validierung
@@ -219,8 +223,8 @@ curl -s https://monitor.meldestelle.at/api/health | jq '.database'
---
**Navigation:**
- [Docker-Overview](./docker-overview.md) - Grundlagen und Philosophie
- [Docker-Architecture](./docker-architecture.md) - Container-Services und Struktur
- [Docker-Development](./docker-development.md) - Entwicklungsworkflow
- [Docker-Monitoring](./docker-monitoring.md) - Observability
- [Docker-Troubleshooting](./docker-troubleshooting.md) - Problemlösung
- [docker-overview](./docker-overview.md) - Grundlagen und Philosophie
- [docker-architecture](./docker-architecture.md) - Container-Services und Struktur
- [docker-development](./docker-development.md) - Entwicklungsworkflow
- [docker-monitoring](./docker-monitoring.md) - Observability
- [docker-troubleshooting](./docker-troubleshooting.md) - Problemlösung
.junie/guidelines/technology-guides/docker/docker-troubleshooting.md
+17 -12
View File
@@ -1,6 +1,7 @@
# Docker-Troubleshooting und Best Practices
---
guideline_type: "technology"
scope: "docker-troubleshooting"
audience: ["developers", "devops", "ai-assistants"]
@@ -8,6 +9,7 @@ last_updated: "2025-09-15"
dependencies: ["docker-overview.md", "docker-architecture.md", "docker-development.md"]
related_files: ["docker-compose.yml", "scripts/validate-docker-consistency.sh", "scripts/docker-versions-update.sh"]
ai_context: "Fehlerbehebung häufiger Docker-Probleme, Debug-Kommandos und umfassende Best Practices"
---
## 🔧 Troubleshooting
@@ -85,29 +87,32 @@ docker-compose logs -f --tail=50 SERVICE_NAME
### Häufige Befehle
| Problem | Befehl | Beschreibung |
|---------|---------|--------------|
| Port belegt | `netstat -tulpn \| grep :<port>` | Port-Nutzung prüfen |
| Service startet nicht | `docker-compose logs <service>` | Service-Logs anzeigen |
| Container hängt | `docker stats` | Ressourcenverbrauch |
| DNS-Probleme | `docker-compose exec <service> nslookup <target>` | DNS-Resolution testen |
| Disk voll | `docker system prune -a --volumes` | Cleanup durchführen |
| Problem | Befehl | Beschreibung |
|-----------------------|---------------------------------------------------|-----------------------|
| Port belegt | `netstat -tulpn \| grep :<port>` | Port-Nutzung prüfen |
| Service startet nicht | `docker-compose logs <service>` | Service-Logs anzeigen |
| Container hängt | `docker stats` | Ressourcenverbrauch |
| DNS-Probleme | `docker-compose exec <service> nslookup <target>` | DNS-Resolution testen |
| Disk voll | `docker system prune -a --volumes` | Cleanup durchführen |
### Debug-Workflows
#### Service startet nicht
1. `docker-compose ps` - Status prüfen
2. `docker-compose logs <service>` - Logs analysieren
3. `docker-compose exec <service> sh` - Container inspizieren
4. Health-Check-Endpoint testen
#### Performance-Probleme
1. `docker stats` - Ressourcenverbrauch
2. `docker-compose top` - Prozess-Übersicht
3. JVM-Parameter optimieren
4. Resource-Limits anpassen
#### Netzwerk-Probleme
1. `docker network ls` - Netzwerke auflisten
2. `docker-compose exec <service> ping <target>` - Connectivity testen
3. Consul Service-Discovery prüfen
@@ -292,8 +297,8 @@ docker-compose up -d && make test
---
**Navigation:**
- [Docker-Overview](./docker-overview.md) - Grundlagen und Philosophie
- [Docker-Architecture](./docker-architecture.md) - Container-Services und Struktur
- [Docker-Development](./docker-development.md) - Entwicklungsworkflow
- [Docker-Production](./docker-production.md) - Production-Deployment
- [Docker-Monitoring](./docker-monitoring.md) - Observability
- [docker-overview](./docker-overview.md) - Grundlagen und Philosophie
- [docker-architecture](./docker-architecture.md) - Container-Services und Struktur
- [docker-development](./docker-development.md) - Entwicklungsworkflow
- [docker-production](./docker-production.md) - Production-Deployment
- [docker-monitoring](./docker-monitoring.md) - Observability
.junie/guidelines/technology-guides/web-app-guideline.md
+26 -8
View File
@@ -1,6 +1,7 @@
# Client-App-Richtlinie (Compose Multiplatform)
---
guideline_type: "technology"
scope: "web-app-multiplatform"
audience: ["developers", "ai-assistants", "frontend-developers"]
@@ -8,6 +9,7 @@ last_updated: "2025-09-15"
dependencies: ["master-guideline.md", "project-standards/architecture-principles.md"]
related_files: ["client/build.gradle.kts", "client/src/commonMain/", "client/src/wasmJsMain/", "client/src/jvmMain/"]
ai_context: "Compose Multiplatform-Entwicklung, MVVM-Pattern, KMP-Architektur, Desktop- und Web-Client-Entwicklung"
---
## 1. Einleitung
@@ -25,11 +27,11 @@ Das Hauptziel ist die maximale Wiederverwendung von Code zwischen den Desktop- u
## 2. Grundprinzipien
### Deklarative UI mit Composables
### Deklarative UI mit Composable
Die gesamte Benutzeroberfläche wird als Baum von `@Composable`-Funktionen deklariert. Dies ist derselbe Ansatz, der auch bei Jetpack Compose für Android verwendet wird.
- **Zustandslosigkeit:** Composables sollten bevorzugt zustandslos sein. Sie erhalten Daten als Parameter und geben Ereignisse über Lambda-Funktionen (Callbacks) nach oben weiter.
- **Zustandslosigkeit:** Composable sollten bevorzugt zustandslos sein. Sie erhalten Daten als Parameter und geben Ereignisse über Lambda-Funktionen (Callbacks) nach oben weiter.
- **Wiederverwendbarkeit:** Erstellen Sie kleine, spezialisierte und wiederverwendbare Composables. Vermeiden Sie monolithische UI-Funktionen.
- **Vorschau:** Nutzen Sie `@Preview`-Annotationen (sofern von der IDE unterstützt), um UI-Komponenten isoliert zu entwickeln und zu visualisieren.
@@ -46,15 +48,18 @@ Der UI-Zustand (State) wird explizit verwaltet.
Das Styling erfolgt plattformspezifisch, aber mit gemeinsamen Prinzipien:
#### Gemeinsame Styling-Prinzipien (commonMain)
- **Compose Material Design**: Nutzen Sie Material3-Komponenten und Theming für konsistente UI.
- **Gemeinsame Designsystem**: Definieren Sie gemeinsame Farben, Typografie und Spacing in `commonMain`.
- **Gemeinsames Designsystem**: Definieren Sie gemeinsame Farben, Typografie und Spacing in `commonMain`.
- **Responsive Design**: Berücksichtigen Sie verschiedene Bildschirmgrößen (Desktop-Fenster vs. Browser-Viewports).
#### Web-spezifisches Styling (wasmJsMain)
- **CSS-Integration**: Web-spezifische Styling-Anforderungen können über CSS in den Resources behandelt werden.
- **Browser-Kompatibilität**: Berücksichtigen Sie Web-spezifische Rendering-Unterschiede.
#### Desktop-spezifisches Styling (jvmMain)
- **Native Look & Feel**: Desktop-Anwendungen sollten sich nativ anfühlen.
- **Fenster-Management**: Berücksichtigen Sie Desktop-spezifische UI-Patterns (Menüleisten, etc.).
@@ -71,12 +76,14 @@ fun AppTheme(content: @Composable () -> Unit) {
```
### Navigation
Die Navigation wird plattformunabhängig in `commonMain` implementiert:
- **ViewModel-basierte Navigation**: Ein `StateFlow` oder `mutableState` im ViewModel repräsentiert die aktuelle Route/Screen.
- **Gemeinsamer Router**: Ein zentraler `Router`-Composable in `commonMain` reagiert auf Zustandsänderungen und rendert den entsprechenden Screen.
- **Plattformspezifische Einstiegspunkte**: Desktop und Web haben separate `main.kt`-Dateien, aber nutzen denselben gemeinsamen App-Composable.
## 3. Projekt- und Code-Struktur
Die Codebasis ist klar zwischen plattformunabhängiger Logik (`commonMain`) und plattformspezifischer Implementation (`jvmMain`, `wasmJsMain`) getrennt.
### Source Sets
@@ -89,12 +96,12 @@ Die Codebasis ist klar zwischen plattformunabhängiger Logik (`commonMain`) und
- **`client/src/jvmMain`** (Desktop-Plattform):
- **`main.kt`**: Der Einstiegspunkt der Desktop-Anwendung.
- **Desktop-spezifische Code**: Plattformspezifische Implementierungen und Integrationen.
- **Desktop-spezifischer Code**: Plattformspezifische Implementierungen und Integrationen.
- **Desktop Dependencies**: `compose.desktop.currentOs`, Coroutines für Swing.
- **`client/src/wasmJsMain`** (Web-Plattform):
- **`main.kt`**: Der Einstiegspunkt der Web-Anwendung (WebAssembly).
- **Web-spezifische Code**: Browser-spezifische Implementierungen.
- **Web-spezifischer Code**: Browser-spezifische Implementierungen.
- **Platform-spezifische Implementierungen**: Web-APIs und Browser-Integrationen.
- **`client/src/wasmJsMain/resources`**:
@@ -102,6 +109,7 @@ Die Codebasis ist klar zwischen plattformunabhängiger Logik (`commonMain`) und
- **Statische Assets**: Bilder, Schriftarten und andere statische Dateien für die Web-Version.
### Shared Module Integration
- **`core/commonMain`** (oder äquivalente `shared`-Module):
- **Repositories/Services**: Code für den Datenzugriff (z.B. Ktor-HTTP-Clients zum Aufrufen des Backends).
- **Business-Logik**: Plattformunabhängige Geschäftslogik, die von allen Client-Plattformen genutzt wird.
@@ -109,6 +117,7 @@ Die Codebasis ist klar zwischen plattformunabhängiger Logik (`commonMain`) und
## 4. Entwicklung und Ausführung
### Desktop-Entwicklung
Für die Desktop-Anwendung stehen folgende Gradle-Tasks zur Verfügung:
```shell script
@@ -123,6 +132,7 @@ Für die Desktop-Anwendung stehen folgende Gradle-Tasks zur Verfügung:
```
### Web-Entwicklung mit Hot-Reload
Für die Web-Anwendung mit automatischer Neuladung bei Änderungen:
```shell script
@@ -131,6 +141,7 @@ Für die Web-Anwendung mit automatischer Neuladung bei Änderungen:
```
#### Docker-Setup für Web-Entwicklung
Das Docker-Setup ist spezifisch für die Web-Entwicklung konfiguriert (wie in `README-DOCKER.md` beschrieben):
```shell script
@@ -144,26 +155,31 @@ Der Dienst ist dann unter dem in der `docker-compose.clients.yml` konfigurierten
### Produktions-Builds
#### Desktop-Distribution
```shell script
# Erstellt native Distributionen für alle konfigurierten Plattformen
./gradlew :client:packageDistributionForCurrentOS
```
#### Web-Distribution
```shell script
# Erstellt optimierte WebAssembly-Artefakte für die Produktion
./gradlew :client:wasmJsBrowserDistribution
```
Das Docker-Image für die Web-Produktion (`Dockerfile` im `client`-Verzeichnis) sollte den `wasmJsBrowserDistribution`-Task nutzen, um die finalen Artefakte zu bauen.
## 5. Plattformspezifische Besonderheiten
### Desktop (jvmMain)
- **Fenster-Management**: Nutzen Sie Compose Desktop-APIs für Fensteroperationen.
- **System-Integration**: Zugriff auf Desktop-spezifische Features (Dateisystem, Notifications, etc.).
- **Performance**: Desktop-Apps können mehr Ressourcen nutzen als Web-Apps.
### Web (wasmJsMain)
- **Browser-APIs**: Zugriff auf Web-APIs erfolgt über `external`-Deklarationen.
- **Bundle-Size**: Achten Sie auf die Größe der WebAssembly-Bundles für optimale Ladezeiten.
- **SEO und Accessibility**: Berücksichtigen Sie Web-spezifische Anforderungen.
@@ -171,17 +187,20 @@ Das Docker-Image für die Web-Produktion (`Dockerfile` im `client`-Verzeichnis)
## 6. Dos and Don'ts
### Multiplatform Best Practices
- **DO**: Die gesamte UI-Logik (State-Management, Datenabruf, Validierung) in `commonMain` implementieren.
- **DO**: Kleine, wiederverwendbare und zustandslose Composables in `commonMain` erstellen.
- **DO**: Kleine wiederverwendbare und zustandslose Composable in `commonMain` erstellen.
- **DO**: Material3 und gemeinsames Theming für konsistente UI zwischen Plattformen verwenden.
- **DO**: Events von der UI über Lambda-Funktionen an die ViewModels in `commonMain` weiterleiten.
- **DO**: Plattformspezifische Features über `expect`/`actual`-Mechanismus abstrahieren.
### Platform-Specific Guidelines
- **DO** (Desktop): Native Look & Feel und Desktop-UI-Patterns verwenden.
- **DO** (Web): Web-Standards und Accessibility-Guidelines befolgen.
### Don'ts
- **DON'T**: Geschäftslogik, API-Aufrufe oder komplexe Zustandsmanipulationen direkt in `@Composable`-Funktionen schreiben.
- **DON'T**: Plattformspezifische Code direkt in `commonMain` verwenden ohne `expect`/`actual`.
- **DON'T** (Web): Den DOM direkt manipulieren. Compose Multiplatform verwaltet das Rendering. Falls Interaktion mit externen Bibliotheken nötig ist, nutzen Sie `external`-Mechanismen sauber gekapselt.
@@ -190,9 +209,8 @@ Das Docker-Image für die Web-Produktion (`Dockerfile` im `client`-Verzeichnis)
---
**Navigation:**
- [Master-Guideline](../master-guideline.md) - Übergeordnete Projektrichtlinien
- [Master-Guideline](../master-guideline.md) - übergeordnete Projektrichtlinien
- [Architecture-Principles](../project-standards/architecture-principles.md) - Architektur-Grundsätze
- [Coding-Standards](../project-standards/coding-standards.md) - Code-Qualitätsstandards
- [Testing-Standards](../project-standards/testing-standards.md) - Test-Qualitätssicherung
- [Trace-Bullet-Guideline](../process-guides/trace-bullet-guideline.md) - Entwicklungszyklus