MQTT Dashboard

A self-hostable MQTT dashboard/explorer for IoT developers.

---

⭐ Features

• Drag & Drop Dashboard — Build your own control center with resizable, draggable panels using a grid layout engine
• Dashboard Panels — Button, Input, Log, Cron, and Stats panels for publish, automation, and monitoring
• Topic Explorer + Wildcards — Browse MQTT topic trees and subscribe with + and # patterns
• Message History — Persistent history with retention settings and cleanup controls
• Multi-Broker Support — Connect to multiple MQTT brokers simultaneously and manage them from a single interface
• TLS & Authentication — Supports plain TCP, TLS/SSL, username/password, and certificate-based authentication
• Real-Time Updates — WebSocket-powered live message streaming
• Single Binary — Go backend with embedded React frontend, zero external dependencies
• Docker Ready — One command to deploy with persistent data volume

---

🔧 How to Install

🐳 Docker Compose (Recommended)

services:
  mqtt-dashboard:
    image: ghcr.io/jmischler72/mqtt-dashboard:latest
    container_name: mqtt-dashboard
    ports:
      - "8080:8080"
    volumes:
      - data_volume:/app/data

volumes:
  data_volume:

docker compose up -d

MQTT Dashboard is now running at http://localhost:8080.

🐳 Docker Command

docker run -d \
  --restart=always \
  -p 8080:8080 \
  -v mqtt-dashboard-data:/app/data \
  --name mqtt-dashboard \
  ghcr.io/jmischler72/mqtt-dashboard:latest

💪 Build from Source

Requirements: Go 1.22+, Node.js 20+

git clone https://github.com/jmischler72/mqtt-dashboard.git
cd mqtt-dashboard

# Build frontend
cd frontend && npm ci && npm run build && cd ..

# Build backend (embeds frontend)
cd backend
cp -r ../frontend/dist ./dist
go build -o mqtt-dashboard .
./mqtt-dashboard

---

🖼️ Panel Types

Functional panels

Panel	Description
Button	One-click publish a preset payload to a topic
Input	Type and send ad-hoc messages to any topic
Log	Real-time message stream with history, wildcards, and date formatting
Cron	Scheduled automatic publishing with visual cron builder and countdown
Stats	Live topic activity charts with configurable time windows

Visual panels

Panel	Description
Image	Provide an image from url/file to show in the dashboard
Separator	Vertical/horizontal to visually separate parts of dashboard
Text	Markdown text to document your dashboard

---

MQTT Implementation

MQTT Dashboard supports a lot of features from MQTT:

• TLS/SSL encryption for broker communication
• Username & Password authentication
• Client Certificate authentication (mTLS)
• QoS Quality of service flags from mqtt specs
• Retain flags that sends back retained message to new subscribers

---

🏗️ Architecture

┌──────────────────────────┐         ┌──────────────────────┐
│   React Frontend (SPA)   │◄──WS──► │    Go Backend        │
│   Vite + Tailwind +      │◄──API─► │    Single Binary     │
│   DaisyUI                │         │                      │
└──────────────────────────┘         └──────────┬───────────┘
                                                │
                                     ┌──────────┴───────────┐
                                     │                      │
                              ┌──────▼──────┐    ┌──────────▼──────────┐
                              │   SQLite    │    │  MQTT Brokers (N)   │
                              │  (layouts,  │    │  TCP / TLS / Auth   │
                              │   configs,  │    └─────────────────────┘
                              │   history)  │
                              └─────────────┘

In production, the Go binary serves the embedded React build directly (so no need for the vite server :) ), it also handles API routes, WebSocket connections, and MQTT client management — all from a single port (:8080).

---

💡 Motivation

Existing MQTT tools are either purely client-side, lack persistence, or don't support building custom control interfaces. MQTT Dashboard combines the best of monitoring tools like MQTT Explorer with the flexibility of a customizable panel-based dashboard — all self-hosted in a single binary.

And here is the link to MQTT-Explorer that inspired a lot this project: https://github.com/thomasnordquist/MQTT-Explorer

If you find this project useful, please consider giving it a ⭐!

---

🗺️ Roadmap

• Allow users to create their custom panels and share them
• More customisable options in base panels

See TODO.md and docs/PRD/ for full details.

---

🛠️ Tech Stack

Layer	Technology
Frontend	React, Vite, TypeScript, Tailwind CSS, DaisyUI
Grid Engine	react-grid-layout
Backend	Go (Golang)
MQTT lib	Eclipse paho.mqtt.golang
Database	SQLite (embedded)
Scheduling	gocron
Realtime	WebSocket
Container	Docker (Alpine)

---

📄 License

GPL-3.0

---

Thank you for checking it out ! Hope you like it. And yes the readme looks like Uptime Kuma because i like it