I will describe quickly how to set-up and prepare RPI4 for Home Assistant. We will use this as a base to install docker and configure everything.
You can use the imager from here , but use the lite image. You don’t need the desktop version.
Install Raspberry OS
Don’t forget to update and upgrade all packages:
apt update && sudo apt upgrade , then reboot.
When you first boot, you can configure the system with
Don’t forget to start ssh, if you need remote ssh access.
We’ll assume you execute everything with a pi user or another who has sudo privileges
sudo apt install docker.io
Don’t forget to add yourself to docker group, so you can execute docker commands without sudo:
sudo usermod pi -a -G docker
(replace pi with the user you’re using, if needed). You need to logout and login for the changes to take effect.
After that, what I do is install a few scripts that will help me manage everything
Use your favorite editor, mine is mcedit.
#!/bin/bash docker pull portainer/portainer-ce docker stop portainer docker rm portainer docker run --name=portainer \ --restart=unless-stopped -d \ -l "diun.enable=true" \ -v /var/run/docker.sock:/var/run/docker.sock \ -v $HOME/docker/portainer:/data \ -p 9000:9000 \ -p 8000:8000 \ portainer/portainer-ce
$HOME/docker with the actual location where you want to store your docker files locally ( if you don’t it will create in your home folder ). This helps next time when you’re rebuilding docker instances so you don’t lose anything.
Make it executable and run it:
chmod +x run_portainer
This will start portainer on port 9000. You can open it via web browser on
http://IP:9000 and set it up. It’s a great software to monitor at and manage your docker environment.
MQTT is really important piece of software, that will allow all our gateways and sensors to actually send data to Home Assistant. Edit
#!/bin/bash docker stop mqtt ; docker rm mqtt docker pull eclipse-mosquitto docker run --name mqtt -d --restart=unless-stopped \ -p 1883:1883 \ --net mqtt \ --ip 192.168.20.10 \ -l "diun.enable=true" \ -v $HOME/docker/mqtt/config:/mqtt/config \ -v $HOME/docker/mqtt/log:/mqtt/log \ -v $HOME/docker/mqtt/data/:/mqtt/data/ \ eclipse-mosquitto
Of course, replace
$HOME/docker (if you need to).
chmod +x $HOME/scripts/run_mqtt
Do not run it yet. We need to configure user and password first.
mkdir -p mqtt/config mqtt/log mqtt/data
Then create a file, called
mosquitto.conf with the following content
port 1883 password_file /mqtt/config/passwd allow_anonymous false
Create the mqtt network. Here we use static IP address for the MQTT server, so that the other container we can configure to use that IP address. If you want, you can omit that, but it’s better to just leave it.
docker network create -d bridge --subnet=192.168.20.0/24 mqtt
Now you can start it for the first time:
Now it’s time to generate password. Enter into the container with:
docker exec -it mqtt /bin/sh
mosquitto_passwd -c /mqtt/config/passwd hass
Enter the password when prompted twice. Try to use generated or hard to guess password. You can add as many users you want, just omit the
-c flag next time.
You can now exit the container with
ctrl + d. Your MQTT server is configured. We’ll use that for Home assistant configuration.
Home assistant itself (
You can configure several things in this shell script, but we’ll get to that. For now, use the basics
#!/bin/sh docker pull homeassistant/home-assistant docker stop hass; docker rm hass docker run -d --name=hass \ --net=host \ --restart=unless-stopped \ -v $HOME/docker/hass:/config \ homeassistant/home-assistant
Here we tell it to use host network, so we don’t need to explicitly map ports. This will have some other advantages later. Save it,
chmod +x $HOME/scripts/run_hass and run it.
cd $HOME/scripts && ./run_hass
You can now configure Home Assistant initially from
http://IP:8123/ , replace IP with rpi’s IP address.
After doing this, open
$HOME/docker/hass/configuration.yaml and add the following section
mqtt: broker: localhost client_id: hass username: hass password: PASSWORD_HERE discovery: true discovery_prefix: homeassistant birth_message: topic: 'hass/status' payload: 'online' will_message: topic: 'hass/status' payload: 'offline'
Of course, replace
PASSWORD_HERE with your MQTT password.
You can now restart home assistant from within the web interface or via
When you’re finished, you will have your first Home Assistant setup. While pretty basic, it’s already ready to be customized.
We will look into this very soon 🙂
3 comments On Home Assistant – docker installation
Great tutorial. Can you please explain how to interstate duckdns docker image to remote accessing home assistant core.
Great guide. Thanks. I hit one problem in the run_hass script. It seems that docker now needs the –privilieged switch (since HA 2021.7 – see https://www.reddit.com/r/homeassistant/comments/og2oss/ha_docker_failing_to_start_after_updating_to/)
Hopefully this comment will be useful to some other person that finds your guide.
Nice tutorial, thank you!
I have only changed cmd line for mqtt: “/usr/sbin/mosquitto -c /mqtt/config/mosquitto.conf”