Need a local MQTT instance on your machine? Want to integrate Node-Red too? Docker makes this incredibly simple. I'll show you exactly how to get everything up and running with minimal effort.

Before we begin, verify that Docker is properly installed on your system. You can download Docker Desktop from the official website where you'll also find comprehensive installation instructions.

I also suggest installing just, a useful tool that simplifies running commands from your terminal with minimal typing.

Create a new directory and add the following compose.yml file :

services:
  mosquitto:
    image: eclipse-mosquitto
    ports:
      - "1883:1883/tcp"
      - "8090:8090"
    volumes:
      - ./mosquitto/mosquitto.conf:/mosquitto/config/mosquitto.conf
    environment:
      - TZ=Europe/Zurich

  node-red:
    image: nodered/node-red
    ports:
      - "1880:1880"
    volumes:
      - ./node-red/data:/data
    environment:
      - TZ=Europe/Zurich
    links:
      - "mosquitto:mqtt-broker"
      - "mosquitto:mqtt"
      - "mosquitto:broker"

Adapt the timezone to your location.

Create a directory mosquitto and add the following mosquitto.conf file :

# Config file for mosquitto
listener 1883
protocol mqtt
listener 8090
protocol websockets
allow_anonymous true

Create another directory named node-red and add the following Dockerfile :

FROM nodered/node-red

RUN npm install @flowfuse/node-red-dashboard
RUN npm install @flowfuse/node-red-dashboard-2-ui-led

Within your node-red directory, create a new empty folder named data which will serve as the storage location for all your project data.

Finally, add a justfile with the following content :

up target="":
    docker compose up {{ target }}

up-rebuild target="":
    docker compose up --build --force-recreate {{ target }}

The content of your directory should look like this :

.
├── compose.yml
├── justfile
├── mosquitto
│   └── mosquitto.conf
└── node-red
    ├── data
    └── Dockefile

To start your server, just type the following command :

just up

You should see something like this :

docker compose up 
[+] Running 3/3
 ✔ Network mosquitto-nodered_default        Created
 ✔ Container mosquitto-nodered-mosquitto-1  Created
 ✔ Container mosquitto-nodered-node-red-1   Created
Attaching to mosquitto-1, node-red-1
mosquitto-1  | mosquitto version 2.0.21 starting
mosquitto-1  | Config loaded from /mosquitto/config/mosquitto.conf.
mosquitto-1  | Opening ipv4 listen socket on port 1883.
mosquitto-1  | Opening ipv6 listen socket on port 1883.
mosquitto-1  | Opening websockets listen socket on port 8090.
mosquitto-1  | mosquitto version 2.0.21 running
node-red-1   | 
node-red-1   | Welcome to Node-RED
node-red-1   | ===================
node-red-1   | 
node-red-1   | [info] Node-RED version: v4.0.9
node-red-1   | [info] Node.js  version: v20.19.0
node-red-1   | [info] Linux 6.10.14-linuxkit arm64 LE
node-red-1   | [info] Loading palette nodes
node-red-1   | [info] Settings file  : /data/settings.js
node-red-1   | [info] Context store  : 'default' [module=memory]
node-red-1   | [info] User directory : /data
node-red-1   | [warn] Projects disabled : editorTheme.projects.enabled=false
node-red-1   | [info] Flows file     : /data/flows.json
node-red-1   | [info] Creating new flow file
node-red-1   | 
node-red-1   | ---------------------------------------------------------------------
node-red-1   | Your flow credentials file is encrypted using a system-generated key.
node-red-1   | 
node-red-1   | If the system-generated key is lost for any reason, your credentials
node-red-1   | file will not be recoverable, you will have to delete it and re-enter
node-red-1   | your credentials.
node-red-1   | 
node-red-1   | You should set your own key using the 'credentialSecret' option in
node-red-1   | your settings file. Node-RED will then re-encrypt your credentials
node-red-1   | file using your chosen key the next time you deploy a change.
node-red-1   | ---------------------------------------------------------------------
node-red-1   | 
node-red-1   | [info] Server now running at http://127.0.0.1:1880/
node-red-1   | [warn] Encrypted credentials not found
node-red-1   | [info] Starting flows
node-red-1   | [info] Started flows

The MQTT broker is available at :

  • mqtt://:1883
  • ws://:8090

The node-RED is available at http://127.0.0.1:1880/

Press Ctrl+C to stop the server

If you just want to start the MQTT broker, type the following command :

just up mosquitto

If you need to rebuild the container, type the following command :

just up-rebuild

When configuring Node-RED, simply reference your MQTT broker using the hostname mosquitto and the port 1883.

Image description

Note : If you prefer, you can also use mqtt-broker, mqtt or broker as a hostname instead of mosquitto.

Enjoy your MQTT Broker and Node-RED instance.