204 lines
5.0 KiB
Markdown
204 lines
5.0 KiB
Markdown
# 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".
|