Tech Decode Logo

How to Run Home Assistant Inside a Docker Container: A Simple Guide

Home Assistant on Docker

This article is part of the Home Assistant Series. Other articles in this series:

  1. Understanding Home Assistant: Your gateway to a smarter home
  2. Running Home Assistant on a Raspberry Pi
  3. Running Home Assistant in a Docker Container
  4. Setting up Home Assistant
  5. Home Assistant Green – All-in-one-solution
  6. Accessing home assistant while away

Home Assistant is a fantastic tool for managing smart home devices, and running it in a Docker container can make it even more flexible and efficient. We already looked at installing the Home Assistant OS directly on a Raspberry Pi, today we look at installing it via a Docker container. Installing it via a Docker container means that deployment is the same no matter the device or operating system (Linux, MacOS or Windows). It can also be run on a Raspberry Pi via Docker, although there are some considerations (see below comparison). As a start, have a look at our in-depth article on Docker to get Docker installed on your chosen hardware and operating system. But let’s recap on Home Assistant and what it is and dive into the Docker installation.

What is Home Assistant?

Home Assistant is an open-source platform for smart home automation. It helps you control and automate smart devices from various brands in a single app or dashboard.

What is Docker?

Docker is a tool that allows you to run applications in lightweight, isolated environments called containers. These containers include everything the application needs to run, making setup and management easier.

Step-by-Step Guide to Running Home Assistant in Docker

Step 1: Install Docker

First, you need Docker installed on your system. Here’s how:

  • On Windows/Mac: Download and install Docker Desktop from the Docker website.
  • On Linux: Open a terminal and run these commands (for Debian/Ubuntu):
    sudo apt update
    sudo apt install docker.io
    sudo systemctl start docker
    sudo systemctl enable docker

Step 2: Create a Docker Network

Home Assistant often needs to communicate with other containers (like MQTT brokers). To ensure smooth communication, create a custom Docker network:

docker network create homeassistant

Step 3: Pull the Home Assistant Docker Image

The Docker image is like a template for creating your Home Assistant container. Pull the official image:

docker pull homeassistant/home-assistant:stable

Step 4: Prepare a Configuration Directory

Home Assistant stores its configuration files on your system. Create a directory for these files so they persist even after the container is updated:

mkdir -p /path/to/your/config
Replace /path/to/your/config with a suitable location on your machine.

Step 5: Run the Home Assistant Container

Now, run the container with the following command:

docker run -d \
  --name=homeassistant \
  --restart=unless-stopped \
  --network=homeassistant \
  -v /path/to/your/config:/config \
  -e TZ=YOUR_TIMEZONE \
  -p 8123:8123 \
  homeassistant/home-assistant:stable

Explanation of the command:

  • -d: Runs the container in the background (detached mode)
  • --name=homeassistant: Names the container for easy management.
  • --restart=unless-stopped: Ensures the container restarts if it crashes, or if the host machine restarts.
  • --network=homeassistant: Connects the container to your custom network.
  • -v /path/to/your/config:/config: Maps your configuration directory to the container.
  • -e TZ=YOUR_TIMEZONE: Sets the correct timezone (e.g., America/New_York).
  • -p 8123:8123: Makes Home Assistant accessible at http://<your-ip>:8123. (Passes port 8123 from the container to port 8123 on the host machine)

Step 6: Access Home Assistant

After a few moments, Home Assistant will be running. Open your web browser and visit:

http://<your-computer's-IP>:8123  
This will probably be http://127.0.0.1:8123 if installed on the same machine you are accessing it from

Follow the setup wizard to configure your Home Assistant instance.

Updating Home Assistant

When a new version is released, you can update Home Assistant with these commands:

  1. Stop the container:
    docker stop homeassistant
  2. Remove the old container
    docker rm homeassistant
  3. Pull the latest image:
    docker pull homeassistant/home-assistant:stable
  4. Re-run the container using the same docker run command from Step 5.

Benefits of Running Home Assistant in Docker

  • Flexibility: Easily switch between versions or add integrations.
  • Isolation: Keeps your Home Assistant setup separate from your main system.
  • Customizability: Docker allows for unique configurations and add-ons.

Conclusion

Running Home Assistant in Docker is a great choice for beginners and advanced users alike. With this setup, you’ll enjoy a robust, isolated, and easily maintainable smart home management system.

If you’re just starting out, don’t worry—take it step by step. Soon, you’ll be automating your home like a pro!

Happy automating!

Visit the official website for Docker | Home Assistant

Related Articles: