# 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

[![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=mqtt)

#### 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"

<img width="452" height="576" alt="image" src="https://gist.github.com/user-attachments/assets/8e51c593-a871-4552-9343-4dc441bdeebf" />

<img width="392" height="188" alt="image" src="https://gist.github.com/user-attachments/assets/bfa4c31c-c52f-4a94-af39-aae83370d61e" />

<img width="1447" height="329" alt="image" src="https://gist.github.com/user-attachments/assets/f4cea356-b293-4878-ae76-aee37ac43983" />


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).