Home Assistant – docker installation

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

sudo raspi-config

Don’t forget to start ssh, if you need remote ssh access.

Install Docker

We’ll assume you execute everything with a pi user or another who has sudo privileges

Execute

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

cd
mkdir docker
mkdir scripts
cd scripts

Use your favorite editor, mine is mcedit.

Portainer ( $HOME/scripts/run_portainer )

#!/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

Replace $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
./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 ( $HOME/scripts/run_mqtt )

MQTT is really important piece of software, that will allow all our gateways and sensors to actually send data to Home Assistant. Edit $HOME/scripts/run_mqtt:

#!/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.

cd $HOME/docker
mkdir -p mqtt/config mqtt/log mqtt/data
cd mqtt/config

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:

cd $HOME/scripts
./run_mqtt

Now it’s time to generate password. Enter into the container with:

docker exec -it mqtt /bin/sh

Then execute

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 ( $HOME/scripts/run_hass )

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 run_hass command.

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 🙂