# Développement - Tester une intégration externe avec Gladys en local **URL:** \ **Category:** Tutoriels\ **Tags:** integration-externe\ **Created:** [Août 10, 2026, 8:51 UTC](https://community.gladysassistant.com/t/developpement-tester-une-integration-externe-avec-gladys-en-local/10525 "2026-08-10T20:51:13Z")\ **Posts on this page:** 1\ **Page:** 1
**Author:** ![cicoub13](https://gladys-assistant-community.b-cdn.net/user_avatar/community.gladysassistant.com/cicoub13/32/4482_2.png) [@cicoub13](https://community.gladysassistant.com/u/cicoub13)\ **Post date:** [Août 10, 2026, 8:51 UTC](https://community.gladysassistant.com/t/developpement-tester-une-integration-externe-avec-gladys-en-local/10525/1 "2026-08-10T20:51:13Z")
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](https://gladysassistant.com/fr/docs/dev/external-integrations/#%C3%A9tape-4--construire-et-tester-en-local). ## 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 à : 1. installer l’intégration une fois dans Gladys, ce qui génère le token 2. récupérer ce token et supprimer le conteneur 3. lancer votre code en local avec ce token — Gladys ne voit pas la différence. ```auto ┌──────────────────────────┐ 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 : ```bash 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. ![http://localhost:1444](https://gladys-assistant-community.b-cdn.net/uploads/default/original/3X/a/e/ae2f2615c54c4c90d7515f3d61518679f76b07bf.png) ### Docker installé et démarré Le daemon doit répondre à la commande suivante sans erreur : ```bash 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 : > > ```bash > 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`** : > > ```bash > 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 : > > ```bash > 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 »**. ![Install from Github](https://gladys-assistant-community.b-cdn.net/uploads/default/original/3X/b/f/bfd255c45cb75eaad1d449d20e67590411699173.jpeg) Dans la fenêtre qui s’ouvre, dépliez le lien **« Mode développeur : installer depuis une image Docker »**. ![Mode développeur](https://gladys-assistant-community.b-cdn.net/uploads/default/original/3X/4/9/49d84c0a1044dd527d674640a88d0d4473debdfc.png) 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**. ![Exemple image github](https://gladys-assistant-community.b-cdn.net/uploads/default/original/3X/7/3/731fd4169add8a1d1bf5537f3e958469256c2474.png) ### Quelle image fournir ? **a) Une image publiée sur Github** — le cas nominal ```auto ghcr.io//: ``` 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 : ```auto 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](https://github.com/GladysAssistant/Gladys/pull/2841)) Construisez une image locale depuis le répertoire de développement de votre intégration externe ```bash docker build -t :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 : ```auto https://github.com// ``` 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--` au lieu de `ext-dev-`. * * * ### 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 : ```auto http://localhost:1444/dashboard/integration/device/external/ ``` 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-` | | Depuis une URL de dépôt GitHub | `ext--` | 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::`), et Gladys rejette tout identifiant qui sort de ce périmètre. ![Selector dans l'url](https://gladys-assistant-community.b-cdn.net/uploads/default/original/3X/3/4/34d3783617339c541f844ff88be91d5c7f704ab2.png) ### 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-` : ```bash docker inspect gladys- \ --format '{{range .Config.Env}}{{println .}}{{end}}' | grep GLADYS_ ``` Sortie attendue : ```auto 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_URL` vaut `host.docker.internal` **parce que la valeur est écrite pour un conteneur**. Depuis votre machine, ce sera `http://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 : ```bash docker rm -f gladys- ``` ## 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 : ```bash nvm use 22 npm install ``` Puis lancez-la avec les trois variables récupérées : ```bash GLADYS_HOST_API_URL="http://localhost:1443" \ GLADYS_INTEGRATION_TOKEN="" \ GLADYS_INTEGRATION_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. ![Logs et état Running](https://gladys-assistant-community.b-cdn.net/uploads/default/original/3X/c/5/c5317b89d51790ab514c3831c395630bdbca4f85.jpeg) ### 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-` | | `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::`, 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) | > ⚠ **Après chaque redémarrage du serveur Gladys** , le conteneur supprimé est recréé au démarrage > 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.