Home Assistant Raspberry Pi Docker Setup

Home Assistant Raspberry Pi Docker Setup

The objective of this article is to install all tools that you need for your smart home applications via Docker. These tools are:

  • Home Assistant as overall smart home dashboard to control your smart devices.
  • Mosquitto as MQTT broker to receive data from self build sensors in your home.
  • InfluxDB as database to store MQTT data.
  • Grafana to create time series dashboards based on data in the InfluxDB database.
Docker Home Assistant

Table of Contents

This article belongs to a series of currently 5 articles about the topic Home Assistant. The following picture shows how the articles are related to each other.

Home Assistant Article Overview

The other articles are the following:

The following table gives you an overview of all components and parts that I used for this tutorial. If you want to support my work, you can buy something from the following links and I will earn a small commission. This does not affect the price you pay for the products.

If you are interested in components and parts that I used in other tutorials, visit the components and parts page.

 Raspberry Pi 4 Model B KitAmazon AliExpress
ORRaspberry Pi 4 Model BAmazonBanggoodAliExpress
ORRaspberry Pi 3 B+ KitAmazon AliExpress
ORRaspberry Pi 3+AmazonBanggoodAliExpress

In my opinion, the installation of Home Assistant via Docker on the Raspberry Pi is the more advanced way of using Home Assistant because this installation method allows you to run more applications or use cases on the same Pi.

Before we start with the setup let us look for the advantages and disadvantages of this installation method compared to the installation of Home Assistant via HASS.io.



You can run multiple other applications and use cases in other docker containers.

There are no add-ons available like Graphana or InfluxDB. But we will install these add-ons in separate docker containers.

If something break and you have to reinstall Home Assistant then the setup of a new docker container is faster compared to a re-installation of the OS.


In our case, we want to run Home Assistant on a Raspberry Pi in a Docker container. In this tutorial I assume that you already installed Raspbian Buster on your Pi. If you are not familiar with the initial setup of the Raspberry, then this tutorial of the headless Raspberry Pi setup is the right for you. I recommend to install Raspbian Buster Lite because we do not need the graphical user interface but only the command line. The following part of the tutorial expect that your have Raspbian installed, an internet connection and SSH activated.

Docker on the Raspberry Pi

In this article is not a docker guide because there are already very good articles about docker in general. But I will summarize the fundamentals of docker that you understand why we use it.

Docker is a set of platform as a service (PaaS) products that enables the isolation of applications through container virtualization. A container is an isolated image of software, libraries, configuration files and any other data to run the container application. Container can communicate with each other through predefined channels and also with the main operation system to load a predefined configuration for example. The main advantage of docker compared to virtual machines is that all containers are run by a single operating system kernel. This ensures that all resources are used at the best.

In our smart home use case, we use the Raspberry Pi as infrastructure of Docker with Raspbian Buster Light as host operating system. Between the operating system and the containers where the applications are running is Docker responsible for the creation, deletion and management of images and containers.

Because the Raspberry Pi is based on the ARM architecture, not all Docker images will work. You find all images on the Docker Hub website that allows the filtering of all images based on the architecture. For the Raspberry Pi we choose only the ARM architecture and not ARM 64 because Raspbian Buster is compiled as 32-bit operating system and not able to run 64-bit applications.

Docker Hub ARM architecture

Before we can start downloading images and creating containers, we have to install Docker. Login on your Raspberry Pi via SSH or open the command line interface. The installation of Docker is done is two steps:

  1. Download the Docker installation script
  2. Execute installation script
Docker installation

From the picture we see that Docker version 19.03.8 is installed. Now we have our foundation to install the applications:

  • Home Assistant
  • Mosquitto MQTT broker
  • InfluxDB
  • Grafana

Before we start you find the most used command line functions regarding Docker in the following table.


Command Line Function

Install image X

docker pull <X>

View all Docker images with image ID

docker image ls

Delete Docker image

docker image rm <image ID>

Create a Docker container

docker run <image name>

Start a container

docker start <container name>

Stop a container

docker stop <container name>

View all Docker containers

docker container ls -a

Delete a Docker container

docker container rm <container ID>

Install Home Assistant via Docker

From the official Home Assistant website we get the full installation command

docker run – init -d – name="home-assistant" -e "TZ=America/New_York" -v /home/pi/homeassistant:/config – net=host homeassistant/raspberrypi3-homeassistant:stable
Docker Home Assistant
With the command
docker container ls -a
you see that your Home Assistant Docker container is running with the container name home-assistant.
Docker Home Assistant container

Now we can open Home Assistant in the browser on port 8123 of the Raspberry Pi. In my case the Raspberry Pi has the IP 102 and I start Home Assistant in the browser by starting the URL: Now you see the signup form of Home Assistant where you can define your name, username and password.

Home Assistant signup

To get location based information you have to select your housing location on the following map. With the use of your IP address your location is guessed when you click on the detect button. You can then redirect the map to your exact location. The timezone and the unit system are automatically set to your location but if you prefer other setting you can change them.

Home Assistant Setup Location

On the next and also last page of the Home Assistant setup you can choose different smart devices in your home. If you have for example smart plugs, smart light bulbs or a smart TV that is turned on, you should see them in the current setup page like my Samsung TV is automatically recognized by Home Assistant.

Home Assistant Setup Devices

But you can also add smart devices manually by clicking on the more button and add the devices by their IP address in you local network.

Now you can finish the Home Assistant setup and you see the Home Assistant dashboard. If you are familiar with the HASS.io installation of Home Assistant you maybe miss something because the HASS.io installation as operating system for the Raspberry Pi comes with a Supervisor button on the left sidebar.

Home Assistant HASSio vs Docker

This allows you so make snapshots of the system to save configurations and to restart or shutdown Home Assistant. In our case because we run Home Assistant in a Docker container, we can save the configurations and reboot or shutdown Home Assistant via the Docker application.

One main advantage of the HASS.io installation is the integrated add-on store to install compatible applications. In our case also want to install Mosquitto MQTT boroker, InfluxDB and Grafana but we have to create a new docker container for each of this applications.

Install Mosquitto via Docker

To receive MQTT data in Home Assistant we have to install an MQTT broker. In this tutorial I use the most frequently used MQTT broker Mosquitto. To find the Docker image of Mosquitto, we search for the application on the Docker Hub website. On the right side we see that the image can be pulled via the command:
docker pull eclipse-mosquitto
Docker Mosquitto

Before we can start the container we want to share useful information between the host system and the Docker container. This is important because we want to define an individual configuration for Mosquitto that should be loaded at the creation of the Mosquitto container.

First we create the following folders under a mosquitto folder in your default directory: config, data and log.

Mosquitto tree
In the config folder we create a file called mosquitto.conf with the following command:
nano config/mosquitto.conf
The configuration file has the following context:
pid_file /var/run/mosquitto.pid

persistence true
persistence_location /mosquitto/data/

log_dest file /mosquitto/log/mosquitto.log
log_dest stdout

password_file /mosquitto/config/mosquitto.passwd
allow_anonymous false
Mosquitto config
Now we have to make sure that Mosquitto as a Docker container get the permission to access these folders. This is done by the chown command that stands for change owner. We use the following command to get Mosquitto access to the mosquitto folder via port 1883.
chown -R 1883:1883 ~/mosquitto
Now we can create and start the Mosquitto container with the following command.
docker run -it -p 1883:1883 – name mosquitto -v ~/mosquitoconfig -v ~/mosquitto/data:/mosquitto/data -v ~/mosquitto/log:/mosquitto/log eclipse-mosquitto
  • -it: create an interactive bash shell in the container.
  • -p: define the published ports to the container. We match port 1883 of the host to port 1883 of the container.
  • –name: gives the container a custom name to stop and restart the container by his name.
  • -v: bind mount volumes between the host system and the container. The left side of the “:” defines the path of the host system and the right side the path in the container.
  • -d (not used): Run the container in the background so that the console is free.
At this time we can run the Mosquitto container but we do not have defined any username or password. Therefore we have to access the command line of the container and need the container ID:
  • Lookup the container ID in my case 5e2ec35d975b:
    sudo docker container ls -a
  • Access the shell of the container:
    docker exec -it 5e2ec35d975b sh
With the following command we create a new user (in my case: cdavid) and set a password that we have to confirm a second time.
Mosquitto Password

If we now look at the folder structure, there is a new data called mosquitto.passwd in the config folder that stores the username and password.

Mosquitto tree Password

The password of this data is encrypted for security reasons, like you see in the following picture.

Mosquitto Password file

This was the hardest part of this tutorial and also costs me some time and also a lot of research and failures. After the MQTT broker is setup with an username and password, we continue our work by setting up a container for InfluxDB and Grafana.

InfluxDB Setup via Docker

When we search on Docker Hub for InfluxDB we find the official image that we can pull by:
docker pull influxdb
Now we want also to share the volumes between the host and the container for InfluxDB. Therefore we create a new folder called influxdb. To start InfluxDB you only have to call:
docker run – name influxdb -p 8086:8086 -v influxdb:/var/lib/influxdb influxdb

Grafana Setup via Docker

You find the Grafana image on the Docker Hub under the name grafana/grafana and you can pull the image with the following command:
docker pull grafana/grafana
To start Grafana use the following command:
docker run -d – name=grafana -p 3000:3000 grafana/grafana
After the container is running, you can access the Grafana application on port 3000 with your browser, in my case: At the end of this tutorial you should have to following Docker containers running.
Docker container all

In this tutorial I want to focus on the setup of all Smart Home components like Home Assistant, Mosquitto, InfluxDB and Grafana as Docker containers. If you want to push data from the MQTT broker into InfluxDB and visualize the date in Grafana, then visit my InfluxDB and Grafana tutorial, were I show you step by step how to get the data funnel working. In this tutorial you will see that you also need a Python application that functions as an MQTT bridge. This MQTT bridge is a subscriber to all MQTT topics and pushes the data into the InfluxDB database.

If you have any questions regarding this tutorial or if you have problems setting up the Home Assistant environment, leave a comment in the following comment section and I will answer your questions as soon as possible.

12 Responses

Leave A Comment