Mosquitto MQTT broker with Docker Compose

Mosquitto is a lightweight MQTT message broker. In a self-hosted smart home stack it sits at the center — Zigbee2MQTT and Z-Wave JS UI publish device state to it, and Home Assistant subscribes to receive updates.

Zigbee2MQTT ─┐
              ├─► Mosquitto (1883) ─► Home Assistant
Z-Wave JS UI ─┘

Mosquitto holds no device state itself. All three clients connect independently. Retained messages (retain: true) allow clients to re-sync immediately after a Mosquitto restart.

Compose

services:
  mosquitto:
    image: eclipse-mosquitto:latest
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - '1883:1883'
      - '9001:9001' # WebSocket — remove if not needed
    volumes:
      - ./config:/mosquitto/config
      - ./data:/mosquitto/data
      - ./log:/mosquitto/log

Configuration

Create config/mosquitto.conf:

listener 1883
listener 9001
protocol websockets

persistence true
persistence_location /mosquitto/data/

log_dest file /mosquitto/log/mosquitto.log
log_type error
log_type warning
log_type notice
log_type information

# Anonymous access — fine for a local-only broker
allow_anonymous true

# To require credentials instead:
# allow_anonymous false
# password_file /mosquitto/config/passwd

Authentication (optional but recommended)

# Create the password file (use -c only on the first user)
docker exec -it mosquitto \
  mosquitto_passwd -c /mosquitto/config/passwd <username>

# Add additional users
docker exec -it mosquitto \
  mosquitto_passwd /mosquitto/config/passwd <username2>

Update mosquitto.conf:

allow_anonymous false
password_file /mosquitto/config/passwd

Restart: docker compose restart mosquitto

Configure the same credentials in Zigbee2MQTT and Z-Wave JS UI.

Verify the broker

# Subscribe in one terminal
docker exec -it mosquitto \
  mosquitto_sub -h localhost -t "test/#" -v

# Publish from another
docker exec -it mosquitto \
  mosquitto_pub -h localhost -t "test/hello" -m "world"

Ports

See also

• Zigbee2MQTT — Zigbee coordinator that publishes to this broker
• Z-Wave JS UI — Z-Wave controller that publishes to this broker
• Home Assistant — subscribes to device state via this broker