Home Assistant

Home Assistant is an open-source home automation software that puts local control and privacy first.

Installation

The home-assistant core package has been dropped from the official repositories. The recommended method for running Home Assistant is now via a container, such as Docker and Podman. This guide focuses on using Docker Compose, which simplifies management.

Prerequisites

Install the docker and docker-compose packages.

Start/enable the docker.service.

Add your user to the docker user group to manage Docker without sudo.

# usermod -aG docker your_user

You must log out and log back in for this change to take effect.

Initial Setup

1. Create a project directory to hold your configuration and the docker-compose.yml file.

$ mkdir ~/homeassistant && cd ~/homeassistant

2. Create a docker-compose.yml file.

~/homeassistant/docker-compose.yml

   services:
     homeassistant:
       image: "ghcr.io/home-assistant/home-assistant:stable"
       container_name: homeassistant
       restart: unless-stopped
       privileged: false
       volumes:
         - ./config:/config
         - /etc/localtime:/etc/localtime:ro
       ports:
         - 8123:8123
       # Uncomment the following section to pass a USB device to the container
       # devices:
       #   - /dev/serial/by-id/YOUR_DEVICE_PATH:/dev/serial/by-id/YOUR_DEVICE_PATH

Note For network discovery of some integrations (like ESPHome) to work, you may need to add network_mode: host to the service definition. If you do this, you must remove the ports section.

3. Start Home Assistant.

$ docker-compose up -d

Docker will download the image and start the container. The first start may take several minutes.

The web interface will be available at http://localhost:8123. All configuration files will be stored in ~/homeassistant/config/.

Migrating from the home-assistant-core package

If you were previously using the official home-assistant-core package, follow these steps to migrate to a Docker setup.

1. Create a full backup of the /var/lib/hass.

2. Stop and disable the old service.

# systemctl stop home-assistant.service
# systemctl disable home-assistant.service

3. Follow the "Initial Setup" steps in the section above to create your ~/homeassistant directory and docker-compose.yml file. Do not start the container yet.

4. Move your existing configuration to the new location.

# mv /var/lib/hass/* ~/homeassistant/config/

5. Correct the file permissions. Replace your_user with your own username.

# chown -R your_user:your_user ~/homeassistant/config/

6. Now, start your new container.

$ cd ~/homeassistant
$ docker-compose up -d

Home Assistant will start using your existing configuration.

Usage

Manage your Home Assistant container from your project directory (~/homeassistant/) using docker-compose.

To stop the container:

$ docker-compose stop

To start the container:

$ docker-compose start

To view the logs:

$ docker-compose logs -f

To update Home Assistant to the latest stable version:

$ docker-compose pull
$ docker-compose up -d

Configuration

Using an external database

Using an external database like MariaDB or PostgreSQL can improve performance. The required Python drivers are already included in the Home Assistant Docker image.

1. Install your chosen database server. Refer to the MariaDB or PostgreSQL pages for setup instructions.

2. Create a database and user for Home Assistant.

For MariaDB:

$ mysql -u root -p

For PostgreSQL:

[postgres]$ createuser ha_user
[postgres]$ createdb homeassistant -O ha_user

3. Add the recorder configuration to ~/homeassistant/config/configuration.yaml:

~/homeassistant/config/configuration.yaml

Replace YOUR_DATABASE_URL with the connection string for your database:

MariaDB/MySQL: 'mysql://ha_user:YOUR_PASSWORD@DATABASE_IP/homeassistant?charset=utf8mb4'
PostgreSQL: 'postgresql://ha_user:YOUR_PASSWORD@DATABASE_IP/homeassistant'

Note Replace DATABASE_IP with the IP address of your database server. If the database is running on the same machine (the Docker host), you can typically use the host's LAN IP or the Docker bridge IP (often 172.17.0.1). localhost will not work as it refers to the container itself, not the host.

Troubleshooting

Access to USB devices (Zigbee/Z-Wave)

To use a USB device like a Zigbee dongle, it must be passed from the host to the container.

1. Find the device's persistent path.

$ ls -l /dev/serial/by-id/

2. Add the user running Docker to the uucp or dialout group, which typically owns serial devices. Check the device's group with ls -l.

# usermod -aG uucp your_user

You will need to log out and back in for this to take effect.

3. Uncomment and edit the devices section in your docker-compose.yml file to map your host device to a path inside the container.

~/homeassistant/docker-compose.yml

...
devices:
  - /dev/serial/by-id/usb-Itead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_...:/dev/ttyACM0

4. Recreate the container to apply the changes.

$ docker-compose up -d --force-recreate