gala-ki-spielwiese/quarkus-automaton/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)

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