MQTT Dashboard
The lightweight, self-hosted MQTT dashboard & topic explorer for IoT developers.
Single binary • Embedded SQLite • Zero external dependencies
---
## ⚡ Why MQTT Dashboard?
Existing tools are either **purely ephemeral topic viewers** (where configurations vanish between sessions) or **heavyweight platforms** (Grafana, Home Assistant) requiring separate databases and complex setups.
**MQTT Dashboard** combines the best of both worlds:
- 🌲 **Explore & Inspect**: Collapsible MQTT topic trees, wildcard subscriptions (`+`, `#`), live numeric graphs, and searchable SQLite history.
- 🎛️ **Monitor & Control**: Drag-and-drop customizable dashboards with Gauges, Toggles, Sliders, Real-time Logs, Inputs, and Buttons.
- 🔄 **Bidirectional Payload Shaping**: Automatically extract nested JSON fields (`telemetry.temp`), match textual stencils (`temp={value}`), or publish formatted templates with `{value}` chips.
- ⏰ **Automated Cron Jobs**: Schedule recurring publishes or sensor polling routines directly from dashboard panels.
- 🔒 **Production Security**: Connect to multiple brokers concurrently over plain TCP, TLS/SSL, or mutual TLS (client certificate & key).
- 📦 **Zero-Config Deployment**: Single self-contained Go binary with embedded SQLite and React UI. No external database or Redis needed.
> 🚀 **[Try the Live Demo without installing](https://mqtt-dashboard.apps.joff.sh)**
---
## 🚀 Quick Start
### 🐳 Option A: Docker (Recommended)
Run the lightweight container and connect to your broker via the web UI:
```bash
docker run -d \
--name mqtt-dashboard \
--restart unless-stopped \
-p 8080:8080 \
-v mqtt_data:/app/data \
ghcr.io/jmischler72/mqtt-dashboard:latest
```
*(Or use Docker Compose: `docker compose -f docker/doc/docker-compose.yml up -d`)*
---
### 📦 Option B: Standalone Binary (Linux, macOS, Windows)
No Docker or Node.js required. Download the single executable for your platform from **[GitHub Releases](https://github.com/jmischler72/mqtt-dashboard/releases)** and run:
```bash
# Example for Linux / macOS
./mqtt-dashboard
```
Open **[http://localhost:8080](http://localhost:8080)** and start building!
---
> 🛠️ **More Deployment & Developer Options:**
> - **[All-in-One Compose with Mosquitto](docker/doc/docker-compose.with-broker.yml)** — Launch a complete test stack with an integrated broker (`docker compose -f docker/doc/docker-compose.with-broker.yml up -d`).
> - **[Building from Source](docs/building-from-source.md)** — Instructions to compile the standalone binary or build the Docker container locally.
> - **[Configuration & Seeding Guide](docs/configuration.md)** — Custom ports, storage paths, reverse-proxy sub-paths, and broker/dashboard auto-seeding.
> - **[systemd & Reverse-Proxy Guide](docs/systemd-apache-deployment.md)** — Production deployment as an unprivileged Linux service behind Apache.
---
## 🎛️ Dashboard Panels
| Panel | Type | Description |
|---|---|---|
| **Gauge** | Monitor | Radial, bar, or numeric display with nested JSON path extraction (`data.temp`) |
| **Graph** | Monitor | Live time-series charts plotted from message history with wildcard multi-series |
| **Log** | Monitor | Live streaming message feed with persistent history, QoS badges, and date formatting |
| **Broker Stats** | Monitor | Live broker telemetry, memory usage, client counts, and `$SYS` metrics |
| **Toggle** | Control | On/off switch with separate read/write shapes (Zigbee2MQTT, Tasmota, Shelly) |
| **Slider** | Control | Range slider for brightness, setpoints, or volume with value interpolation |
| **Button** | Control | One-click message publish with optional confirmation modal |
| **Input** | Control | Interactive text input to publish ad-hoc payloads to any topic |
| **Cron** | Automation | Scheduled recurring publisher with visual schedule builder and countdown |
| **Image / Markdown / Separator** | Visual | Static assets, rich documentation cards, and layout organization dividers |
---
## 🏗️ Architecture
```
┌──────────────────────────┐ ┌──────────────────────┐
│ React Frontend (SPA) │◄──WS──► │ Go Backend │
│ Vite + Tailwind CSS + │◄──API─► │ Single Binary │
│ DaisyUI │ │ (Chi Router) │
└──────────────────────────┘ └──────────┬───────────┘
│
┌──────────┴───────────┐
│ │
┌──────▼──────┐ ┌──────────▼──────────┐
│ SQLite │ │ MQTT Brokers (N) │
│ (layouts, │ │ TCP / TLS / Auth │
│ configs, │ └─────────────────────┘
│ history) │
└─────────────┘
```
The Go binary serves the embedded React build directly, routing REST API calls, WebSocket streams, and MQTT client connections from a single port (`:8080`).
---
## 📚 Documentation
Deep-dive architecture and development guides are available in the [`docs/`](docs/) directory:
- 📘 **[Payload Shaping & Template Guide](docs/payload-shaping.md)** — Dynamic value extraction, loose JSON parsing, and device examples (Zigbee2MQTT, Tasmota, Shelly).
- 🛠️ **[Panel Architecture & Developer Guide](docs/panel-development-guide.md)** — Anatomy of `PanelDefinition`, UI primitives, validation rules, and step-by-step panel creation tutorial.
- ⚙️ **[Configuration & Seeding Guide](docs/configuration.md)** — Two-tier runtime configuration (env vars, TOML), declarative `seed.json` schema, and GitOps provisioning.
- 🚀 **[Native & Reverse-Proxy Deployment Guide](docs/alternative-deployments.md)** — Systemd service configuration, reverse proxy setup (Apache/Nginx), and sub-path routing.
- ⏰ **[Automations & Cron Engine](docs/automations-and-scheduler.md)** — In-memory scheduling with `gocron v2`, origin attribution, toggle APIs, and retention pruning.
- 🔌 **[WebSocket Protocol Specification](docs/websocket-protocol.md)** — Wire protocol frames, topic subscription multiplexing, and client backpressure.
- 🔐 **[Authentication & TLS Guide](docs/auth-and-tls.md)** — Plain TCP, TLS/SSL, mutual TLS (mTLS), and local test broker matrices.
- 🏗️ **[Backend Broker Workflow](docs/backend-broker-workflow.md)** & **[Publish Correlation Engine](docs/publish-correlation-engine.md)** — Concurrency and message origin attribution.
---
## 🛠️ Tech Stack
- **Frontend**: React 19, TypeScript, Vite, Tailwind CSS v4, DaisyUI v5, react-grid-layout
- **Backend**: Go 1.27, Chi Router, Eclipse Paho MQTT
- **Database**: SQLite (pure Go via `modernc.org/sqlite`, WAL mode)
- **Scheduling & Realtime**: `gocron v2`, Gorilla WebSocket
- **Deployment**: Single binary, Alpine Docker container (`ghcr.io/jmischler72/mqtt-dashboard`)
---
## 📄 License
Distributed under the [GPL-3.0 License](LICENSE.txt).
If you find MQTT Dashboard useful, **please consider giving it a ⭐ on GitHub!**