Home Assistant

Related articles
Home Assistant Supervised
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
Note
For network discovery of some integrations (like Chromecast, HomeKit, or Philips Hue) 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/
.
Podman
Podman
is a daemonless alternative to Docker with native
systemd
integration via
Quadlets
.
Prerequisites
Install
the
podman
package.
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
Note
For network discovery of integrations like Chromecast, HomeKit, or Philips Hue, replace
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:
Note
YOUR_HOST can be set to localhost if running locally
$ mariadb -u root -p
CREATE DATABASE homeassistant;
CREATE USER 'ha_user'@'YOUR_HOST' IDENTIFIED BY 'YOUR_PASSWORD';
GRANT ALL PRIVILEGES ON homeassistant.* TO 'ha_user'@'YOUR_HOST';
FLUSH PRIVILEGES;
quit;
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
See also
Home Assistant homepage
Official Documentation for Container Installation