gala-ki-spielwiese/agent-backend/SETUP.md

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)

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

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

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

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

Für lokale Entwicklung eine .env-Datei im Projektverzeichnis anlegen:

# API-Absicherung des REST Endpoints
export GALABAU_API_KEY=<lokaler-dev-key>

# SFTP
export GALABAU_SFTP_PASSWORD=<sftp-passwort>
# Alternativ (Public-Key-Auth):
# export SFTP_KEY_PASSPHRASE=<passphrase>

# OCI Object Storage Credentials
export OCI_TENANCY_ID=ocid1.tenancy.oc1..xxx
export OCI_USER_ID=ocid1.user.oc1..xxx
export OCI_FINGERPRINT=aa:bb:cc:dd:...
# Lokal: Pfad zur eigenen OCI Key-Datei
export OCI_PRIVATE_KEY_PATH=~/.oci/oci_api_key.pem
# In Produktion (Kubernetes): gemountetes Secret, z.B. /etc/oci/private-key.pem

# ORDS
export GALABAU_ORDS_API_KEY=<ords-api-key>

Importieren:

source .env

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

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

# 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

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

# 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".