Home Assistant Install Docker

/ Comments off

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.

  1. Home Assistant Docker Install Hassio
  2. Home Assistant Install On Docker Windows 10
  3. Install Docker Mac
  4. Hass Docker

Getting add-ons and snapshots on Home Assistant without using Home Assistant OS can be tricky, however today I will show you how to install Home Assistant on. Install Home Assistant Container. These below instructions are for an installation of Home Assistant Container running in your own container environment, which you manage yourself. Any OCI compatible runtime can be used, however this guide will focus on installing it with Docker.

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


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

mkdir docker
mkdir scripts
cd scripts

Use your favorite editor, mine is mcedit.

Portainer ( $HOME/scripts/run_portainer )

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

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:

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

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= mqtt

Now you can start it for the first time:

cd $HOME/scripts

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 Docker Install Hassio

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

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

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.

Home Assistant Install On Docker Windows 10

We will look into this very soon 🙂

I hope that you’ve landed here before spending hours/days trying to find a solution as to why you can’t forward the Home Assistant port in Docker. The solution is frustratingly easy.

Install Docker Mac



The install Home Assistant in docker on Windows instructions are great, with one exception. It explains the required prerequisites to make sure docker has access to a host disk. However, those instructions have outdated instructions to setup the port-forward rules, which ultimately makes it a waste of time.

They share this command (don’t use):

It installs fine and spins up the container. The docs say to next use netsh and manually add port-forward rules, but it doesn’t work (and you can seriously mess stuff up with netsh).


Instead, you can just tell docker to port forward it for you when you initially create the container by using the -p switch. Since Home Assistant uses port 8123, you use -p 8123:8123 in the command.

Here’s the one-liner that does both the install, and the port forward, at the same time:

Hass Docker

After that, you’re ready to go! Open a browser on the host PC and navigate to http://localhost:8123.

Important-p 8123:8123 parameter must be used before--name. Otherwise, it gets used in the container instead of Docker, which results in a broken install because the container doesn’t know what -p is. I wasted two days before discovering this, thanks to help from Alex Sorokoletov and Martin Sundhaug. I owe them some 🍻.