Как установить HACS

Введение

Home Assistant — мощная платформа для умного дома. Но возможности базовой установки ограничены. Чтобы добавить новые интеграции, пользовательские панели, карточки интерфейса и полезные утилиты, удобно использовать HACS (Home Assistant Community Store). Это каталог дополнений от сообщества, который открывает доступ к тысячам готовых решений.

Что такое HACS и зачем он нужен

HACS — это менеджер репозиториев, который позволяет:

• быстро находить и устанавливать пользовательские интеграции
• добавлять кастомные карточки для Lovelace UI
• управлять обновлениями сторонних дополнений
• расширять функциональность без ручного копирования файлов

Проект развивается сообществом на GitHub: https://github.com/hacs.
В текущий момент доступно более 1500 интеграций, их список: https://github.com/hacs/default/blob/master/integration.

Предварительные требования

Перед установкой убедитесь, что:

• Есть доступ в интернету
• У вас установлена актуальная версия Home Assistant (рекомендуется последняя стабильная)
• Вы используете аккаунт администратора и имеете доступ к конфигурации (директория config)

Установка HACS через SSH

Подключитесь к серверу Home Assistant через SSH (смотри статью: Настраиваем ssh доступ к Home Assistant)

1. Убедитесь, что находитесь в каталоге конфигурации Home Assistant (обычно /config)
2. Выполните команду:

wget -O - https://get.hacs.xyz | bash -

4. Перезапустите Home Assistant

Для сверки: после запуска установочного скрипта в терминале финальные строки при успешной установке выглядят так:

INFO: Creating HACS directory...
INFO: Unpacking HACS...

INFO: Verifying versions
INFO: Current version is 2025.9.4, minimum version is 2024.4.1

INFO: Removing HACS zip file...
INFO: Installation complete.

INFO: Remember to restart Home Assistant before you configure it
➜  config

Если вы управляете несколькими инстансами Home Assistant или предпочитаете декларативный подход, установку HACS можно автоматизировать через Ansible. Подробные примеры приведены в приложении «Установка HACS через Ansible». Данные примеры не содержат последующей конфигурации — например, авторизации HACS через GitHub и ввода кода подтверждения. Эти шаги необходимо выполнить вручную, как описано дальше. Такой подход особенно удобен в CI/CD сценариях и при поддержке нескольких серверов: код в Git остаётся источником правды, а установка становится повторяемой и предсказуемой.

Первоначальная настройка HACS (через GUI)

1. Откройте Настройки → Интеграции → Добавить интеграцию и найдите HACS
2. Отметьте чекбоксы согласия (о доступе к логам, отсутствии add-ons в HACS, кастомном характере компонентов и необходимости отключать custom_components при проблемах) и нажмите Подтвердить
3. Пройдите авторизацию GitHub по Device Flow: на экране появится код и ссылка. Перейдите на github.com/login/device, вставьте код и подтвердите доступ. Вернитесь в Home Assistant и дождитесь завершения
4. После успешной активации в левом меню появится пункт HACS — откройте его: отобразится каталог интеграций и карточек

Где хранится токен GitHub и зачем он нужен

Зачем нужен токен. HACS использует GitHub API для поиска репозиториев, чтения релизов и скачивания архивов. Авторизация токеном поднимает лимиты GitHub API, делает обновления стабильнее и (при желании) даёт доступ к приватным репозиториям.

Где хранится. На актуальных версиях Home Assistant токен HACS хранится в JSON‑файле .storage/core.config_entries (относительно каталога config; на HAOS это обычно /config/.storage/core.config_entries). Внутри файла найдите запись с "domain": "hacs" и поле "data.token" — это и есть ваш токен.

Пример токена:

➜  config cat .storage/core.config_entries| grep hacs
      {"created_at":"2025-09-25T08:04:43.992573+00:00","data":{"token":"gho_*************************************"},"disabled_by":null,"discovery_keys":{},"domain":"hacs","entry_id":"01K5ZYEEARV001YKV6SD96PVH0","minor_version":1,"modified_at":"2025-09-25T08:04:43.992574+00:00","options":{"experimental":true},"pref_disable_new_entities":false,"pref_disable_polling":false,"source":"user","subentries":[],"title":"","unique_id":null,"version":1}

Срок действия токена. Это OAuth‑токен GitHub без фиксированного срока жизни; он действует, пока вы не отзовёте доступ приложения HACS в GitHub (Settings → Applications → Authorized OAuth Apps) или пока GitHub не отзовёт его автоматически (например, при годе неактивности или в случае утечки).

Использование HACS

• Установка компонентов: откройте HACS и выберите нужный плагин или интеграцию
• Обновления: HACS уведомляет о новых версиях - достаточно нажать "Update"
• Управление: удаление или отключение компонентов происходит в пару кликов

Заключение

HACS делает Home Assistant действительно гибкой платформой. С его помощью можно легко добавить новые возможности, кастомизировать интерфейс и держать все плагины в актуальном состоянии.

Приложение: установка HACS через Ansible

Ниже приведены фрагменты роли Ansible для установки HACS. Чтобы они заработали, необходимо определить переменные окружения, в частности:

• hass__user — системный пользователь, под которым работает Home Assistant
• hacs__release_path — каталог, куда устанавливается Home Assistant
• hass__config_path — путь к конфигурации Home Assistant (например, /config)
• при необходимости: hass__hacs_installer_url, hass__hacs_installer_path

Оба подхода ставят HACS, но отличаются способом реализации. Первый способ проще и быстрее, но менее детерминированный и часто вызывает нарекания линтеров из‑за использования shell и пайпов. Второй способ считается более «правильным» с точки зрения Ansible: он чище для линтера, позволяет явно контролировать условия установки и исключает повторные действия.

Первый способ (shell с пайпом)

- name: Install HACS
  become: true
  become_user: "{{ hacs__user }}"
  ansible.builtin.shell: "wget -O - https://get.hacs.xyz | bash -"
  environment:
    PATH: "{{ hacs__release_path }}:{{ ansible_env.PATH }}"
  args:
    executable: /bin/bash
    chdir: "{{ hacs__release_path }}"
  with_items:
    - wget -O - https://get.hacs.xyz | bash -
  notify:
    - Restart hass
  register: hacs__result
  changed_when: "'Remember to restart' in (hacs__result.stdout | default(''))"

Второй способ (stat + get_url + command)

- name: Check HACS installation
  ansible.builtin.stat:
    path: "{{ hass__config_path }}/custom_components/hacs/manifest.json"
  register: hass__hacs_manifest

- name: Download HACS installer script
  ansible.builtin.get_url:
    url: "{{ hass__hacs_installer_url | default('https://get.hacs.xyz') }}"
    dest: "{{ hass__hacs_installer_path | default('/tmp/hacs-install.sh') }}"
    mode: '0755'
  when: not hass__hacs_manifest.stat.exists

- name: Run HACS installer
  become: true
  become_user: "{{ hass__user }}"
  ansible.builtin.command: /bin/bash "{{ hass__hacs_installer_path | default('/tmp/hacs-install.sh') }}"
  args:
    chdir: "{{ hass__config_path }}"
    creates: "{{ hass__config_path }}/custom_components/hacs/manifest.json"
  environment:
    PATH: "{{ hass__release_path }}:{{ ansible_env.PATH }}"
  register: hass__hacs_install
  when: not hass__hacs_manifest.stat.exists

- name: Remove HACS installer script
  ansible.builtin.file:
    path: "{{ hass__hacs_installer_path | default('/tmp/hacs-install.sh') }}"
    state: absent
  when: hass__hacs_install is defined

Приложение: полезные ссылки

• Официальный сайт HACS — https://www.hacs.xyz/
• GitHub HACS — https://github.com/hacs