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 or Podman.
Docker
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.
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
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/.
Podman
Podman is a daemonless alternative to Docker with native systemd integration via Quadlets.
Prerequisites
Setup
1. Create a directory for the configuration.
# mkdir -p /opt/homeassistant/config
2. Create a Quadlet file:
/etc/containers/systemd/homeassistant.container
[Unit] Description=Home Assistant Wants=network-online.target After=network-online.target [Container] ContainerName=homeassistant Image=ghcr.io/home-assistant/home-assistant:stable Volume=/opt/homeassistant/config:/config Volume=/etc/localtime:/etc/localtime:ro Volume=/run/dbus:/run/dbus:ro Environment=TZ=UTC PublishPort=8123:8123 [Service] Restart=always [Install] WantedBy=multi-user.target
PublishPort=8123:8123 with Network=host and add PodmanArgs=--privileged.3. Reload systemd and start the service.
# systemctl daemon-reload # systemctl start homeassistant
The Quadlet will automatically generate a systemd service that starts on boot. Check status with:
# systemctl status homeassistant
The web interface will be available at http://localhost:8123. All configuration files will be stored in /opt/homeassistant/config/.
Updating
To update Home Assistant:
# podman pull ghcr.io/home-assistant/home-assistant:stable # systemctl restart homeassistant
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'
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