ha-docker-mqtt.md

Home Assistant Core in Docker with Mosquitto broker

​This requires basic knowledge of linux, bash, nano and Docker itself.

Basic Setup

In this example we are using /home/user/ha-docker-mqtt as the root path so all commands should be run from there (your chosen path!).

Create the required directories

mkdir -p homeassistant/config
mkdir -p mosquitto/{config,data,log}

Create the mosquitto.conf file

nano mosquitto/config/mosquitto.conf

Paste the following;

persistence true
persistence_location /mosquitto/data 

log_dest stdout

allow_anonymous false
password_file /mosquitto/config/passwd

Create an empty password file;

touch mosquitto/config/passwd

Create the docker compose file

nano docker-compose.yaml

Paste the following content;

services:
  mosquitto:
    image: eclipse-mosquitto:latest
    container_name: ha-test-mosquitto
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log

  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: ha-test-homeassistant
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
      - /etc/timezone:/etc/timezone:ro

Set permissions

sudo chown -R 1883:1883 mosquitto
sudo chmod 700 mosquitto/config
sudo chmod 600 mosquitto/config/passwd

Create a Mosquitto user

docker run --rm -it \
-v "$(pwd)/mosquitto/config:/mosquitto/config" \
eclipse-mosquitto mosquitto_passwd \
/mosquitto/config/passwd ha-mqtt

Replace 'ha-mqtt' with your desired username. You'll be prompted for a password.

Pull and launch the container

docker compose up

Watch the console - if everything is good you can detach (press d) from the console if you're running a newer version of docker or press CTRL+C and then launch again with docker compose up -d to launch in daemon mode.

Configure Home Assistant

Add the MQTT integration

Manual steps:

• Open your browser and go to http://<YourIPAddress:8123
• Navigate to Setttings -> Integrations, devices, entities and helpers
• Click on "Add integration"
• Search for MQTT
• Select the "MQTT" option at the top

Add the MQTT broker

• In the "Broker" field use localhost
• Leave the port as 1883
• In the username field, enter the user you created earlier, in our example ha-mqtt
• In the password field, enter your chosen password, in our example we again use ha-mqtt
• Click on "Submit"

You now have Home Assistant Core linked to Mosquitto MQTT.

If you want the MQTT server to be available outside of Home Assistant, you need to allow remote connections to Mosquitto;

nano mosquitto/config/mosquitto.conf

Add the following line to the configuration file;

listener 1883 0.0.0.0 (IPv4)
listener 1883 :: (IPv6)

Restart the Mosquitto container;

docker restart ha-test-mosquitto

The MQTT server will then be available on the IP address of the host, for example;

192.168.1.187:1883

NOTE: This isn't necessary unless you absolutely need something else to access the MQTT server outside of Home Assistant (e.g. you have a device which can 'speak' MQTT and needs broker details).