Installing Home Assistant with Docker on a Raspberry Pi

Want to automate your home but don’t want to hand over control of your data to big corporations? Then Home Assistant is the perfect solution for you. It’s an extremely powerful, flexible, and most importantly, private open-source platform for your smart home.

In this guide, I’ll show you how to easily install Home Assistant with Docker on a server like a Raspberry Pi. We’ll skip the pre-built systems and maintain full control.

What is Home Assistant?

Home Assistant is an open-source platform that acts as a central control hub for your smart home. Instead of using dozens of different apps for lights, sockets, thermostats, and sensors, Home Assistant bundles everything into a single, clean interface. The biggest advantage: it runs locally in your home, for example, on a Raspberry Pi. Your data stays with you and isn’t sent to a third-party cloud.

The platform is versatile and supports thousands of devices from a wide variety of manufacturers. Through automations, you can create intelligent routines—for example, turn on the lights when you get home, or turn down the heating when a window is opened.

Home Assistant OS vs. Docker Container: Which Path is Right for You?

There are several ways to install Home Assistant. The official documentation mainly distinguishes between two methods:

We’re choosing the container method because it gives us full control. Add-ons like a database can simply be added as their own container if needed, and updates are done with just two commands.

Prerequisites: What You’ll Need

You don’t need much to get started. We can skip the $99 Home Assistant Green.

• A Server: A Raspberry Pi (Amazon Affiliate Link) (Model 4 or newer is recommended) is a popular and energy-efficient choice. However, an old laptop, an Intel NUC, or a NAS running Linux are also perfectly suitable.
• Docker: Docker must be installed on your server. I show how to set up Docker on a Raspberry Pi in one of my other blog posts.
• Smart Home Devices: Of course, you’ll also need some smart devices you want to control, such as lights (Philips Hue Amazon Affiliate Link), sockets (Shelly Amazon Affiliate Link), thermostats, or sensors.

Installation: Step-by-Step to Your Own Smart Home

Just follow these steps to get Home Assistant up and running on your server in minutes.

1. Connect to the Server and Create Folders

First, connect to your server via SSH (in my case, a Raspberry Pi).

ssh username@your-server-ip-address

Once connected, let’s create the necessary folder structure for Home Assistant.

# Create a main folder for Home Assistant
mkdir homeassistant

# Change into the new folder
cd homeassistant

# Create a subfolder for the configuration
mkdir config

# Create an empty Docker Compose file
touch compose.yaml

Now, in the homeassistant directory, we have a config folder where all settings will be stored, and a compose.yaml file that will contain our Docker configuration.

2. Create the compose.yaml File

Open the compose.yaml file with a text editor like nano.

nano compose.yaml

Now, paste the following content. I’ll explain what each line means in a moment.

services:
    homeassistant:
        image: ghcr.io/home-assistant/home-assistant:2025.9
        container_name: homeassistant
        network_mode: host
        volumes:
            - ./config:/config
            - /etc/localtime:/etc/localtime:ro
            - /run/dbus:/run/dbus:ro # Optional for Bluetooth
        devices:
            # You can pass through USB devices like Zigbee sticks here
            # - /dev/ttyUSB0:/dev/ttyUSB0
        restart: unless-stopped
        privileged: true
        environment:
            - TZ=Europe/Berlin

What do these configurations mean?

• image: We’re using the official image from the GitHub Container Registry (ghcr.io). Important: I’m specifying a fixed version (2025.9) instead of latest. This prevents unexpected issues after automatic updates and allows us to update deliberately.
• container_name: A fixed name that makes managing the container easier.
• network_mode: host: Allows Home Assistant to use your server’s network interface directly. This is crucial for the automatic discovery of many devices on your network.
• volumes: We mount our local config folder into the container. This ensures all our settings persist even after an update. We also sync the system time.
• devices: This section is commented out, but it becomes important if you connect hardware like a Zigbee or Z-Wave stick via USB.
• restart: unless-stopped: Ensures the container starts automatically if your server ever reboots.
• privileged: true: Gives the container elevated permissions. This is often necessary to access hardware like USB devices.
• environment: Here, we set the time zone so that all time references and automations work correctly.

Save the file with Ctrl + X, confirm with Y, and press Enter.

3. Start Home Assistant

Everything is now ready. We can start Home Assistant with a single command:

sudo docker compose up -d

Docker will now download the Home Assistant image and start the container in the background (-d stands for “detached”). The first start might take a few minutes while Home Assistant initializes itself.

You can monitor the progress with the following command:

sudo docker compose logs -f

If you don’t see any error messages, everything is on the right track.

The Initial Setup

Open a web browser and enter your server’s IP address followed by port 8123:

http://YOUR-SERVER-IP:8123

You should be greeted by the Home Assistant welcome screen.

1. Create a user account: Click “Create my smart home” and set up an administrator account with a name and a strong password.
2. Set your location: Specify your location. This helps Home Assistant calculate accurate sunrise and sunset times for automations.
3. Analytics: Decide if you want to share anonymous usage data.

After this, Home Assistant will scan your network for compatible devices.

Integrating Devices and Exploring the Dashboard

After setup, you’ll land on your personal dashboard. You’ll already see some initial information like the weather and any devices you’ve set up.

To add more devices, go to Settings > Devices & Services.

Here, you can click the “Add Integration” button to search for hundreds of supported services and devices.

Example: Adding a Shelly Socket

In my case, I can add my Shelly socket. After configuration, it appears directly on my dashboard. I can now not only turn it on and off but also see its real-time power consumption.

This way, you can gradually add all your devices and customize your dashboard to your liking.

How to Easily Update

1. Change the version: Open the compose.yaml file on your server again.

   nano compose.yaml

   Change the line image: ghcr.io/home-assistant/homeassistant:2025.9 to a newer version, e.g., 2025.10.

2. Stop the container: Stop the running Home Assistant container.

   sudo docker compose down

3. Pull the new image: Download the new version.

   sudo docker compose pull

4. Restart the container: Start Home Assistant with the new version.

   sudo docker compose up -d

That’s it! Go to Settings > About in the web interface to verify that the new version is running. The whole process only takes a few minutes.

Conclusion: Your Smart Home, Your Rules

We’ve seen how easy it is to install Home Assistant with Docker on a Raspberry Pi. You now have a private foundation for your smart home.

The next step is to integrate your devices and explore the world of automations. Create scenes, scripts, and rules that make your home truly intelligent. Feel free to write in the comments which automation is most useful for you!