Run Playground Locally with Docker

Run Playground locally when you need to validate your own API Client, account permissions, and physical devices. The published image includes both the web interface and backend service, so Go, Node.js, and a source checkout are not required.

If you only want to explore the workflow, start with the online Playground.

Prerequisites

• Docker is installed.
• You have an API Client with its clientId and clientSecret.
• The API Client has at least device:read; control and configuration require additional scopes.
• Local port 8090 is available.

See Authorization Scopes for the complete rules.

Protect test credentials

Use a dedicated test account and test devices instead of production credentials. Grant only the permissions required for the current validation, and do not grant device:manage unless device management is required.

1. Create the Environment File

Create an empty directory and add a .env file:

WLTE_BASE_URL=https://openapi.svnwi.com
WLTE_CLIENT_ID=replace-with-your-clientId
WLTE_CLIENT_SECRET=replace-with-your-clientSecret
WLTE_WS_ENABLED=true

Restrict access to the file:

chmod 600 .env

Do not commit .env to Git or place clientSecret in browser code, a mobile application, or public logs.

2. Pull and Start the Latest Image

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

The port is bound to the host loopback interface and is not exposed directly to the local network or Internet.

3. Verify the Process

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

After the health check succeeds, open:

http://127.0.0.1:8090

4. Validate Your Integration

1. Confirm that the device list matches the devices available to the account.
2. Open a device and verify that its peripheral panels match its capabilities.
3. Select HTTP and WebSocket in turn, then perform one live state refresh with each transport.
4. Use only test devices for relay or RS-485 operations.
5. Compare requests, responses, and event messages in Protocol Inspector.

If the UI reports a permission error, update the API Client on API Keys, then restart the container with the updated credentials.

Optional Configuration

The following settings have defaults and only need to be added to .env when you want to tune timeouts, event buffers, or logging:

Environment variable	Default	Purpose
WLTE_REQUEST_TIMEOUT	15s	REST API request timeout
PLAYGROUND_WS_EVENT_BUFFER	256	WebSocket event buffer size
PLAYGROUND_WS_EVENT_HISTORY	200	Events retained by the page
PLAYGROUND_WS_PING_INTERVAL	20s	WebSocket Ping interval
PLAYGROUND_TRAFFIC_HISTORY	200	Messages retained by Protocol Inspector
PLAYGROUND_LOG_FORMAT	json	Log format
PLAYGROUND_LOG_LEVEL	info	Log level

Stop and Remove the Container

docker rm -f wlte-openapi-playground

Build from Source

Build from the Dockerfile only when you need to validate unreleased code or modify Playground itself:

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

The Dockerfile builds the Vue application, embeds it into the Go service, and runs one non-root process in the final image. .env is never copied into the image.

Troubleshooting

The Page Does Not Open

Confirm that the container is running and that .env does not set PLAYGROUND_LISTEN_ADDR=127.0.0.1:8090. The process must listen on 0.0.0.0:8090 inside the container; the published image already uses that default.

The Device List Is Empty

Confirm that the API Client has device:read and that its account can access devices. Continue with Common Failures.

Can I Expose It Publicly?

Playground does not provide operator login. Add HTTPS, authentication, or network access controls before sharing it, and use dedicated test credentials with limited permissions.

Related Pages

• Online Playground
• Get an API Key
• REST API vs WebSocket