quarkus projektordner umbenannt

2026-04-09 08:06:13 +02:00
parent a37829ccd3
commit 9f98c44a18
28 changed files with 0 additions and 0 deletions
--- a/quarkus-automaton/SETUP.md
+++ b/quarkus-automaton/SETUP.md
@@ -0,0 +1,203 @@
+# Setup — Dateieingang Service
+
+Alle Befehle werden in **WSL** ausgeführt.
+Maven wird über den enthaltenen Maven Wrapper (`./mvnw`) aufgerufen — kein separates Maven nötig.
+
+---
+
+## Voraussetzungen
+
+### Java 25 (via SDKMAN)
+
+```bash
+curl -s "https://get.sdkman.io" | bash
+source "$HOME/.sdkman/bin/sdkman-init.sh"
+sdk install java 25-tem
+sdk default java 25-tem
+java -version
+```
+
+### Maven Wrapper
+
+Das Projekt verwendet den Maven Wrapper (`./mvnw`), der bereits im Projekt enthalten ist.
+Keine separate Maven-Installation notwendig.
+
+Das initiale Einrichten des Maven Wrappers wurde gemacht, indem (1.) Maven manuell installiert
+wurde und (2.) das Maven Goal `wrapper` ausgeführt wurde:
+
+1. `sdk install maven`
+2. `mvn -N wrapper:wrapper -Dmaven=3.9.14`
+
+> **Hinweis:** SDKMAN fixiert die Java-Version, `mvnw` fixiert die Maven-Version —
+> beide zusammen stellen sicher, dass alle Entwickler identische Builds erzeugen.
+
+---
+
+## Projekt bauen
+
+```bash
+# Bauen (inkl. Tests)
+./mvnw package
+
+# Bauen ohne Tests
+./mvnw package -DskipTests
+
+# Bauen + Tests ausführen
+./mvnw verify
+```
+
+Build-Artefakt: `target/quarkus-app/`
+
+---
+
+## Dev-Server starten
+
+### Standard (ohne Observability-Stack)
+
+```bash
+./mvnw quarkus:dev
+```
+
+Quarkus Dev UI erreichbar unter: http://localhost:8080/q/dev/
+REST Endpoint erreichbar unter: `POST http://localhost:8080/api/process-incoming`
+
+### Mit Grafana / LGTM-Stack
+
+```bash
+./mvnw quarkus:dev -Pgrafana
+```
+
+Startet automatisch via Dev Services:
+- **Loki** — Log-Aggregation
+- **Grafana** — http://localhost:3000 (admin/admin)
+- **Tempo** — Distributed Tracing
+- **Mimir** — Metriken
+
+Logs werden via OTLP direkt an Loki geschickt — kein Promtail, kein manuelles Setup.
+
+> **Hinweis:** Das `-Pgrafana`-Profil ist nur für die Entwicklung gedacht.
+> In Produktion wird ein externer OTLP-Collector (z.B. Grafana Alloy) verwendet.
+
+---
+
+## Umgebungsvariablen
+
+Quarkus lädt eine `.env`-Datei im Projektverzeichnis **automatisch** — kein `source` nötig.
+Format: `KEY=VALUE` ohne `export`.
+
+```properties
+# API-Absicherung des REST Endpoints
+GALABAU_API_KEY=dev-key
+
+# SFTP
+GALABAU_SFTP_HOST=sftp.lieferant.de
+GALABAU_SFTP_USERNAME=sftpuser
+GALABAU_SFTP_PASSWORD=<sftp-passwort>
+# GALABAU_SFTP_HOST_KEY_FINGERPRINT=SHA256:...
+
+# OCI Object Storage Credentials (erst nötig wenn OCI-Stub durch echte Implementierung ersetzt)
+# OCI_TENANCY_ID=ocid1.tenancy.oc1..xxx
+# OCI_USER_ID=ocid1.user.oc1..xxx
+# OCI_FINGERPRINT=aa:bb:cc:dd:...
+# OCI_PRIVATE_KEY_PATH=~/.oci/oci_api_key.pem
+
+# ORDS (erst nötig wenn ORDS-Stub durch echte Implementierung ersetzt)
+# GALABAU_ORDS_API_KEY=<ords-api-key>
+```
+
+> **.env niemals committen** — in `.gitignore` eintragen.
+
+---
+
+## Projektstruktur
+
+```
+src/main/java/de/galabau/dateieingang/
+├── api/        # FileProcessingResource — REST Endpoint (/api/process-incoming)
+├── sftp/       # SftpService, SftpConfig — SSHJ: list, download, rename
+├── zip/        # ZipExtractionService — Apache Commons Compress
+├── oci/        # OciUploadService, OciConfig — OCI SDK, Marker-Handling
+├── ords/       # OrdsClient, OrdsNotificationService — MicroProfile REST Client
+├── pipeline/   # FileProcessingPipeline — Orchestrierung + Async
+├── model/      # ProcessingContext, FileEntry, OrdsRequest
+├── config/     # ApplicationConfig
+└── exception/  # SftpException, ZipException, OciException, OrdsException
+```
+
+---
+
+## Endpoint manuell aufrufen (Entwicklung)
+
+```bash
+curl -X POST http://localhost:8080/api/process-incoming \
+  -H "X-Api-Key: $GALABAU_API_KEY"
+```
+
+Erwartete Antwort: `HTTP 202 Accepted` (Pipeline läuft im Hintergrund)
+
+---
+
+## Nützliche Maven-Befehle
+
+```bash
+# Extension hinzufügen
+./mvnw quarkus:add-extension -Dextensions="smallrye-fault-tolerance"
+
+# Installierte Extensions anzeigen
+./mvnw quarkus:list-extensions
+
+# Dependency-Baum anzeigen
+./mvnw dependency:tree
+```
+
+---
+
+## Testen
+
+```bash
+# Unit-Tests
+./mvnw test
+
+# Integrationstests (benötigt laufende externe Services / Docker für Testcontainers)
+./mvnw verify
+```
+
+Für SFTP-Integrationstests wird Testcontainers mit `atmoz/sftp` verwendet —
+Docker muss lokal laufen.
+
+---
+
+## Debugging
+
+### Mit IntelliJ IDEA
+
+1. Projekt öffnen
+2. Java 25 als Projekt-SDK wählen
+3. Quarkus-Plugin installieren (falls nicht vorhanden)
+4. Dev-Server über `quarkus:dev` starten — Quarkus unterstützt Hot-Reload
+
+### Mit VS Code
+
+1. Quarkus-Plugin für VS Code installieren
+2. Projektverzeichnis öffnen
+3. Integrierte Debug-Funktionalität nutzen
+
+---
+
+## Deployment (Kubernetes / OCI)
+
+```bash
+# JAR bauen
+./mvnw package -DskipTests
+
+# Container-Image bauen (Quarkus JVM-Mode)
+./mvnw package -Dquarkus.container-image.build=true
+```
+
+Kubernetes Secrets für Credentials anlegen:
+- Skalare Werte (`OCI_TENANCY_ID`, `OCI_USER_ID`, `OCI_FINGERPRINT`, `GALABAU_API_KEY`, etc.)
+  → Kubernetes Secret → Env-Vars
+- OCI Private Key (PEM-Datei)
+  → Kubernetes Secret → Volume Mount unter `/etc/oci/private-key.pem`
+
+Siehe `docs/Plan.md` — Abschnitt "Deployment-Constraints".