How to Set Up Mosquitto MQTT Broker on Raspberry Pi with Docker

MQTT is a lightweight messaging protocol designed for IoT devices. Eclipse Mosquitto is the most widely used open-source MQTT broker, and running it on a Raspberry Pi gives you a dedicated, always-on message hub for your sensors and smart devices.

Prerequisites

A Raspberry Pi 3 or newer running Raspberry Pi OS
Docker and Docker Compose installed (see our Docker setup guide)
SSH access or a terminal on the Pi

Update your system first:

Bash

sudo apt update && sudo apt upgrade -y

Step 1: Create the Project Directory

Bash

mkdir -p ~/mosquitto/config
mkdir -p ~/mosquitto/data
mkdir -p ~/mosquitto/log
cd ~/mosquitto

Step 2: Create the Mosquitto Configuration File

Create the configuration file at ~/mosquitto/config/mosquitto.conf:

Code

persistence true
persistence_location /mosquitto/data/

log_dest file /mosquitto/log/mosquitto.log
log_dest stdout

listener 1883
listener 9001
protocol websockets

allow_anonymous false
password_file /mosquitto/config/password_file

This configuration:

Enables persistent message storage
Opens port 1883 for standard MQTT connections
Opens port 9001 for WebSocket connections
Disables anonymous access and requires a password file

Step 3: Create the Docker Compose File

Create docker-compose.yml in the ~/mosquitto directory:

YAML

services:
  mosquitto:
    image: eclipse-mosquitto
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"
      - "9001:9001"
    volumes:
      - ./config:/mosquitto/config
      - ./data:/mosquitto/data
      - ./log:/mosquitto/log

Step 4: Create a Password File

Before starting the broker, you need to create at least one user. First, start the container temporarily to access the mosquitto_passwd tool:

Bash

cd ~/mosquitto
docker compose run --rm mosquitto mosquitto_passwd -c /mosquitto/config/password_file myuser

You will be prompted to enter and confirm a password. This creates the password_file with the user myuser.

To add additional users later (without overwriting the file), omit the -c flag:

Bash

docker compose exec mosquitto mosquitto_passwd /mosquitto/config/password_file anotheruser

Step 5: Start the Broker

Bash

cd ~/mosquitto
docker compose up -d

Verify it is running:

Bash

docker ps

Check the logs to confirm the broker started without errors:

Bash

docker logs mosquitto

You should see output indicating that listeners are active on ports 1883 and 9001.

Step 6: Test with Pub/Sub Commands

Install the Mosquitto client tools on your Pi (or any machine on the network):

Bash

sudo apt install -y mosquitto-clients

Open two terminal windows. In the first, subscribe to a topic:

Bash

mosquitto_sub -h localhost -p 1883 -t "test/topic" -u myuser -P yourpassword

In the second, publish a message:

Bash

mosquitto_pub -h localhost -p 1883 -t "test/topic" -m "Hello from Pi!" -u myuser -P yourpassword

You should see Hello from Pi! appear in the subscriber terminal.

Using MQTT with Other Services

Mosquitto pairs well with many self-hosted services:

Home Assistant -- add the MQTT integration and point it to <your-pi-ip>:1883
Node-RED -- use the MQTT input/output nodes for automation flows
Custom sensors -- ESP32 and ESP8266 boards can publish sensor data directly to your broker

Troubleshooting

Connection refused on port 1883: Make sure the container is running with docker ps. Check docker logs mosquitto for startup errors.
Authentication errors: Verify the username and password match what you set with mosquitto_passwd. The password file path in mosquitto.conf must match the mounted volume path.
WebSocket not connecting: Confirm port 9001 is mapped in your compose file and that the protocol websockets line is under the listener 9001 directive.
Permission denied on log/data directories: Run sudo chown -R 1883:1883 ~/mosquitto/data ~/mosquitto/log to match the Mosquitto container user.
Firewall issues: If connecting from another machine, ensure the ports are open: sudo ufw allow 1883 && sudo ufw allow 9001.

Conclusion

A Mosquitto MQTT broker on your Raspberry Pi gives you a reliable, self-hosted messaging backbone for all your IoT projects. With password authentication enabled and Docker keeping the deployment clean, you have a solid foundation to build on. Add sensors, connect Home Assistant, or wire up Node-RED flows -- your MQTT broker is ready to handle it all.