Konfiguration

Edge Connector Configuration

Der Edge Connector wird über eine Kombination aus einer config.json-Datei und Umgebungsvariablen konfiguriert. Umgebungsvariablen haben immer Vorrang vor Werten in der Config-Datei, die wiederum Vorrang vor eingebauten Standardwerten haben. Diese Seite behandelt alle Konfigurationsoptionen, Dateiformate und die Prioritätsregeln.

Prioritätsreihenfolge

Wenn der Edge Connector einen Konfigurationswert auflöst, prüft er die folgenden Quellen in dieser Reihenfolge (höchste Priorität zuerst):

Umgebungsvariablen — überschreiben immer alles andere.
config.json-Datei — Werte aus der Konfigurationsdatei im Arbeitsverzeichnis.
Eingebaute Standardwerte — fest hinterlegte Fallback-Werte, die verwendet werden, wenn keine andere Quelle einen Wert liefert.

Umgebungsvariablen

Die folgenden Umgebungsvariablen steuern das Verhalten des Edge Connectors. Alle sind optional; der Edge Connector funktioniert mit Standardwerten für die lokale Entwicklung.

Verbindung und Server

Variable	Standard	Beschreibung
`TOOL_RPC_URL`	`ws://localhost:3001`	WebSocket-URL für den nara Platform Server. Das ist der primäre Verbindungsendpunkt für den gesamten Tool-Ausführungsverkehr. Verwende `wss://` für Produktion.
`PLATFORM_API_URL`	`http://localhost:3000`	Basis-URL für die nara Platform API. Wird für Bundle-Verwaltung, Authentifizierungs-Endpunkte und Cloud-Connector-Operationen verwendet.
`NEXT_PUBLIC_TOOL_RPC_URL`		Alternative zu `TOOL_RPC_URL`. Wenn `TOOL_RPC_URL` nicht gesetzt ist, wird dieser Wert verwendet. Nützlich beim Teilen von Umgebungsdateien mit der Webapp.
`NEXT_PUBLIC_PLATFORM_API_URL`		Alternative zu `PLATFORM_API_URL`. Gleiches Prioritätsverhalten.

Authentifizierung

Variable	Standard	Beschreibung
`AUTH_TOKEN_PATH`	`./auth-token.json`	Pfad zur Datei, in der der Authentifizierungs-JWT-Token gespeichert wird. Kann absolut oder relativ zum Installationsverzeichnis sein.
`DEPLOYMENT_ID`		Deployment-Identifier für Cloud-/Server-Modus. Wenn sowohl `DEPLOYMENT_ID` als auch `DEPLOYMENT_SECRET` gesetzt sind, nutzt der Connector Deployment-Anmeldedaten statt JWT-Token-Authentifizierung.
`DEPLOYMENT_SECRET`		Deployment-Secret für Cloud-/Server-Modus. Muss zusammen mit `DEPLOYMENT_ID` gesetzt werden.
`DEPLOYMENT_CREDENTIALS_PATH`		Pfad zu einer Datei mit Deployment-Anmeldedaten als Alternative zum einzelnen Setzen von `DEPLOYMENT_ID` und `DEPLOYMENT_SECRET`.

Pfade und Verzeichnisse

Variable	Standard	Beschreibung
`CUSTOM_IMPLEMENTATIONS_PATH`	`./custom-implementations/index.js`	Pfad zum Einstiegspunkt deiner eigenen Tool-Implementierungen. Die Runtime lädt Implementierungen beim Start von diesem Pfad.
`NARA_INSTALL_DIRECTORY`	Aktuelles Arbeitsverzeichnis	Root-Installationsverzeichnis. Wird zur Auflösung relativer Pfade (Token-Datei, Lock-Datei, Shutdown-Datei) und als Basis für den Prozess-Lock verwendet.

Runtime-Verhalten

Variable	Standard	Beschreibung
`HEALTH_PORT`	`8080`	Port für den HTTP Health-Check-Server. Stellt die Endpunkte `/livez`, `/healthz` und `/statusz` bereit.
`EC_TEST_RUN`		Auf `1` setzen, um den Testmodus zu aktivieren. Deaktiviert State-Persistenz, Autostart und das System Tray. Wird von `edge-connector run` für lokales Testen verwendet.
`EC_DISABLE_STATE`		Auf `1` setzen, um State-Persistenz zu deaktivieren. Die Runtime speichert und stellt ihren Laufzustand nicht wieder her. Im Testmodus automatisch aktiviert.
`EC_DISABLE_AUTOSTART`		Auf `1` setzen, um den automatischen Start beim Systemstart zu deaktivieren. Im Testmodus automatisch aktiviert.
`EC_DISABLE_TRAY`		Auf `1` setzen, um das System-Tray-Icon zu deaktivieren. Im Testmodus automatisch aktiviert.
`EC_CONNECTOR_TYPE`	`EDGE`	Connector-Typ-Identifier.
`INSTANCE_TYPE`		Auf `E2E` setzen, um E2E-Test-Tools neben regulären Tools zu registrieren. Wird in End-to-End-Testumgebungen verwendet.

Config-Datei (`config.json`)

Die config.json-Datei liegt im Arbeitsverzeichnis des Edge Connectors. Wenn sie nicht existiert, kopiert die Runtime eine Standardkonfiguration aus dem Installationspaket.

Vollständiges Schema:

{
  "toolRpcUrl": "ws://localhost:3001",
  "authTokenPath": "./auth-token.json",
  "customImplementationsPath": "./custom-implementations/index.js",
  "connectorType": "EDGE",
  "platformApiUrl": "http://localhost:3000",
  "deploymentId": null,
  "currentBundleId": null
}

Feld-Referenz:

Feld	Typ	Erforderlich	Beschreibung
`toolRpcUrl`	`string`	Ja	WebSocket-URL für den nara Platform Server
`authTokenPath`	`string`	Ja	Pfad zur Authentifizierungs-Token-Datei (absolut oder relativ zum Installationsverzeichnis)
`customImplementationsPath`	`string`	Ja	Pfad zum Einstiegspunkt der eigenen Implementierungen
`connectorType`	`"EDGE"`	Ja	Connector-Typ
`platformApiUrl`	`string`	Nein	Basis-URL für die nara Platform API
`deploymentId`	`string`	Nein	Deployment-ID (gesetzt, wenn einem Deployment zugewiesen)
`currentBundleId`	`string`	Nein	Aktuell getrackte Bundle-ID (wird automatisch durch `bundle checkout` und `upload` gesetzt)

Auth-Token-Datei (`auth-token.json`)

Der Authentifizierungs-Token wird als JSON-Datei gespeichert. Diese Datei wird automatisch von edge-connector auth erstellt und von der Runtime verwaltet.

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "savedAt": "2025-01-15T10:30:00.000Z"
}

Feld	Typ	Beschreibung
`token`	`string`	Der JWT-Authentifizierungs-Token
`savedAt`	`string`	ISO-8601-Zeitstempel, wann der Token gespeichert wurde

Die Datei wird mit restriktiven Berechtigungen (0600) erstellt, um den Token vor unbefugtem Zugriff zu schützen.

Deployment-Anmeldedaten-Datei

Für Server-/Cloud-Deployments können Anmeldedaten in einer Datei statt in Umgebungsvariablen gespeichert werden:

{
  "deploymentId": "dep_abc123xyz",
  "deploymentSecret": "sec_9f8e7d6c5b4a..."
}

Setze die Umgebungsvariable DEPLOYMENT_CREDENTIALS_PATH auf den Pfad zu dieser Datei. Die Runtime liest die Datei beim Start und nutzt die Anmeldedaten für die WebSocket-Authentifizierung.

Platform-API-URL-Konfiguration

Die Platform-API-URL bestimmt, wohin der Edge Connector API-Anfragen für Authentifizierung, Bundle-Verwaltung und Cloud-Operationen sendet. Die URL wird in dieser Reihenfolge aufgelöst:

Umgebungsvariable PLATFORM_API_URL
Umgebungsvariable NEXT_PUBLIC_PLATFORM_API_URL
Feld platformApiUrl in config.json
Standard: http://localhost:3000

Für Produktions-Deployments sollte dies auf deine nara-Instanz-URL gesetzt werden (z.B. https://app.nara.de).

Beispielkonfigurationen

{
  "toolRpcUrl": "ws://localhost:3001",
  "authTokenPath": "./auth-token.json",
  "customImplementationsPath": "./custom-implementations/index.js",
  "connectorType": "EDGE",
  "platformApiUrl": "http://localhost:3000"
}

# Umgebungsvariablen
TOOL_RPC_URL=wss://tool-rpc.nara.de
PLATFORM_API_URL=https://app.nara.de
DEPLOYMENT_ID=dep_abc123
DEPLOYMENT_SECRET=sec_xyz789
HEALTH_PORT=8080
EC_DISABLE_TRAY=1

ENV TOOL_RPC_URL=wss://tool-rpc.nara.de
ENV PLATFORM_API_URL=https://app.nara.de
ENV DEPLOYMENT_ID=dep_abc123
ENV DEPLOYMENT_SECRET=sec_xyz789
ENV HEALTH_PORT=8080
ENV EC_DISABLE_TRAY=1
ENV EC_DISABLE_AUTOSTART=1
ENV NARA_INSTALL_DIRECTORY=/app