Requirements
You’ll need:
- A Raspberry Pi, I used a 4B 4GB
- A micro SD card, I used a 64GB card
Set up Raspberry OS
First, install the Pi with the standard 64-bit Bookworm Raspberry Pi OS.
Either use the desktop edition and attach a screen, keyboard and mouse, or use the Lite version and set up SSH so you can log in to the Pi remotely (this is useful on the desktop as well).
In either case, set the host name to homeassistant. I set my user name to rebeam - this is used below, replace as necessary with your own user name.
Also make sure to set up your WiFi details in Imager if needed, although a wired ethernet connection is better for reliability if possible.
Log in to ssh to test (e.g. ssh username@homeassistant.local - you can omit the username if it matches the on on you PC).
To avoid having to type in the password every time, close the ssh session and then send your key with ssh-copy-id rebeam@homeassistant.local, substituting your user name on the pi for rebeam. If you’ve not yet generated a key, see this Github guide.
Network setup
For ease of use, set a static IP for the raspberry pi - the best way is usually to get your router to assign a specific IP based on mac address.
This will also resolve issues if the homeassistant.local address doesn’t work for you, since you can use the static IP directly.
Set up Docker
We’ll install docker so we can run home assistant and MQTT in containers. I used these instructions and checked against the official docker install script docs and post-installation steps for Linux. One addition below is to restart the Pi after running sudo apt upgrade - when I attempted to install docker, it gave errors that were only resolved by a restart.
The summary is:
Update package index, upgrade installed packages:
sudo apt update
sudo apt upgrade
Restart:
sudo reboot -n
Run the docker install script:
curl -sSL https://get.docker.com | sh
Add your user to the docker group - note that if you are using a user name other than rebeam, you should change this below:
sudo usermod -aG docker rebeam
Log out:
logout
Log back in to get access to newly added group, and check you are in the docker group - this should print a list of groups including “docker”:
groups
Run “hello world” docker container to check it works:
docker run hello-world
Set up Docker containers for Home Assistant and Mosquitto
There’s a good guide on pimylifeup, but the home assistant docs specify additional options, so we’ve included these.
Create a directory named containers in your home directory:
cd ~
mkdir containers
cd containers
Create the following file as docker-compose.yml:
services:
homeassistant:
container_name: homeassistant
image: "ghcr.io/home-assistant/home-assistant:stable"
volumes:
- ./volumes/homeassistant-config:/config
- /etc/localtime:/etc/localtime:ro
- /run/dbus:/run/dbus:ro
devices:
- /dev/ttyUSB0:/dev/ttyUSB0
restart: unless-stopped
privileged: true
network_mode: host
mosquitto:
image: eclipse-mosquitto
restart: unless-stopped
container_name: mosquitto
volumes:
- ./volumes/mosquitto:/mosquitto
ports:
- 1883:1883
- 9001:9001
Note: We include the /dev/ttyUSB0 in case you have a USB Zigbee dongle.
Start the containers:
docker compose up -d
You can now create a config file in the mosquitto volume - note we are using sudo since the directories will have been created by docker running as root, so our normal user doesn’t have permission:
cd ~/containers/volumes/mosquitto
sudo mkdir config
sudo nano ./config/mosquitto.conf
Then paste the following minimal configuration - the following sets up anonymous access for anyone on your network, if you want you can configure a password here instead:
# following two lines required for > v2.0
allow_anonymous true
listener 1883
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
You can then restart the containers from the ~/containers dir:
cd ~/containers
docker compose restart
You can now also log in to Home Assistant at homeassistant.local:8123 and set up your admin password.
Test Mosquitto
We can use any mqtt client. MQTT Explorer looks like a good option.
For simplicity if you already have npm installed, you can use the mqtt.js command line client. Install it with:
npm install mqtt -g
You can now subscribe to messages from the mosquitto broker (server) - replace hostname.local with your server’s IP or appropriate local domain name:
mqtt sub -t 'hello' -h 'hostname.local' -v
Leave this running, and in another terminal we can publish a message:
mqtt pub -t 'hello' -h 'hostname.local' -m 'from MQTT.js'
This should print the message “hello from MQTT.js” in the first terminal window where we subscribed to the message.
Integrate MQTT with Home Assistant
We now need to let Home Assistant know about our MQTT broker so it can send/receive messages. We use the MQTT integration for this.
First, log in to Home Assistant, and navigate to “Settings” on the left pane, then “Devices & Services”.
Click ”+ ADD INTEGRATION” in the bottom right, then search for “MQTT” in the dialog that pops up. Select “MQTT”, then “MQTT” again.
This should display a dialog for MQTT details. Enter “localhost” for the “Broker”, leave “Port” as 1883, and leave “Username” and “Password” blank, then click “SUBMIT”. This should show a “Success” dialog, click “FINISH”.
To test this is working, navigate to “Settings” on the left pane, then “Devices & Services”. Find “MQTT” in the grid of devices and click it. Now click “Configure”, and you should see a page allowing you to publish and listen to messages. Start up and connect MQTT Explorer, or listen on the command line with mqtt sub -t 'home-assistant-test' -h 'houseassistant.local' -v. Then fill out the “Publish a packet” fields, with “Topic” as “houseassistant.local” and “Payload” as some test message, and click “PUBLISH”. You should see the message pop up in MQTT Explorer or on the command line where mqtt is running.
Migrating Home Assistant between Pis
If you are transferring from another container installation of Home Assistant, you can do this by just zipping up the volume directory on the original Pi:
cd ~/containers/volumes
sudo tar -zcvf homeassistant-config.tar.gz homeassistant-config
Then on the new Pi, stop the home assistant container:
cd ~/containers
docker compose down
Copy the homeassistant-config.tar.gz file from the old Pi to the new one, placing it in the ~/containers/volumes directory. Then rename the existing volume directory and replace with the contents of the tar:
cd ~/containers/volumes
sudo mv homeassistant-config homeassistant-config-original
sudo tar -zxvf homeassistant-config.tar.gz
Finally, restart the containers on the new Pi:
cd ~/containers
docker compose up -d
You should now have an identical copy of the old Home Assistant installation - if you’re using a Zigbee adaptor, make sure to move it to the new Pi, and restart the containers.