DJBenson/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

Set permissions

sudo chown -R 1883:1883 mosquitto
sudo chmod 700 mosquitto/config
sudo chmod 600 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: main
    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: main
    ports:
      - 8123:8123
    volumes:
      - ./homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
      - /etc/timezone:/etc/timezone:ro

This file makes some assumptions;

It uses a network called "main" - replace this with your network or set it to "host"
We don't expose a port for Mosquitto - we don't need it - we will refer to the container by its name (ha-test-mosquitto) from Home Assistant

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 add the name of your Mosquitto container (or the IP address of the host) - in our example it's ha-test-mosquitto
If you're using the container name or did not change the default MQTT port, leave this as 1883 or enter the port you used if you did change the port
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.