Ejecutar el Playground en local con Docker

Ejecuta el Playground en local cuando necesites validar tu propio API Client, los permisos de tu cuenta y tus dispositivos físicos. La imagen publicada incluye la interfaz web y el servicio backend, así que no necesitas Go, Node.js ni descargar el código fuente.

Si solo quieres explorar el flujo, empieza por el Playground en línea.

Requisitos previos

• Tener Docker instalado.
• Tener un API Client con su clientId y su clientSecret.
• Que el API Client tenga al menos device:read; el control y la configuración requieren scopes adicionales.
• Tener libre el puerto local 8090.

Las reglas completas están en Scopes de autorización (en inglés).

Protege las credenciales de prueba

Usa una cuenta y unos dispositivos de prueba dedicados, no credenciales de producción. Concede solo los permisos que necesite la validación actual, y no concedas device:manage salvo que vayas a gestionar dispositivos.

1. Crear el archivo de entorno

Crea un directorio vacío y añade un archivo .env:

WLTE_BASE_URL=https://openapi.svnwi.com
WLTE_CLIENT_ID=sustituye-por-tu-clientId
WLTE_CLIENT_SECRET=sustituye-por-tu-clientSecret
WLTE_WS_ENABLED=true

Restringe el acceso al archivo:

chmod 600 .env

No subas el .env a Git ni pongas el clientSecret en código de navegador, en una aplicación móvil o en registros públicos.

2. Descargar y arrancar la última imagen

docker pull wlte/wlte-openapi-playground:latest

docker run -d \
  --name wlte-openapi-playground \
  --env-file .env \
  -p 127.0.0.1:8090:8090 \
  wlte/wlte-openapi-playground:latest

El puerto queda vinculado a la interfaz de loopback del host y no se expone directamente a la red local ni a Internet.

3. Comprobar el proceso

docker ps --filter name=wlte-openapi-playground
docker logs --tail=100 wlte-openapi-playground
curl --fail http://127.0.0.1:8090/healthz

Cuando la comprobación de salud funcione, abre:

http://127.0.0.1:8090

4. Validar tu integración

1. Confirma que la lista de dispositivos coincide con los dispositivos disponibles para la cuenta.
2. Abre un dispositivo y verifica que sus paneles de periféricos coinciden con sus capacidades.
3. Selecciona HTTP y luego WebSocket, y haz una actualización de estado en vivo con cada transporte.
4. Usa solo dispositivos de prueba para las operaciones de relé o RS-485.
5. Compara peticiones, respuestas y mensajes de evento en el Protocol Inspector.

Si la interfaz informa de un error de permisos, actualiza el API Client en API Keys y reinicia el contenedor con las credenciales actualizadas.

Configuración opcional

Estos ajustes tienen valores por defecto y solo hace falta añadirlos al .env si quieres ajustar timeouts, búferes de eventos o registros:

Variable de entorno	Por defecto	Para qué sirve
WLTE_REQUEST_TIMEOUT	15s	Timeout de las peticiones REST API
PLAYGROUND_WS_EVENT_BUFFER	256	Tamaño del búfer de eventos WebSocket
PLAYGROUND_WS_EVENT_HISTORY	200	Eventos que conserva la página
PLAYGROUND_WS_PING_INTERVAL	20s	Intervalo del Ping de WebSocket
PLAYGROUND_TRAFFIC_HISTORY	200	Mensajes que conserva el Protocol Inspector
PLAYGROUND_LOG_FORMAT	json	Formato de los registros
PLAYGROUND_LOG_LEVEL	info	Nivel de registro

Detener y eliminar el contenedor

docker rm -f wlte-openapi-playground

Compilar desde el código fuente

Compila desde el Dockerfile solo cuando necesites validar código sin publicar o modificar el propio Playground:

docker build \
  --build-arg VERSION=local \
  -t wlte-openapi-playground:local \
  .

docker run -d \
  --name wlte-openapi-playground \
  --env-file .env \
  -p 127.0.0.1:8090:8090 \
  wlte-openapi-playground:local

El Dockerfile compila la aplicación Vue, la incrusta en el servicio Go y ejecuta un único proceso sin privilegios de root en la imagen final. El .env nunca se copia dentro de la imagen.

Resolución de problemas

La página no se abre

Confirma que el contenedor está en marcha y que el .env no define PLAYGROUND_LISTEN_ADDR=127.0.0.1:8090. Dentro del contenedor el proceso debe escuchar en 0.0.0.0:8090; la imagen publicada ya usa ese valor por defecto.

La lista de dispositivos está vacía

Confirma que el API Client tiene device:read y que su cuenta puede acceder a dispositivos. Continúa en Fallos habituales.

¿Puedo exponerlo públicamente?

El Playground no incluye inicio de sesión de operador. Añade HTTPS, autenticación o control de acceso de red antes de compartirlo, y usa credenciales de prueba dedicadas con permisos limitados.

Páginas relacionadas

• Playground en línea
• Obtener una API Key
• REST API o WebSocket