Dieser Tutorial beschreibt, wie Sie eine externe Integration entwickeln und testen können, ohne bei jeder Änderung ein Docker-Image neu zu erstellen: Ihr Code läuft wie ein einfacher Node.js-Prozess auf Ihrem Computer und verbindet sich mit einer lokal gestarteten Gladys-Instanz.
Dies ist die schnellste Entwicklungsmethode und ergänzt den Schritt 4 der offiziellen Dokumentation.
Was Sie tun werden
Eine externe Integration authentifiziert sich bei Gladys mit einem Token (einem JWT) und einem Selector (einer eindeutigen Kennung). Diese beiden Werte werden von Gladys zum Zeitpunkt der Installation der Integration (im Entwicklermodus) erstellt und ihr Docker-Container wird erstellt.
Der Trick bei der lokalen Entwicklung besteht darin:
- Installieren Sie die Integration einmal in Gladys, was das Token generiert
- Holen Sie sich dieses Token und löschen Sie den Container
- Starten Sie Ihren Code lokal mit diesem Token — Gladys merkt den Unterschied nicht.
┌──────────────────────────┐ WebSocket + REST ┌─────────────────────────┐
│ Gladys (npm start) │ ◄────────────────────────────────► │ Ihre Integration │
│ API localhost:1443 │ Token + Selector │ node index.js │
│ Front localhost:1444 │ │ (außerhalb des Containers) │
└──────────────────────────┘ └─────────────────────────┘
Der Docker-Container dient nur dazu, das Token zu erhalten: Der Code, den Sie testen, läuft daneben.
Voraussetzungen
Gladys lokal gestartet
Von der Wurzel des Gladys-Repos:
nvm use 22
npm start
Dieser Befehl startet parallel den Server (API unter http://localhost:1443) und die Frontend (http://localhost:1444). Öffnen Sie die Frontend und erstellen Sie Ihr Administrator-Konto, wenn es sich um eine Erstinstallation handelt.
Docker installiert und gestartet
Der Daemon muss auf den folgenden Befehl ohne Fehler antworten:
docker ps
Nicht standardmäßiger Docker-Socket
Wenn Sie Colima (oder einen nicht standardmäßigen Docker-Socket) verwenden
Gladys kommuniziert mit Docker über die Bibliothek dockerode, die keine Docker-Kontexte liest. Sie kennt nur zwei Dinge: die Umgebungsvariable DOCKER_HOST und, falls nicht vorhanden, den Socket /var/run/docker.sock.
Mit Colima, Podman, Rancher Desktop oder einem entfernten Docker existiert dieser Socket nicht:
ls -la /var/run/docker.sock # No such file or directory
Ihre CLI docker funktioniert trotzdem (sie verwendet den Kontext), aber Gladys sieht keinen Daemon und externe Integrationen werden deaktiviert.
Exportieren Sie die Variable in der Shell, die Gladys startet, bevor npm start:
export DOCKER_HOST=$(docker context inspect --format '{{.Endpoints.docker.Host}}')
# z. B. unix:///Users/moi/.colima/default/docker.sock
npm start
Dauerhafte Alternative, wenn Sie nicht mehr daran denken möchten:
sudo ln -sf ~/.colima/default/docker.sock /var/run/docker.sock
Symptom, wenn der Schritt vergessen wird: Beim Start protokolliert der Server
External integrations are not available: Gladys has no access to a Docker socket, und jeder Versuch, eine externe Integration zu installieren, scheitert.
Schritt 1 — Installation der Integration im Entwicklermodus
Gehen Sie zu http://localhost:1444/dashboard/integration (der Button erscheint nur für ein Administrator-Konto), und klicken Sie dann auf „Von GitHub installieren“.
Im sich öffnenden Fenster klicken Sie auf den Link „Entwicklermodus: Von einem Docker-Image installieren“.
Es werden Ihnen zwei Felder vorgeschlagen:
| Feld | Pflichtfeld | Bemerkung |
|---|---|---|
| Docker-Image | Ja | Priorität gegenüber dem im Manifest deklarierten docker_image |
| Manifest (JSON, optional) | Nein | Unnötig, wenn das Image das Label io.gladysassistant.manifest trägt, andernfalls fügen Sie den Inhalt Ihrer gladys-assistant-integration.json ein |
Klicken Sie auf Installieren.
Welches Image bereitstellen?
a) Ein auf GitHub veröffentlichtes Image — der nominale Fall
ghcr.io/<owner>/<repo>:<version>
Das ist das, was Sie haben, wenn Sie ein GitHub-Repository besitzen. Die CI veröffentlicht bereits Bilder. Der Inhalt des Bildes ist hier nicht wichtig, da Sie Ihren Code ohnehin lokal ausführen werden.
b) Ein „Platzhalter“-Bild + das angehängte Manifest — zum Starten ohne Veröffentlichung
Haben Sie noch nichts veröffentlicht? Verwenden Sie ein beliebiges leichtes öffentliches Bild und fügen Sie Ihr
Manifest im zweiten Feld ein:
alpine:3
Gladys lädt alpine herunter, validiert Ihr Manifest gladys-assistant-integration.json, erstellt den Dienst und generiert den Token: Das ist alles, was Sie benötigen. Der Container wird nichts Nützliches tun (er wird sofort stoppen, der Status wird auf „Degraded“ und dann „Error“ wechseln) — ohne Bedeutung, er wird in Schritt 3 gelöscht.
c) Ein lokal gebautes Bild (in Warteschleife PR #2841)
Bauen Sie ein lokales Bild aus dem Entwicklungsverzeichnis Ihrer externen Integration
docker build -t <meine-integration>:dev .
Variante: Installation aus der GitHub-Repository-URL
Das Hauptformular desselben Fensters akzeptiert eine Repository-URL:
https://github.com/<owner>/<repo>
Gladys liest das gladys-assistant-integration.json an der Wurzel und lädt das im Manifest deklarierte Bild herunter. Praktisch, wenn das Repository öffentlich ist und das Bild veröffentlicht — ohne Manifest zum Kopieren.
Einziger Unterschied für den Rest: Der Selector wird zu ext-<owner>-<repo> statt
ext-dev-<name>.
Muss man es einmal starten?
Nein, das ist automatisch. Die Installation verknüpft: Herunterladen des Bildes → Erstellen des Dienstes in der Datenbank → Erstellen des Containers → Starten. Dieses Erstellen des Containers erzeugt den Token, er existiert also, sobald das Formular beendet ist — Sie werden auf die Integrationsseite weitergeleitet.
Wenn das Manifest ungültig ist, zeigt Gladys die Details Feld für Feld an (actions[1].depends_on: unknown field): Es ist ein Entwicklerbildschirm, die Fehler sind explizit.
Schritt 2 — Selector und Token abrufen
Der Selector
Nach der Installation werden Sie auf die Integrationsseite weitergeleitet. Der Selector ist das letzte
Segment der URL:
http://localhost:1444/dashboard/integration/device/external/<mein-selector>
Achtung, das ist nicht der Name Ihrer Integration. Gladys leitet ihn ab:
| Installationsmodus | Selector |
|---|---|
| Entwicklermodus (Docker-Bild) | ext-dev-<name-des-manifests-in-kleinbuchstaben-mit-bindestrichen> |
| Aus einer GitHub-Repository-URL | ext-<owner>-<repo> |
Bei Kollisionen wird ein numerisches Suffix hinzugefügt (ext-dev-meine-integration-2).
Das ist kein einfaches Etikett: Das SDK verwendet es, um die Identifikatoren Ihrer Geräte zu präfixieren
(ext:<selector>:<mein-gerät>), und Gladys lehnt jede Kennung ab, die außerhalb dieses Bereichs liegt.
Der Token
Der Token wird nie in der Benutzeroberfläche angezeigt: Gladys injiziert ihn in die Umgebung des
Containers und zeigt ihn nicht erneut an. Man liest ihn also direkt im Container, der immer den Namen gladys-<selector> trägt:
docker inspect gladys-<mein-selector> \
--format '{{range .Config.Env}}{{println .}}{{end}}' | grep GLADYS_
Erwartete Ausgabe:
GLADYS_HOST_API_URL=http://host.docker.internal:1443
GLADYS_INTEGRATION_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
GLADYS_INTEGRATION_SELECTOR=ext-dev-meine-integration
Sie haben Ihre drei Variablen. Zwei Hinweise:
GLADYS_HOST_API_URLhat den Werthost.docker.internalweil der Wert für einen Container geschrieben ist. Von Ihrem Computer aus wird eshttp://localhost:1443sein.- Der Token hat kein Ablaufdatum: Er bleibt gültig, solange Gladys den
Container nicht neu erstellt (siehe den Abschnitt Problembehebung). - Man findet den Namen des Selectors, der zuvor gefunden wurde, dank der URL
GLADYS_INTEGRATION_SELECTOR
Schritt 3 — Container löschen
Ein Token kann nicht geteilt werden: Wenn sich ein zweiter Client mit demselben Token authentifiziert,
schließt Gladys die Verbindung des ersten. Wenn der Container am Leben bleibt, unterbrechen er und Ihr lokaler Prozess sich gegenseitig in einer Endlosschleife.
Löschen Sie also den Container:
docker rm -f gladys-<mein-selector>
Der Token bleibt gültig: Seine Widerrufung hängt nur von einem Zähler in der Datenbank ab, den diese Löschung nicht beeinflusst.
Schritt 4 — Integration mit Node starten
Im Repository Ihrer Integration:
nvm use 22
npm install
Starten Sie sie dann mit den drei abgerufenen Variablen:
GLADYS_HOST_API_URL="http://localhost:1443" \
GLADYS_INTEGRATION_TOKEN="<der kopierte token>" \
GLADYS_INTEGRATION_SELECTOR="<mein-selector>" \
LOG_LEVEL=debug \
npm start
Überprüfen, dass es funktioniert
Auf der Integrationsseite werden die Logs die Verbindung zum WebSocket anzeigen. Auf der Gladys-Seite aktualisieren Sie die Integrationsseite: Der Status wechselt zu „Läuft“, obwohl kein Container läuft. Sie können nun normalerweise die Registerkarten Konfiguration, Erkennung, Geräte und Aktionen verwenden.
In einer Schleife arbeiten
Ändern Sie Ihren Code, Ctrl-C, starten Sie neu.
Der Token überlebt alle Neustarts Ihres Prozesses: Es ist nicht notwendig, ihn neu zu generieren.
Problembehebung
| Symptom | Ursache | Lösung |
|---|---|---|
401 auf der API oder Schließen der WebSocket-Verbindung mit dem Code 4000 |
Der Token wurde widerrufen: Gladys hat den Container neu erstellt (Aktualisierung der Integration, Änderung der Hardware oder Neustart des Gladys-Servers) | Gehen Sie zu Schritt 2 zurück, um den Token im neuen Container zu lesen, und führen Sie dann Schritt 3 aus |
| Der Container erscheint von selbst und unterbricht Ihre Verbindung | Schritt 3 nicht durchgeführt oder mit docker stop / der „Stop“-Schaltfläche durchgeführt |
docker rm -f gladys-<mein-selector> |
UNABLE_TO_PULL_IMAGE bei der Installation |
Das Bild existiert auf keinem zugänglichen Registry | Verwenden Sie ein Platzhalter-Bild (Schritt 1b) oder den Zweig des PR #2841 |
Die Installation scheitert mit einem generischen Fehler und der Server protokolliert External integrations are not available |
Gladys sieht den Docker-Daemon nicht | Exportieren Sie DOCKER_HOST vor npm start (siehe Voraussetzungen) |
| Status „Degraded“ und dann „Error“ direkt nach der Installation | Erwartet mit einem Platzhalter-Bild: Der Container authentifiziert sich nie | Ohne Konsequenz — der Token bleibt gültig, fahren Sie fort |
GladysIntegration: missing "…" option |
Eine der drei Variablen wurde nicht übergeben | Überprüfen Sie den Startbefehl / die source der .env.local |
Die Integration verbindet sich, aber die Erkennung scheitert mit devices[0].external_id: must start with "ext:…:" |
Der übergebene Selector entspricht nicht dem des Dienstes: Das SDK präfixiert die external_id mit ext:<selector>:, und Gladys lehnt alles ab, was außerhalb seines Bereichs liegt |
Nehmen Sie den genauen Selector aus der URL der Integrationsseite (Schritt 2) |
Integration mit einem neuen Token neu erstellt: Lesen Sie ihn erneut (Schritt 2) und löschen Sie den
Container erneut (Schritt 3). Das ist die Hauptüberraschung dieser Entwicklungs Schleife.
Aufräumen
Um wieder auf gesunde Grundlagen zurückzukehren, deinstallieren Sie die Integration über ihren Tab Überwachung →
Deinstallieren. Gladys löscht den Container, sein privates Netzwerk, seinen Datenordner und die entsprechende Zeile in der Datenbank. Die bereits erstellten Geräte bleiben in Gladys, bis Sie sie löschen.
Es bleibt nur noch, zu Schritt 1 zurückzukehren.