geopilot

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.

Einrichten der Entwicklungsumgebung

Folgende Komponenten müssen auf dem Entwicklungsrechner installiert sein:

✔️ Git
✔️ Docker
✔️ Visual Studio 2022 (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.

Damit die Launch Settings für docker-compose korrekt geladen werden, mit Rechtsklick auf dem Projekt Manage Docker Compose Launch Settings öffnen, warten bis alle Services geladen sind und dann speichern.

Starten der Applikation 🚀

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

URLs Entwicklungsumgebung 🔗

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 auch über https://localhost:5173/browser erreichbar und das Cookie kann somit auch da zur Authentifizierung verwendet werden.

Debugging 🪲

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.

Cypress Tests

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.

Health Check API

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

Neue Version erstellen

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.

Authentifizierung

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

Token

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.

Redirect URIs

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)

Swagger UI

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

Appsettings

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)
    "ClientId": "geopilot-client", // Token audience (required)

    // 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
    "ApiScope": "<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.