slalaure/mqtt_uns_viewer repository overview

⁠⚠️ DEPRECATED: Project Renamed to Korelate

This project has evolved and is now officially named Korelate.

No further updates will be published to this Docker Hub repository. To get the latest versions, features, and security updates, please pull from our new repository:

👉 hub.docker.com/r/slalaure/korelate⁠

⁠How to migrate

Update your docker-compose.yml or docker run commands to use the new image name: image: slalaure/korelate:latest

For the source code and documentation, visit our GitHub repository: github.com/slalaure/korelate⁠

⁠MQTT UNS Viewer

A lightweight, real-time web application to visualize MQTT topic trees, dynamic SVG graphics, and data history for Unified Namespace (UNS) and Sparkplug B.

This image provides a self-contained, broker-agnostic web server that connects to any MQTT broker, saves all messages to an embedded DuckDB database, and broadcasts them via WebSocket to a real-time web frontend.

⁠✨ Key Features

• Real-time Topic Tree: Visualize your entire MQTT namespace as it builds, including payload and timestamp.
• Dynamic SVG View: Animate 2D diagrams, P&IDs, or maps using data from MQTT topics.
• Sparkplug B Support: Automatically decodes Sparkplug B Protobuf payloads for visualization.
• Persistent History: All messages are saved to an embedded DuckDB database within the data volume.
• History View: A powerful UI to search, filter by time, and inspect all historical data.
• Topic Mapper: Create real-time data transformations (e.g., "Topic A -> Topic B") using simple JavaScript and even query the database.
• Charting: Build, save, and share custom time-series charts from any numeric data in your payloads.
• Publish Tab: Manually publish messages (JSON, String, or Sparkplug B) to any topic.
• Agent Protocol (MCP): Includes an optional server (mcp_server.mjs) to allow LLMs or agents to query and control the instance.
• Secure Connection: Supports standard mqtts with username/password and mtls with client certificates (e.g., for AWS IoT).

⁠🚀 How to Run (Recommended)

The best way to run this application is with docker-compose, as it correctly sets up the data volume and the optional MCP server.

⁠1. Create your data directory

This directory will store your configuration, database, and custom SVG files.

mkdir -p mqtt-viewer-data/certs
cd mqtt-viewer-data

⁠2. Create a .env file

Inside the mqtt-viewer-data directory, create a .env file. You can copy the .env.example⁠ from the project.

File: mqtt-viewer-data/.env

# --- General MQTT Broker Configuration ---
MQTT_BROKER_HOST=www.mqttunsviewer.com
MQTT_PORT=1883
MQTT_PROTOCOL=mqtt
#change bellow id to make it unique, if already in use you will be disconnected
CLIENT_ID=my-web-visualizer-app-docker
MQTT_TOPIC="stark_industries/#,spBv1.0/stark_industries/#"

# --- Authentication (use one method) ---
MQTT_USERNAME=
MQTT_PASSWORD=
CERT_FILENAME=
KEY_FILENAME=
CA_FILENAME=

# --- Application ---
SIMULATOR_ENABLED=true
PORT=8080
SPARKPLUG_ENABLED=true

# --- Database ---
DUCKDB_MAX_SIZE_MB=50
DB_INSERT_BATCH_SIZE=1000
DB_BATCH_INTERVAL_MS=1000

# --- MCP Server (Optional) ---
# stdio or http
MCP_TRANSPORT=http
MCP_PORT=3000

Important: If you are using MTLS (e.g., AWS IoT), place your certificate files (.crt, .key) inside the mqtt-viewer-data/certs directory you created.

⁠3. Create a docker-compose.yml

In the same directory where you created mqtt-viewer-data, create this file:

File: docker-compose.yml

version: '3.8'

services:
  app:
    image: slalaure/mqtt_uns_viewer:latest
    container_name: mqtt_uns_viewer_app
    restart: always
    ports:
      - "8080:8080" # Web application
    volumes:
      # Mount the data directory for persistence
      - ./mqtt-viewer-data:/usr/src/app/data
    environment:
      - NODE_ENV=production
      - PORT=8080
      - BASE_PATH=/

  mcp:
    image: slalaure/mqtt_uns_viewer:latest
    container_name: mqtt_uns_viewer_mcp
    restart: always
    ports:
      - "3000:3000" # MCP server
    volumes:
      - ./mqtt-viewer-data:/usr/src/app/data
    environment:
      - NODE_ENV=production
      - MCP_TRANSPORT=http
      - MCP_PORT=3000
      - MAIN_APP_HOST=app # Docker DNS name for the app service
      - PORT=8080
      - BASE_PATH=/
    command: node mcp_server.mjs # Overrides the default command
    depends_on:
      - app

⁠4. Run!

docker-compose up -d

You can now access the web viewer at http://localhost:8080.

⁠🔧 Configuration

All configuration is managed via the .env file located in your persistent data volume.

⁠📄 License

This project is licensed under the APACHE 2.0 License.