Este tutorial describe cómo desarrollar y probar una integración externa sin reconstruir una imagen Docker en cada modificación: su código se ejecuta como un simple proceso Node.js en su máquina y se conecta a una instancia de Gladys lanzada localmente.
Este es el bucle de desarrollo más rápido y complementa el paso 4 de la documentación oficial.
Lo que vas a hacer
Una integración externa se autentica con Gladys mediante un token (un JWT) y un selector (su identificador único). Estos dos valores son creados por Gladys en el momento en que instala la integración (en modo desarrollador) y fabrica su contenedor Docker.
El truco del desarrollo local consiste en:
- instalar la integración una vez en Gladys, lo que genera el token
- recuperar este token y eliminar el contenedor
- ejecutar su código localmente con este token — Gladys no nota la diferencia.
┌──────────────────────────┐ WebSocket + REST ┌─────────────────────────┐
│ Gladys (npm start) │ ◄────────────────────────────────► │ su integración │
│ API localhost:1443 │ token + selector │ node index.js │
│ Front localhost:1444 │ │ (fuera del contenedor) │
└──────────────────────────┘ └─────────────────────────┘
El contenedor Docker solo se utiliza para obtener el token: el código que prueba, en cambio, se ejecuta al lado.
Requisitos previos
Gladys lanzado localmente
Desde la raíz del repositorio Gladys:
nvm use 22
npm start
Este comando lanza en paralelo el servidor (API en http://localhost:1443) y el front (http://localhost:1444). Abra el front y cree su cuenta de administrador si es una primera instalación.
Docker instalado y arrancado
El demonio debe responder al siguiente comando sin errores:
docker ps
Socket Docker no estándar
Si usa Colima (o un socket Docker no estándar)
Gladys se comunica con Docker a través de la biblioteca dockerode, que no lee los contextos Docker. Solo conoce dos cosas: la variable de entorno DOCKER_HOST, y, en su defecto, el socket /var/run/docker.sock.
Con Colima, Podman, Rancher Desktop o un Docker remoto, este socket no existe:
ls -la /var/run/docker.sock # No such file or directory
Su CLI docker sigue funcionando (usa el contexto), pero Gladys, en cambio, no verá ningún demonio y las integraciones externas estarán desactivadas.
Exporte la variable en el shell que lanza Gladys, antes de npm start:
export DOCKER_HOST=$(docker context inspect --format '{{.Endpoints.docker.Host}}')
# ej. unix:///Users/yo/.colima/default/docker.sock
npm start
Alternativa permanente, si prefiere no pensar más en ello:
sudo ln -sf ~/.colima/default/docker.sock /var/run/docker.sock
Síntoma si se olvida este paso: al arrancar, el servidor registra
External integrations are not available: Gladys has no access to a Docker socket, y cualquier intento de instalar una integración externa falla.
Paso 1 — Instalar la integración en modo desarrollador
Vaya a http://localhost:1444/dashboard/integration (el botón solo aparece para una cuenta administradora), luego haga clic en « Instalar desde GitHub ».
En la ventana que se abre, despliegue el enlace « Modo desarrollador: instalar desde una imagen Docker ».
Se le proponen dos campos:
| Campo | Obligatorio | Nota |
|---|---|---|
| Imagen Docker | Sí | Prioritario sobre el docker_image declarado en el manifiesto |
| Manifiesto (JSON, opcional) | No | Innecesario si la imagen lleva el etiqueta io.gladysassistant.manifest, de lo contrario pegue el contenido de su gladys-assistant-integration.json |
Haga clic en Instalar.
¿Qué imagen proporcionar?
a) Una imagen publicada en Github — el caso nominal
ghcr.io/<owner>/<repo>:<version>
Esto es lo que obtienes si tienes un repositorio de GitHub. La CI ya publica imágenes. El contenido de la imagen no importa aquí, ya que de todos modos ejecutarás tu código localmente.
b) Una imagen « de prueba » + el manifiesto pegado — para comenzar sin publicar nada
¿Aún no has publicado nada? Usa cualquier imagen pública ligera y pega tu
manifiesto en el segundo campo:
alpine:3
Gladys descarga alpine, valida tu manifiesto gladys-assistant-integration.json, crea el servicio y genera el token: es todo lo que necesitas. El contenedor no hará nada útil (se detendrá de inmediato, el estado pasará a « Degradado » luego « Error ») — sin importancia, será eliminado en el paso 3.
c) Una imagen construida localmente (en espera PR #2841)
Construye una imagen local desde el directorio de desarrollo de tu integración externa
docker build -t <mi-integracion>:dev .
Variante: instalar desde la URL del repositorio de GitHub
El formulario principal de la misma ventana acepta una URL de repositorio:
https://github.com/<owner>/<repo>
Gladys lee el gladys-assistant-integration.json en la raíz y descarga la imagen declarada en el manifiesto. Práctico cuando el repositorio es público y la imagen publicada — sin manifiesto que copiar.
La única diferencia para el resto: el selector se convierte en ext-<owner>-<repo> en lugar de
ext-dev-<nombre>.
¿Hay que lanzarlo una primera vez?
No, es automático. La instalación encadena: descarga de la imagen → creación del servicio en la base → creación del contenedor → inicio. Es esta creación de contenedor la que fabrica el token, por lo que existe tan pronto como el formulario se completa — te redirige a la página de la integración.
Si el manifiesto es inválido, Gladys muestra el detalle campo por campo (actions[1].depends_on: unknown field) : es una pantalla de desarrollador, los errores son explícitos.
Paso 2 — Recuperar el selector y el token
El selector
Después de la instalación, te redirige a la página de la integración. El selector es el último
segmento de la URL:
http://localhost:1444/dashboard/integration/device/external/<mi-selector>
¡Atención, esto no es el nombre de tu integración! Gladys lo deriva:
| Modo de instalación | Selector |
|---|---|
| Modo desarrollador (imagen Docker) | ext-dev-<nombre-del-manifiesto-en-minúsculas-con-guiones> |
| Desde una URL de repositorio de GitHub | ext-<owner>-<repo> |
En caso de colisión, se añade un sufijo numérico (ext-dev-mi-integracion-2).
Esto no es solo una etiqueta: el SDK lo usa para prefijar los identificadores de tus dispositivos
(ext:<selector>:<mi-dispositivo>), y Gladys rechaza cualquier identificador que salga de este perímetro.
El token
El token nunca se muestra en la interfaz: Gladys lo inyecta en el entorno del
contenedor y no lo vuelve a mostrar. Por lo tanto, se lee directamente en el contenedor, que siempre
lleva el nombre gladys-<selector>:
docker inspect gladys-<mi-selector> \
--format '{{range .Config.Env}}{{println .}}{{end}}' | grep GLADYS_
Salida esperada:
GLADYS_HOST_API_URL=http://host.docker.internal:1443
GLADYS_INTEGRATION_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
GLADYS_INTEGRATION_SELECTOR=ext-dev-mi-integracion
Tienes tus tres variables. Dos precisiones:
GLADYS_HOST_API_URLvalehost.docker.internalporque el valor está escrito para un contenedor. Desde tu máquina, seráhttp://localhost:1443.- El token no tiene fecha de expiración: sigue siendo válido mientras Gladys no recree el
contenedor (ver la sección Dépannage). - Se vuelve a encontrar el nombre del selector encontrado anteriormente gracias a la URL
GLADYS_INTEGRATION_SELECTOR
Paso 3 — Eliminar el contenedor
Un token no puede ser compartido: cuando un segundo cliente se autentica con el mismo token,
Gladys cierra la conexión del primero. Si el contenedor sigue vivo, él y tu proceso local
se cortan la palabra en bucle.
Por lo tanto, elimina el contenedor:
docker rm -f gladys-<mi-selector>
El token sigue siendo válido: su revocación solo depende de un contador en la base de datos, que esta eliminación no toca.
Paso 4 — Lanzar la integración con Node
En el repositorio de tu integración:
nvm use 22
npm install
Luego, lánzala con las tres variables recuperadas:
GLADYS_HOST_API_URL="http://localhost:1443" \
GLADYS_INTEGRATION_TOKEN="<el token copiado>" \
GLADYS_INTEGRATION_SELECTOR="<mi-selector>" \
LOG_LEVEL=debug \
npm start
Verificar que funciona
En el lado de la integración, los registros muestran la conexión al WebSocket. En el lado de Gladys, actualiza la página de la integración: el estado pasa a « En ejecución », incluso cuando ningún contenedor está en funcionamiento. Ahora puedes usar normalmente las pestañas Configuración, Descubrimiento, Dispositivos y Acciones.
Bucle
Modifica tu código, Ctrl-C, relánzalo.
El token sobrevive a todos los reinicios de tu proceso: no es necesario regenerarlo.
Dépannage
| Síntoma | Causa | Correctivo |
|---|---|---|
401 en la API, o cierre del WebSocket con el código 4000 |
El token ha sido revocado: Gladys ha recreado el contenedor (actualización de la integración, modificación del hardware, o reinicio del servidor Gladys) | Reanuda en el paso 2 para releer el token en el nuevo contenedor, luego repite el paso 3 |
| El contenedor reaparece solo y te corta la conexión | Paso 3 no realizado, o realizado con docker stop / el botón « Detener » |
docker rm -f gladys-<mi-selector> |
UNABLE_TO_PULL_IMAGE en la instalación |
La imagen no existe en ningún registro accesible | Usa una imagen de prueba (paso 1b), o la rama de la PR #2841 |
La instalación falla con un error genérico, y el servidor registra External integrations are not available |
Gladys no ve el demonio Docker | Exporta DOCKER_HOST antes de npm start (ver Requisitos previos) |
| Estado « Degradado » luego « Error » justo después de la instalación | Esperado con una imagen de prueba: el contenedor nunca se autentica | Sin consecuencia — el token sigue siendo válido, continúa |
GladysIntegration: missing "…" option |
Una de las tres variables no se ha pasado | Verifica el comando de lanzamiento / el source del .env.local |
La integración se conecta, pero el descubrimiento falla con devices[0].external_id: must start with "ext:…:" |
El selector pasado no corresponde al del servicio: el SDK prefija los external_id con ext:<selector>:, y Gladys rechaza todo lo que sale de su perímetro |
Reanuda el selector exacto en la URL de la página de la integración (paso 2) |
de la integración, con un nuevo token: léelo (paso 2) y elimina nuevamente el
contenedor (paso 3). Esta es la principal sorpresa de este bucle de desarrollo.
Limpieza
Para volver a empezar desde cero, desinstala la integración desde su pestaña Supervisión →
Desinstalar. Gladys elimina el contenedor, su red privada, su carpeta de datos y la
línea correspondiente en la base de datos. Los dispositivos ya creados permanecen en Gladys hasta que los elimines.
Solo queda volver al paso 1.