Home Assistant - ArchWiki

Jump to content

# Home Assistant

From ArchWiki

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

Categories:

- Servers
- Web applications

Home Assistant
Add topic