geopilot ist ein benutzerfreundliches Tool für das Liefern und Validieren von Geodaten. Es ermöglicht das Hochladen von Geodaten in verschiedenen Formaten und überprüft sie auf Einhaltung geltender Standards. Anwender können ihre hochgeladenen und validierten Daten deklarieren um diese für die Weiterverarbeitung bereit zu stellen. Mit geopilot wird der Prozess der Geodatenverarbeitung für eine reibungslose und zuverlässige Datenübermittlung optimiert.

Folgende Komponenten müssen auf dem Entwicklungsrechner installiert sein:

✔️ Git
✔️ Docker
✔️ Visual Studio 2026 (Erweiterungen ASP.NET & web dev, Node.js development, Container dev tools)

Für die Formattierung wird ESLint verwendet. Dazu im Visual Studio unter Options/Text Editor/Javascript/Linting/General Enable ESLint auf true setzen, resp. im VS Code die ESLint-Extension installieren.

• Vor dem ersten Start oder bei Änderungen in den Packages muss in Geopilot.Frontend manuell npm install ausgeführt werden.

• Damit die Applikation mit HTTPS funktioniert, muss ein lokales dev-cert erstellt werden. Dieses wird durch das npm Script predev vor dem Start automatisch erstellt. Sollte dies nicht funktionieren, kann mit folgendem Befehl ein Zertifikat manuell erstellt und vertraut werden: dotnet dev-certs https --trust. HTTPS muss verwendet werden, damit die STAC-Urls korrekt funktionieren und so der STAC-Browser wie in einer produktiven Umgebung verwendet werden kann.

• Das Projekt kann mit dem Launch Profile "Development" gestartet werden.

Das Projekt unterstützt das Starten der Applikation mit Docker Compose, um einer produktiven Umgebung möglichst nahe zu kommen. Um HTTPS zu unterstützen, benötigt es ein vertrautes dev-cert sowie ein Export dessen im PEM-Format. Diese werden im docker-compose.yml korrekt geladen. Setup ist nachfolgend beschrieben. Die Applikation ist danach unter https://localhost:5173 erreichbar.

dotnet dev-certs https --trust
dotnet dev-certs https --export-path ".\certs\cert.pem" --no-password --format PEM
docker compose up -d

geopilot verwendet eine YAML-Konfigurationsdatei, um den Validierungs- und Lieferprozess als Pipeline zu definieren. Diese Datei beschreibt die verfügbaren Prozesse (z.B. INTERLIS-Validierung), deren Konfiguration sowie die Schritte, die bei einer Datenlieferung ausgeführt werden. Ein Beispiel befindet sich unter src/Geopilot.Api/PipelineDefinitions/basicPipeline_01.yaml.

Der Pfad zur Pipeline-Konfiguration kann auf zwei Arten festgelegt werden:

• Appsettings: In den Appsettings unter Pipeline:Definition (z.B. beim Betrieb ohne Docker).
• Umgebungsvariable: Über Pipeline__Definition (z.B. in der docker-compose.yml), welche den Wert aus den Appsettings überschreibt.

Beim Start mit Docker Compose wird die YAML-Datei als Volume in den Container gemountet und der Pfad per Umgebungsvariable gesetzt:

environment:
  Pipeline__Definition: /pipelines/pipelines.yaml
volumes:
  - ./src/Geopilot.Api/PipelineDefinitions/basicPipeline_01.yaml:/pipelines/pipelines.yaml:ro

Wichtig: Der Pfad in der Umgebungsvariable Pipeline__Definition und der Mount-Pfad in volumes müssen übereinstimmen. Bei einer Umbenennung oder Verschiebung der YAML-Datei müssen beide Stellen entsprechend angepasst werden.

Das Auth-Token wird als Cookie im Frontend gespeichert und über den Reverse Proxy (in vite.config.js) ans API zur Authentifizierung weitergegeben. Der STAC Browser ist über https://localhost:5173/browser erreichbar und das Cookie kann somit auch da zur Authentifizierung verwendet werden.

Das Debugging sollte nun sowohl für das Geopilot.Frontend in JavaScript als auch für Geopilot.Api in C# funtkionieren.

PgAdmin kann für eine Analyse der Datenbank verwendet werden und ist unter localhost:3001 verfügbar.

Die Cypress Tests können mit npm run cy oder npm run test gestartet werden. Sie werden zudem automatisch in der CI/CD Pipeline ausgeführt. Das Projekt ist mit Cypress Cloud konfiguriert, wodurch unter anderem die parallele Ausführung der End-to-End (E2E) Tests ermöglicht wird. Testergebnisse und Aufzeichnungen sind ebenfalls direkt in Cypress Cloud einsehbar, was die Identifikation und Behebung möglicher Fehler und Probleme erleichtert. Um die detaillierten Testergebnisse einzusehen und die E2E-Tests des Projekts zu debuggen, kann die Cypress Dashboard-Seite besucht werden.

Für das Monitoring im produktiven Betrieb steht unter https://<host>:<port>/health eine Health Check API zur Verfügung. Anhand der Antwort Healthy (HTTP Status Code 200), resp. Unhealthy (HTTP Status Code 503) kann der Status der Applikation bspw. mit cURL abgefragt werden.

curl -f https://<host>:<port>/health || exit 1;

Der Health Check ist auch im Docker Container integriert und kann ebenfalls über eine Shell abgefragt werden.

docker inspect --format='{{json .State.Health.Status}}' container_name

Ein neuer GitHub Pre-release wird bei jeder Änderung auf main automatisch erstellt. In diesem Kontext wird auch ein neues Docker Image mit dem Tag :edge erstellt und in die GitHub Container Registry (ghcr.io) gepusht. Der definitve Release erfolgt, indem die Checkbox Set as the latest release eines beliebigen Pre-releases gesetzt wird. In der Folge wird das entsprechende Docker Image in der ghcr.io Registry mit den Tags (bspw.: :v1.2.3 und :latest) ergänzt.

Fürs Login auf geopilot wird ein Identity Provider mit OpenID Connect (OIDC) vorausgesetzt. Der verwendete OAuth2 Flow ist Authorization Code Flow with Proof Key for Code Exchange (PKCE).

Zur Authentifizierung aus dem Frontend wird das ID-Token und aus dem Swagger UI das Access-Token verwendet. Dabei wird geprüft, dass das Token von der angegebenen Authority ausgestellt wurde (iss Claim) und für die Client-Id gültig ist (aud Claim). Zusätzlich werden folgende Claims im Token vorausgesetzt: sub, email und name. Diese werden beispielsweise bei den OIDC Scopes openid, profile und email mitgeliefert.

Als erlaubte Redirect URIs müssen für das Login aus dem Frontend https://<app-domain> und aus Swagger UI https://<app-domain>/swagger/oauth2-redirect.html angegeben werden. (Entwicklungsumgebung: https://localhost:5173 und https://localhost:7188/swagger/oauth2-redirect.html)

Abhängig vom Identity Provider wird die Audience (aud Claim) im Access-Token automatisch gesetzt, sofern ein passender Scope verwendet wird. Der benötigte Scope kann in den Appsettings under ApiServerScope gesetzt werden, um diesen im Swagger UI zur Auswahl anzuzeigen. Ohne diesem Scope wird das Access-Token möglicherweise ohne oder für eine andere Audience ausgestellt.

In der Entwicklungsumgebung wird die Audience stattdessen mit einem Keycloak Protocol Mapper festgelegt.

Folgende Appsettings können definiert werden (Beispiel aus appsettings.Development.json für die Entwicklungsumgebung):

"Auth": {
    // General auth options
    "Authority": "http://localhost:4011/realms/geopilot", // Token issuer (required)
    "ClientAudience": "geopilot-client", // ID_Token audience (required)
    "ApiAudience": "geopilot-api", // Access_Token audience (required)
    "FullScope": "openid profile email geopilot.api" // Full scope a client application needs to send as to configure access and id tokens correctly

    // Swagger UI auth options
    "ApiOrigin": "https://localhost:7188", // Swagger UI origin (required)
    "AuthorizationUrl": "http://localhost:4011/realms/geopilot/protocol/openid-connect/auth", // OAuth2 login URL
    "TokenUrl": "http://localhost:4011/realms/geopilot/protocol/openid-connect/token", // OAuth2 token URL
    "ApiServerScope": "<custom app scope>"
}

Falls die AuthorizationUrl und/oder TokenUrl nicht definiert sind, wird im Swagger UI die OpenID Konfiguration der Authority (<authority-url>/.well-known/openid-configuration) geladen und alle vom Identity Provider unterstützten Flows angezeigt.

geopilot kann optional mit einem Cloud-Upload-Flow betrieben werden, bei dem Dateien über Presigned URLs direkt in einen Object Storage hochgeladen werden. Die Standardimplementierung verwendet Azure Blob Storage (bzw. Azurite als Emulator für die Entwicklung). Für die Virenprüfung wird optional ClamAV unterstützt.

Beide Features sind standardmässig deaktiviert. Ohne Konfiguration wird ausschliesslich der klassische direkte Upload verwendet.

Azurite und ClamAV sind in der docker-compose.yml vorkonfiguriert. Azurite verwendet die gleichen HTTPS-Zertifikate wie die Applikation. ClamAV braucht beim ersten Start ca. 1–2 Minuten für Virendefinitionen.

docker compose up -d azurite clamav

"CloudStorage": {
    "Enabled": true,
    "ConnectionString": "...",
    "BucketName": "uploads",
    "AutoCreateContainer": false, // Nur für Entwicklung auf true setzen
    "AllowedOrigins": ["https://localhost:5173"] // CORS für Presigned-URL-Uploads
},
"ClamAV": {
    "Enabled": true,
    "Host": "localhost",
    "Port": 3310
}

Weitere Einstellungen (MaxFileSizeMB, MaxFilesPerJob, MaxJobSizeMB, MaxGlobalActiveSizeMB, MaxActiveJobs, PresignedUrlExpiryMinutes, CleanupAgeHours, CleanupIntervalMinutes, RateLimitRequests, RateLimitWindowMinutes) werden in appsettings.json konfiguriert. Veraltete, verwaiste und überdimensionierte Uploads werden automatisch durch den CloudCleanupService bereinigt.

• Cloud Storage deaktiviert (Standard): Nur der direkte Upload (/api/v1/validation) ist verfügbar. ClamAV-Einstellungen werden ignoriert.
• Cloud Storage aktiviert, ClamAV deaktiviert: Cloud-Upload funktioniert ohne Virenprüfung. Pro Upload wird eine Warnung geloggt.
• Cloud Storage aktiviert, ClamAV aktiviert: Cloud-Upload mit Virenprüfung vor der Validierung.