Getting Started

BunkerM is a self-hosted MQTT management platform that bundles Eclipse Mosquitto with a web dashboard into a single Docker container. This guide covers system requirements, installation options, first login, and creating your first MQTT client.

System Requirements

Before deploying BunkerM, make sure your system meets these requirements:

• Docker: version 19.03 or higher
• CPU: 1+ cores
• RAM: 512 MB minimum (1 GB+ recommended)
• Storage: 1 GB minimum free space
• Ports: 1900 (MQTT) and 2000 (Web UI) must be available

Installation

Basic Docker run

The simplest way to start BunkerM - one command, everything included:

docker run -d -p 1900:1900 -p 2000:2000 bunkeriot/bunkerm:latest

This runs BunkerM in detached mode, maps port 1900 for MQTT connections, and port 2000 for the web UI.

With persistent storage (recommended)

For any environment where you want to keep your data across container restarts, add Docker volumes:

docker run -d \
  -p 1900:1900 \
  -p 2000:2000 \
  -v bunkerm_data:/nextjs/data \
  -v mosquitto_data:/var/lib/mosquitto \
  -v mosquitto_conf:/etc/mosquitto \
  --name bunkerm \
  --restart unless-stopped \
  bunkeriot/bunkerm:latest

Without volumes, all clients, ACL rules, and configuration are lost when the container stops. See Persistent Storage for a full explanation.

Docker Compose

Create a docker-compose.yml file:

version: "3.8"
services:
  bunkerm:
    image: bunkeriot/bunkerm:latest
    ports:
      - "1900:1900"
      - "2000:2000"
    volumes:
      - bunkerm_data:/nextjs/data
      - mosquitto_data:/var/lib/mosquitto
      - mosquitto_conf:/etc/mosquitto
    restart: unless-stopped

volumes:
  bunkerm_data:
  mosquitto_data:
  mosquitto_conf:

Then start it:

docker compose up -d

Remote access

If you need to access BunkerM from a remote machine or expose it on your network, pass the host address as an environment variable:

docker run -d -p 1900:1900 -p 2000:2000 \
  -e HOST_ADDRESS=<YOUR_IP> \
  bunkeriot/bunkerm:latest

Replace <YOUR_IP> with your server's IP address or domain name.

First Login

Once the container is running, open your browser and navigate to:

http://localhost:2000

You will see the BunkerM login page. Use these default credentials:

• Email: admin@bunker.local
• Password: admin123

Dashboard Overview

After logging in you arrive at the main dashboard, which gives an overview of your broker's state:

• Connected Clients - number of currently active MQTT connections
• Message Statistics - publish rate and message throughput
• Broker Status - whether Mosquitto is running normally
• Recent Activity - latest connection and log events

Creating Your First MQTT Client

BunkerM uses Mosquitto's dynamic security plugin. Every device that connects to the broker needs its own client account. Here is how to create one:

1. In the sidebar, go to ACL > Clients.
2. Click Add Client.
3. Enter a Client ID - the MQTT client identifier (e.g., sensor-kitchen-01).
4. Enter a Username and Password - the credentials the device will use to connect.
5. Click Save.

The client is immediately active. Configure your MQTT device to connect to localhost:1900 (or your server's address) with the username and password you just set.

Verifying the Connection

To confirm a device is connected, go to ACL > Connected Clients in the sidebar. Any device currently connected to the broker appears here with its client ID, IP address, and connection details.

Troubleshooting

• Web UI not accessible: verify that port 2000 is not used by another application. Check with docker logs bunkerm.
• MQTT broker not reachable: verify port 1900 is free and not blocked by a firewall.
• Container fails to start: run docker logs <container_id> to see the error.
• Client cannot connect: check ACL > Clients to confirm the account exists and is enabled.