MQTT with Eclipse Mosquitto (Official Docker Image)

December 30, 2025

I have’ had a version of mosquitto running for some time. It’s a docker setup and it just worked. The author of the docker container has moved in a direction I’m not following.

MQTT is a protocol for enabling devices that are “smart” to talk to your network and other devices or service you might have running in your home. There’s no need to expose this outside your internal network (unless you’re doing complicated and difficult things in which case it’s very unlikely that you need this posting). Basically it’s a message queuing system.

Mosquitto is a broker for these messages, systems send “messages”, like an event (“the light turned on”), the messages are then passed to whatever system is subscribed to those messages. These messages can be encoded and or connected to other things that then enable automation.

So if you have smart lights or a smart vacuum or something then this can be handy. Especially if you’re running something like Home Assistant which knows what to do with these messages including sending and receiving them.

Setting up Mosquitto was significantly less painful than I’d originally believed it would be. I have now tried BunkerM twice and both times it was too much trouble to work with. Eclipse Mosquitto is surprisingly easy to setup. However you will need to setup both ends of this for it to work, that is to say on the hardware sending messages and the server listening and responding. In my case I have a posting here that sets up the other end for a robot vacuum with valetudo installed, the post also talks about setting up Home Assistant to handle the messages.

I have tried Eclipse Mosquitto before as well but for some reason (didn’t find the right tutorial?) I could not make it work. This time I got it, so I’ll write down my experience here and hope that it works again if I need it.

Speaking of the right tutorial, this article was all I needed. I followed the steps, setup a user and all was well. I setup a second user as I’d done that in the past and once I logged in from home assistant and the vacuum with this new user it all just worked Nothing else needed changing.

My compose file is like this

services:
  mosquitto:
    image: eclipse-mosquitto
    container_name: mosquitto
    volumes:
      - ./config:/mosquitto/config
      - ./data:/mosquitto/data
      - ./log:/mosquitto/log
    ports:
      - 1883:1883
      - 9001:9001
    networks:
      - home
    stdin_open: true
    tty: true
    restart: unless-stopped

networks:
  home:
    external: true

and my mosquitto.conf is like this

#base config, ports, protocol, persistance
listener 1883
listener 9001
protocol websockets
persistence true
persistence_file mosquitto.db
persistence_location /mosquitto/data/

#Authentication
allow_anonymous false
password_file /mosquitto/config/afile

In Home Assistant to reset the username and password and make it log in again you end up in

Settings -> Devices & Services -> MQTT

from there you pick the vertical elipsis by the first line for the MQTT service you’re messing with (there can only be one) and choose “Reconfigure” (it’s a ways down the list). Here you can set username and password as well as address for your MQTT service and force a new login.

As always your mileage may vary.