Home Assistant Docker Guide

In this comprehensive guide, I will delve into the world of Home Assistant and explore how to set it up using Docker, a containerization platform that simplifies the installation process.

Whether you're a newcomer to the world of home automation or a tech enthusiast looking to streamline your smart home setup, this guide is tailored to help beginners embark on their Home Assistant journey.

By the end of this tutorial, you'll have a functional Home Assistant Docker container running, ready to start integrating and automating your smart devices.

So, let's dive into the world of Home Assistant and Docker to transform your home into a smarter, more efficient space.

Introduction to Home Assistant

What is Home Assistant?

Home Assistant is an open-source home automation platform that allows users to integrate and control smart home devices from different brands and communicate with them through a unified interface. It supports over 2,400 different devices and services. The software is written in Python and has an active community contributing new features and integrations.

Why use Home Assistant?

There are several benefits to using Home Assistant for your home automation needs:

  • Open source - Home Assistant is open source which means it's free to use and not tied to any proprietary system. The code is publicly available for anyone to contribute and audit.

  • Local control - It runs locally on your network and hardware. Your data is not sent to the cloud. This improves privacy and reduces reliance on vendor services.

  • Integrates many devices - Home Assistant has a vast ecosystem of integrations for consumer IoT brands like Philips Hue, IKEA, and Google Nest along with many niche and DIY devices. This allows controlling devices from many vendors in one place.

  • Active community - With over 190,000 forum members and over 3,000 code contributors, bugs are quickly fixed and new features added. The frequent updates add support for the latest devices and technologies.

  • Customizable and extensible - Users can customize the UI and add functionality via automations, scripts, and plugins. Home Assistant is highly flexible.

Benefits of Home Assistant

In summary, the main benefits of Home Assistant include:

  • Local home automation with no reliance on cloud services

  • Control over the privacy of home data

  • Support for many brands, protocols, and devices out of the box

  • An active open-source community providing quick enhancements

  • Highly customizable with many extensions and plugins available

  • Free and not tied to any vendor ecosystem

Setting up Home Assistant with Docker

What is Docker?

Docker is a popular software container platform. It allows applications like Home Assistant to run in an isolated user space called a container. The container has everything the application needs to run including all dependencies and libraries.

Containers provide a consistent environment for the application to run irrespective of the underlying operating system and hardware. This makes Docker very useful for deploying and scaling applications.

Benefits of using Home Assistant on Docker

There are several advantages of running Home Assistant as a Docker container:

  • Simplified deployment - With Docker, deploying Home Assistant takes just one command. There is no need to install dependencies and configure OS.

  • Portability - The HA Docker image can run on any platform that supports Docker like Linux, Windows, Mac, NAS devices, etc. This provides wide hardware compatibility.

  • Isolation - Home Assistant and its dependencies are isolated in the container. This prevents conflicts with other software running on the host system.

  • Management - Docker provides useful tools to manage containers like starting, stopping, updating, and resource monitoring.

  • Community support - There are readymade Docker images, templates, tools, and documentation from the community to help run HA.

Steps to set up Home Assistant on Docker

The basic steps to deploy Home Assistant on Docker are:

Install Docker - If not already installed, install Docker Engine or Docker Desktop on the target system like a Raspberry Pi, NAS, NUC, or a desktop PC.

In this tutorial, we will install Docker on a fresh Ubuntu machine using the following code:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh ./get-docker.sh

Note

If you are attempting to install the Home Assistant Docker image on a Synology NAS then you should follow my article Installing Home Assistant on Synology NAS rather than this article as it will include more accurate instructions compared to a generic Docker setup.

Create directories - Create directories on the host system for Home Assistant configuration and data. This allows persisting data outside the Docker container.

On my Ubuntu machine, I create Docker config folders in a folder called Docker that lives inside my home directory. For this example, I have created the folder structure /home/wsh/docker/home-assistant/config

Pull HA Docker image - Get the latest Home Assistant Docker image from the official repository using docker pull ghcr.io/home-assistant/home-assistant:stable.

Run container - Run the Docker container from the image using the docker run command. Pass the created directories as mounts and set port binding.

Tip

You may be required to run your docker commands with 'sudo' e.g. sudo docker pull and sudo docker run

docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ=YOUR_TIME_ZONE \
  -v /PATH_TO_YOUR_CONFIG:/config \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

Initial configuration - Do the initial setup through the Home Assistant web interface like integrations, users, automation, etc. The container will be using the same IP address as your host machine because we used --network=host so simply open http://YOUR_IP_ADDRESS:8123 in your web browser to continue with the onboarding process.

Once the container is running, Home Assistant can be accessed through the web interface as with a regular installation. The directories containing configuration and data are persisted on the host for backup.

Configuring the Home Assistant Docker container

Mapping devices and integrations

Since Home Assistant runs inside the isolated Docker container, additional steps need to be taken to allow the container to communicate with IoT devices on the host network and control them:

  • Network mode - The container should be launched with host network mode to share the host network stack. This allows HA to discover devices.

  • Privileged mode - For interacting with devices connected via Zigbee or Z-Wave dongles, the container needs to be privileged. This grants raw host hardware access.

  • USB devices - Relevant USB dongles like HUSBZB-1 need to be passed through to the container using the --device flag when launching the Docker.

  • GPIO - For boards like Raspberry Pi, use the --device flag to expose the GPIO pins to the container.

Example - Mapping a Z-Wave USB controller to the Home Assistant Docker container

The following example is the same command we used to install the container with the addition of the --device flag. In this example my AEOTEC Z-Wave USB controller is using /dev/ttyACM0 so I use --device=/dev/ttyACM0.

Tip

To easily identify your USB device's serial port on Linux install "hwinfo" using apt-get install hwinfo then run hwinfo --short

docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ=YOUR_TIME_ZONE \
  -v /PATH_TO_YOUR_CONFIG:/config \
  --network=host \
  --device=/dev/ttyACM0
  ghcr.io/home-assistant/home-assistant:stable

Once devices are accessible, integrations can be set up normally through the UI.

Home Assistant Docker add-ons

Home Assistant has many useful add-ons that provide extra functionality like Google Drive backup and browser file editor however these add-ons from the add-on store are not available for Docker container installations.

Home Assistant Docker updates

There are a few approaches to keep Home Assistant up-to-date on Docker:

Download the latest version of the home-assistant image.

docker pull ghcr.io/home-assistant/home-assistant:stable

Manually stop the container and then remove it.

docker stop homeassistant
docker rm homeassistant

Run a new container with the updated image.

docker run -d \
  --name homeassistant \
  --restart=unless-stopped \
  --privileged \
  -e TZ=YOUR_TIME_ZONE \
  -v /PATH_TO_YOUR_CONFIG:/config \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

  • Create an automated script to periodically stop, pull the new image, and rerun the container e.g. as a cron job.

  • Use Portainer to easily update and manage your Home Assistant container.

Backing up the configuration before updating is recommended to allow rolling back in case of issues.

Backing up and restoring the Home Assistant Docker container

Importance of backups

It is critical to have proper backups of the Home Assistant Docker deployment. Backups protect against data loss or corruption. Some scenarios where backups help recover Home Assistant:

  • Hardware failure of the host running Docker.

  • Network failure or errors that impact connectivity.

  • Power outages or electrical surges cause file system errors.

  • Accidental changes or deletion of configuration and data.

  • Major bugs or incompatibility issues after a Home Assistant update.

  • Malware or ransomware attack that impacts files.

Home Assistant Docker backup process and tools

Backing up a Home Assistant Docker involves copying key volumes and data outside the container:

  • Configuration - The Home Assistant configuration folder mapped as a volume to the host should be periodically backed up. This contains all the customization.

  • Database - If an SQL database like PostgreSQL is used as the recorder, its data volume must be backed up as well.

  • Automation - Scripts can automate the backup process on a schedule. BASH, Python, Docker CLI commands, etc. can be used.

  • Cloud storage - Backup files can be pushed to cloud storage like Google Drive for off-site safekeeping and recovery.

Home Assistant Docker restore process

To restore Home Assistant on Docker from a backup:

  • Stop the Home Assistant Docker container if it's still running.

  • Delete or unregister the stopped container. This clears the state and starts fresh.

  • Copy back configuration and data folders from the latest backup to the original locations.

  • Launch a new Home Assistant container, passing the same volumes.

  • The container will start up with a restored configuration accessing restored data.

  • Once launched, verify everything is restored properly through the Home Assistant UI.

Tips for Optimizing Home Assistant Docker

Limiting container size

Some tips to minimize disk usage of the Home Assistant Docker container:

  • Avoid large snapshots of the image. Use Docker pruning and cleanup commands periodically.

  • Set size limits on Docker volumes mapped from the host. This will prevent unbounded growth.

  • Store audio files, images, snapshots etc. outside persistent volumes e.g. a NAS share.

  • Disable debug logging and use log rotation to reduce container logs volume.

  • Prune old recorder database entries and backups if they retain too much history.

Improving performance

Steps to get better performance out of Home Assistant on Docker:

  • Use host network mode for lower latency discovery and control.

  • For Raspberry Pi, build images specifically optimized for ARM architecture.

  • Allocate sufficient CPU cores and memory for smooth operation.

  • Schedule intensive automations for when the host is less busy to reduce resource contention.

  • Enable caching of static assets in NGINX proxy for faster UI loading.

  • Exclude integrator logs, disable verbose logging, etc. to reduce I/O overhead.

Automating container management

Some ways to automate the management of the Home Assistant Docker container:

  • Use Docker Compose to simplify launching containers with the correct settings.

  • Create scripts to back up volumes and prune images automatically.

  • Set up health checks to monitor and restart the container if unresponsive.

  • Automate container updates by polling Docker Hub for new versions.

  • Integrate backups, updates, etc. into CI/CD pipelines for consistent deployments.

  • Leverage Kubernetes or Docker Swarm if running at scale for automated deployment, scaling, and management.

Conclusion

Summary of main points

  • Home Assistant is a popular open-source home automation platform with integration for 2400+ devices.

  • Docker provides a simplified way to deploy Home Assistant by packaging it as a lightweight container but lacks features such as the add-on store.

  • Key benefits are quick setup, portability, isolation from the host system, and standardized management.

  • Devices need to be passed through and privileges granted for HA to access hardware like USB and GPIO.

  • Backing up volumes and databases is critical to protect from data loss and allow recovery.

  • Optimizations like limiting size, improving performance, and automating management help run HA efficiently on Docker.

Final thoughts on Home Assistant with Docker

Running Home Assistant via Docker provides a resilient, manageable, and portable deployment option. It reduces complexity and taps into Docker ecosystem tools.

With some diligence around mapping devices, planning backups, optimizing resources, and automating management, Home Assistant can run smoothly in Docker containers. This gives a great mix of flexibility and standardization for home automation deployments.

FAQs

What hardware is required to run Home Assistant in Docker?

Home Assistant has modest hardware requirements. A dual-core processor, 2GB RAM, and 16GB storage is sufficient. For audio processing or computer vision, more CPU cores or a GPU will be beneficial. It can run on a wide range of hardware like Raspberry Pi, NUC, NAS, old desktops, etc.

How do I migrate my existing Home Assistant install to Docker?

1. Take a full backup of the configuration directory and any data volumes.
2. Provision a suitable host system with Docker installed.
3. Copy over the backup to this new host.
3. Launch a Home Assistant Docker container, mapping the backups as volumes.
4. Once operational, decommission the old Home Assistant system.

What Docker image should I use for Home Assistant?

The official homeassistant/home-assistant image on Docker Hub is recommended. Select tags like stable, beta or specific version numbers depending on preference for bleeding edge versus stability. For Raspberry Pi and other ARM boards, use the homeassistant/raspberrypi image.

How should persistent storage be handled with Home Assistant Docker?

Important data like the configuration and database should be mapped to persistent named volumes on the host rather than stored within the container. This keeps the data intact across container upgrades and restarts. Non-critical data can still reside in the writable container layer.

What common pitfalls should be avoided when deploying Home Assistant with Docker?

1. Insufficient I/O performance if the database is stored on the same drive as the OS and Docker images.
2. Allowing container logs to grow unbounded and fill up disk space.
3. Not adequately exposing USB, GPIO, and necessary hardware to the container.
4. Large full image backups bloat disk usage instead of smaller incremental backups.
5. Upgrading the host OS kernel/Docker version resulting in incompatibility with the existing Home Assistant container.
Popular Tags