Ce tutoriel décrit comment développer et tester une intégration externe sans reconstruire une
image Docker à chaque modification : votre code tourne comme un simple process Node.js sur votre machine, et se connecte à une instance Gladys lancée en local.
C’est la boucle de développement la plus rapide, et elle complète l’étape 4 de la documentation
officielle.
Ce que vous allez faire
Une intégration externe s’authentifie auprès de Gladys avec un token (un JWT) et un
selector (son identifiant unique). Ces deux valeurs sont créées par Gladys au moment où il
installe l’intégration (en mode développeur) et fabrique son conteneur Docker.
L’astuce du développement local consiste donc à :
- installer l’intégration une fois dans Gladys, ce qui génère le token
- récupérer ce token et supprimer le conteneur
- lancer votre code en local avec ce token — Gladys ne voit pas la différence.
┌──────────────────────────┐ WebSocket + REST ┌─────────────────────────┐
│ Gladys (npm start) │ ◄────────────────────────────────► │ votre intégration │
│ API localhost:1443 │ token + selector │ node index.js │
│ Front localhost:1444 │ │ (hors conteneur) │
└──────────────────────────┘ └─────────────────────────┘
Le conteneur Docker ne sert qu’à obtenir le token : le code que vous testez, lui, tourne à côté.
Prérequis
Gladys lancé en local
Depuis la racine du dépôt Gladys :
nvm use 22
npm start
Cette commande lance en parallèle le serveur (API sur http://localhost:1443) et le front (http://localhost:1444). Ouvrez le front et créez votre compte administrateur si c’est une première installation.
Docker installé et démarré
Le daemon doit répondre à la commande suivante sans erreur :
docker ps
Socket Docker non standard
Si vous utilisez Colima (ou un socket Docker non standard)
Gladys parle à Docker via la librairie dockerode, qui ne lit pas les contextes Docker. Elle
ne connaît que deux choses : la variable d’environnement DOCKER_HOST, et à défaut le socket
/var/run/docker.sock.
Avec Colima, Podman, Rancher Desktop ou un Docker distant, ce socket n’existe pas :
ls -la /var/run/docker.sock # No such file or directory
Votre CLI docker fonctionne quand même (il utilise le contexte), mais Gladys, lui, ne verra
aucun daemon et les intégrations externes seront désactivées.
Exportez la variable dans le shell qui lance Gladys, avant npm start :
export DOCKER_HOST=$(docker context inspect --format '{{.Endpoints.docker.Host}}')
# ex. unix:///Users/moi/.colima/default/docker.sock
npm start
Alternative permanente, si vous préférez ne plus y penser :
sudo ln -sf ~/.colima/default/docker.sock /var/run/docker.sock
Symptôme si l’étape est oubliée : au démarrage, le serveur logue
External integrations are not available: Gladys has no access to a Docker socket, et toute tentative d’installation d’une intégration externe échoue.
Étape 1 — Installer l’intégration en mode développeur
Rendez-vous sur http://localhost:1444/dashboard/integration (le bouton n’apparaît que pour un compte administrateur), puis cliquez sur « Installer depuis GitHub ».
Dans la fenêtre qui s’ouvre, dépliez le lien « Mode développeur : installer depuis une image
Docker ».
Deux champs vous sont proposés :
| Champ | Obligatoire | Remarque |
|---|---|---|
| Image Docker | Oui | Prioritaire sur le docker_image déclaré dans le manifeste |
| Manifeste (JSON, optionnel) | Non | Inutile si l’image porte le label io.gladysassistant.manifest, sinon collez le contenu de votre gladys-assistant-integration.json |
Cliquez sur Installer.
Quelle image fournir ?
a) Une image publiée sur Github — le cas nominal
ghcr.io/<owner>/<repo>:<version>
C’est ce que vous avez si vous avez un repository Github. La CI publie déjà des images. Le contenu de l’image importe peu ici, puisque vous allez de toute façon exécuter votre code en local.
b) Une image « bouchon » + le manifeste collé — pour démarrer sans rien publier
Vous n’avez encore rien publié ? Utilisez n’importe quelle image publique légère et collez votre
manifeste dans le second champ :
alpine:3
Gladys télécharge alpine, valide votre manifeste gladys-assistant-integration.json, crée le service et génère le token : c’est tout ce dont vous avez besoin. Le conteneur ne fera rien d’utile (il s’arrêtera aussitôt, le statut passera à « Dégradée » puis « Erreur ») — sans aucune importance, il sera supprimé à l’étape 3.
c) Une image construite en local (en attente PR #2841)
Construisez une image locale depuis le répertoire de développement de votre intégration externe
docker build -t <mon-integration>:dev .
Variante : installer depuis l’URL du dépôt GitHub
Le formulaire principal de la même fenêtre accepte une URL de dépôt :
https://github.com/<owner>/<repo>
Gladys y lit le gladys-assistant-integration.json à la racine et télécharge l’image déclarée dans le manifeste. Pratique quand le dépôt est public et l’image publiée — sans manifeste à copier.
Seule différence pour la suite : le selector devient ext-<owner>-<repo> au lieu de
ext-dev-<nom>.
Faut-il la lancer une première fois ?
Non, c’est automatique. L’installation enchaîne : téléchargement de l’image → création du service en base → création du conteneur → démarrage. C’est cette création de conteneur qui fabrique le token, il existe donc dès que le formulaire se termine — vous êtes redirigé sur la page de l’intégration.
Si le manifeste est invalide, Gladys affiche le détail champ par champ (actions[1].depends_on: unknown field) : c’est un écran de développeur, les erreurs sont explicites.
Étape 2 — Récupérer le selector et le token
Le selector
Après l’installation, vous êtes redirigé sur la page de l’intégration. Le selector est le dernier
segment de l’URL :
http://localhost:1444/dashboard/integration/device/external/<mon-selector>
Attention, ce n’est pas le nom de votre intégration. Gladys le dérive :
| Mode d’installation | Selector |
|---|---|
| Mode développeur (image Docker) | ext-dev-<nom-du-manifeste-en-minuscules-avec-tirets> |
| Depuis une URL de dépôt GitHub | ext-<owner>-<repo> |
En cas de collision, un suffixe numérique est ajouté (ext-dev-mon-integration-2).
Ce n’est pas un simple libellé : le SDK s’en sert pour préfixer les identifiants de vos appareils
(ext:<selector>:<mon-appareil>), et Gladys rejette tout identifiant qui sort de ce périmètre.
Le token
Le token n’est jamais affiché dans l’interface : Gladys l’injecte dans l’environnement du
conteneur et ne le réaffiche plus. On le lit donc directement dans le conteneur, qui porte toujours
le nom gladys-<selector> :
docker inspect gladys-<mon-selector> \
--format '{{range .Config.Env}}{{println .}}{{end}}' | grep GLADYS_
Sortie attendue :
GLADYS_HOST_API_URL=http://host.docker.internal:1443
GLADYS_INTEGRATION_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
GLADYS_INTEGRATION_SELECTOR=ext-dev-mon-integration
Vous avez vos trois variables. Deux précisions :
GLADYS_HOST_API_URLvauthost.docker.internalparce que la valeur est écrite pour un conteneur. Depuis votre machine, ce serahttp://localhost:1443.- Le token n’a pas de date d’expiration : il reste valable tant que Gladys ne recrée pas le
conteneur (voir la section Dépannage). - On retrouve le nom du sélecteur trouvé précédemment grâce à l’URL
GLADYS_INTEGRATION_SELECTOR
Étape 3 — Supprimer le conteneur
Un token ne peut pas être partagé : lorsqu’un second client s’authentifie avec le même token,
Gladys ferme la connexion du premier. Si le conteneur reste en vie, lui et votre process local
se coupent la parole en boucle.
Supprimez donc le conteneur :
docker rm -f gladys-<mon-selector>
Le token reste valable : sa révocation ne dépend que d’un compteur en base, que cette suppression ne touche pas.
Étape 4 — Lancer l’intégration avec Node
Dans le dépôt de votre intégration :
nvm use 22
npm install
Puis lancez-la avec les trois variables récupérées :
GLADYS_HOST_API_URL="http://localhost:1443" \
GLADYS_INTEGRATION_TOKEN="<le token copié>" \
GLADYS_INTEGRATION_SELECTOR="<mon-selector>" \
LOG_LEVEL=debug \
npm start
Vérifier que ça marche
Côté intégration, les logs affichent la connexion au WebSocket. Côté Gladys, rafraîchissez la page de l’intégration : le statut passe à « En cours d’exécution », alors même qu’aucun conteneur ne tourne. Vous pouvez maintenant utiliser normalement les onglets Configuration, Découverte, Appareils et Actions.
Boucler
Modifiez votre code, Ctrl-C, relancez.
Le token survit à tous les redémarrages de votre process : inutile de le régénérer.
Dépannage
| Symptôme | Cause | Correctif |
|---|---|---|
401 sur l’API, ou fermeture du WebSocket avec le code 4000 |
Le token a été révoqué : Gladys a recréé le conteneur (mise à jour de l’intégration, modification du matériel, ou redémarrage du serveur Gladys) | Reprenez à l’étape 2 pour relire le token dans le nouveau conteneur, puis refaites l’étape 3 |
| Le conteneur réapparaît tout seul et vous coupe la connexion | Étape 3 non faite, ou faite avec docker stop / le bouton « Arrêter » |
docker rm -f gladys-<mon-selector> |
UNABLE_TO_PULL_IMAGE à l’installation |
L’image n’existe sur aucun registry accessible | Utilisez une image bouchon (étape 1b), ou la branche de la PR #2841 |
L’installation échoue avec une erreur générique, et le serveur logue External integrations are not available |
Gladys ne voit pas le daemon Docker | Exportez DOCKER_HOST avant npm start (voir Prérequis) |
| Statut « Dégradée » puis « Erreur » juste après l’installation | Attendu avec une image bouchon : le conteneur ne s’authentifie jamais | Sans conséquence — le token reste valable, poursuivez |
GladysIntegration: missing "…" option |
Une des trois variables n’a pas été passée | Vérifiez la commande de lancement / le source du .env.local |
L’intégration se connecte, mais la découverte échoue avec devices[0].external_id: must start with "ext:…:" |
Le selector passé ne correspond pas à celui du service : le SDK préfixe les external_id avec ext:<selector>:, et Gladys rejette tout ce qui sort de son périmètre |
Reprenez le selector exact dans l’URL de la page de l’intégration (étape 2) |
de l’intégration, avec un nouveau token : relisez-le (étape 2) et supprimez à nouveau le
conteneur (étape 3). C’est la principale surprise de cette boucle de développement.
Nettoyage
Pour repartir sur des bases saines, désinstallez l’intégration depuis son onglet Supervision →
Désinstaller. Gladys supprime le conteneur, son réseau privé, son dossier de données et la
ligne correspondante en base. Les appareils déjà créés restent dans Gladys jusqu’à ce que vous les supprimiez.
Il ne reste plus qu’à reprendre à l’étape 1.