Установка Home Assistant в Docker: Container и Compose по шагам

Docker-установка Home Assistant подойдёт тем, кто уже работает с контейнерами или хочет оставить на сервере свою операционную систему и другие сервисы. В статье пошагово разберём установку Home Assistant в Docker: подготовим Linux-сервер, поставим Docker Engine, создадим каталог конфигурации, запустим контейнер командой и через Docker Compose, откроем интерфейс на порту 8123, пробросим USB-устройства, подключим внешнюю базу данных и научимся обновляться и делать резервные копии. Мы работаем с вариантом Container — официально поддерживаемым способом наряду с Home Assistant OS.

Сначала о том, что вы получаете. Container-установка — это только ядро Home Assistant в контейнере. В ней нет Supervisor, значит нет магазина дополнений, встроенного управления системой и обновления одной кнопкой. Нужные сервисы (брокер MQTT, Zigbee2MQTT, редактор файлов) вы запускаете отдельными контейнерами. Если нужен вариант «всё включено», выбирайте Home Assistant OS. Способы Supervised и Core (установка без контейнера) в 2025 году объявлены устаревшими, так что для новой установки остаются HAOS и Container.

1Кратко

• Нужен Linux-сервер с Docker Engine 23.0.0 или новее; Docker Desktop на Windows и macOS для постоянной работы не подходит.
• Образ — ghcr.io/home-assistant/home-assistant:stable, конфигурация хранится в подключённом каталоге, поэтому контейнер можно безопасно пересоздавать.
• Обязательные параметры: network_mode: host для автообнаружения и каталог с конфигурацией в /config; интерфейс открывается на порту 8123.
• Обновление — docker compose pull и docker compose up -d; резервная копия — это копия каталога конфигурации.
• Дополнений нет: MQTT, Zigbee2MQTT и прочее запускаются отдельными контейнерами рядом.

2Container или Home Assistant OS: что выбрать

Критерий	Home Assistant OS	Container (Docker)
Операционная система	отдельная, управляется Home Assistant	ваша собственная, обычно Linux
Магазин дополнений	есть	нет, сервисы ставите сами
Резервные копии	встроенные, полные	копируете каталог конфигурации; встроенные ограничены
Обновление	из интерфейса	новым образом контейнера
Сложность	ниже	выше, нужны навыки администрирования
Другие сервисы на том же сервере	неудобно	удобно
Потребности в железе	выделенное устройство или виртуальная машина	любой Linux-сервер, в том числе уже занятый

3Что понадобится

• Сервер на Linux с доступом по SSH: мини-ПК, одноплатный компьютер, виртуальная машина, NAS с поддержкой Docker.
• Docker Engine версии 23.0.0 или новее и плагин Docker Compose.
• Доступ в интернет для загрузки образа из реестра ghcr.io. Из России доступ к части репозиториев может потребовать VPN или зеркал.
• Свободный порт 8123: Home Assistant будет слушать именно его.
• Каталог для конфигурации на надёжном накопителе (лучше SSD): в нём лежат настройки, база данных и учётные данные.
• Минимум по ресурсам скромный: для небольшого дома хватает 2 ГБ памяти и пары ядер, но запас по диску нужен под историю.

Docker на Windows и macOS

Официальная инструкция для Container рассчитана на Linux. Автообнаружению нужен режим network_mode: host, а в Docker Desktop на Windows и macOS он ведёт себя иначе: контейнер попадает во внутреннюю сеть виртуальной машины Docker, а не в вашу локальную. В итоге обнаружение устройств, интеграции на основе mDNS и многое другое не работает. Для Windows лучше виртуальная машина с Home Assistant OS, для контейнеров — отдельный Linux-сервер.

4Шаг 1. Установите Docker Engine и Compose

Если Docker уже есть, пропустите этот шаг и проверьте версию. Для Debian и Ubuntu самый прямой путь — установочный скрипт проекта Docker. Скачайте его, прочитайте и только потом запускайте:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Скрипт ставит Docker Engine и плагин Compose. Если вы предпочитаете подключить репозиторий вручную, используйте инструкцию Docker для вашего дистрибутива. Чтобы работать без sudo, добавьте пользователя в группу docker и перезайдите в сеанс:

sudo usermod -aG docker $USER

Проверьте работу:

docker --version
docker compose version
docker run --rm hello-world

Если команды выполняются без ошибок, двигайтесь дальше. Старые установки могут называть утилиту docker-compose (с дефисом); в этом случае подставляйте её вместо docker compose, но лучше перейти на актуальный плагин.

5Шаг 2. Создайте каталог для конфигурации

Контейнеры одноразовые, а данные Home Assistant нет. Настройки, база устройств и история должны жить вне контейнера, в подключаемом каталоге:

sudo mkdir -p /opt/homeassistant/config

Путь выбираете вы. Запомните его: здесь находятся configuration.yaml, каталог .storage и файлы базы данных. Именно этот каталог нужно копировать при резервном копировании.

6Шаг 3. Запустите контейнер командой docker run

Самый быстрый запуск — одна команда. Тег stable указывает на последнюю стабильную версию.

docker run -d 
  --name homeassistant 
  --privileged 
  --restart=unless-stopped 
  -e TZ=Europe/Moscow 
  -v /opt/homeassistant/config:/config 
  -v /run/dbus:/run/dbus:ro 
  --network=host 
  ghcr.io/home-assistant/home-assistant:stable

Разберём параметры:

Параметр	Что делает
--name homeassistant	имя контейнера, по которому им управляют
--privileged	расширенные права; рекомендуется в официальной инструкции для доступа к оборудованию, например Bluetooth
--restart=unless-stopped	контейнер запускается после перезагрузки сервера
-e TZ=...	часовой пояс, подставьте свой, например Europe/Moscow
-v ...:/config	подключение каталога конфигурации
-v /run/dbus:/run/dbus:ro	доступ к D-Bus для Bluetooth-интеграций
--network=host	сеть хоста: нужна для автообнаружения; порты параметром -p не публикуются

Режим --privileged можно попробовать убрать и пробросить устройства явно, но часть функций, например Bluetooth, может перестать работать. Для первой установки разумно следовать официальному примеру. Для корректной остановки контейнера документация также рекомендует увеличить время ожидания: параметр --stop-timeout 60 даёт Home Assistant время записать данные на диск.

7Шаг 4. Настройте Docker Compose (рекомендуемый способ)

Команда docker run неудобна для изменений: чтобы поменять параметр, нужно пересоздавать контейнер. Поэтому для постоянной работы опишите всё в файле Compose. Если вы запускали контейнер командой из шага 3, сначала удалите его: docker rm -f homeassistant. Создайте файл:

nano /opt/homeassistant/compose.yaml

Содержимое:

services:
  homeassistant:
    container_name: homeassistant
    image: "ghcr.io/home-assistant/home-assistant:stable"
    volumes:
      - /opt/homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
    stop_grace_period: 60s
    privileged: true
    network_mode: host
    environment:
      TZ: Europe/Moscow

Отступы в YAML обязательны: используйте пробелы, а не табуляции. Запустите контейнер из каталога с файлом:

cd /opt/homeassistant
docker compose up -d

Docker скачает образ (несколько сотен мегабайт) и запустит контейнер в фоне. Проверка состояния:

docker ps
docker logs -f homeassistant

Выход из просмотра журнала — Ctrl+C. При первом запуске в логах будут сообщения о создании файлов конфигурации в /config. Параметр stop_grace_period: 60s задаёт время на корректное завершение при остановке.

8Шаг 5. Откройте интерфейс на порту 8123

Подождите одну-две минуты, пока Home Assistant закончит первую инициализацию, и откройте в браузере:

http://IP-адрес-сервера:8123

Например, http://192.168.1.70:8123. Адрес homeassistant.local работает не всегда: он зависит от mDNS на вашем сервере, поэтому надёжнее обращаться по IP, закреплённому в роутере. Откроется мастер создания пользователя: задайте имя, пароль, название дома, расположение, часовой пояс и единицы измерения. После этого вы попадёте на главную панель.

9Шаг 6. Подключите USB-устройства: Zigbee-стик и другое

Контейнер не видит USB-устройства, пока их не пробросить. Сначала найдите стабильное имя на сервере:

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

Имена вида /dev/ttyUSB0 могут меняться после перезагрузки, а ссылки в by-id привязаны к конкретному устройству. Добавьте в сервис в файле Compose:

    devices:
      - /dev/serial/by-id/usb-ВАШЕ-УСТРОЙСТВО:/dev/zigbee

Путь после двоеточия — это адрес внутри контейнера, его вы будете указывать в настройках интеграции. Примените изменения командой docker compose up -d: контейнер пересоздастся. Если устройство не открывается, проверьте права на него и убедитесь, что его не занимает другая программа на хосте. Для Bluetooth нужны D-Bus и права, которые даёт privileged, плюс работающий Bluetooth-демон на хосте.

10Шаг 7. Обновление Home Assistant в контейнере

Из интерфейса контейнер не обновляется: кнопки обновления ядра в Container-установке нет. Образ загружают заново и пересоздают контейнер:

cd /opt/homeassistant
docker compose pull
docker compose up -d
docker image prune -f

Первая команда скачивает новый образ, вторая запускает контейнер с ним, третья удаляет неиспользуемые старые слои. Конфигурация остаётся в подключённом каталоге. Перед крупным обновлением сделайте копию:

sudo cp -a /opt/homeassistant/config /opt/homeassistant/config.bak

Тег stable удобен, но каждый раз подтягивает самую свежую версию. Хотите контролировать обновления — зафиксируйте номер версии в теге образа и повышайте вручную после чтения заметок о выпуске. Для отката верните прежний тег и восстановите копию. Автоматическое обновление контейнеров сторонними утилитами не рекомендуется: интеграции иногда ломаются после выхода новой версии, и лучше увидеть это в момент, когда вы за компьютером.

11Перезапуск и корректная остановка

Чтобы применить изменения в configuration.yaml, достаточно перезапуска из интерфейса либо команды:

docker restart homeassistant

Если вы изменили сам файл Compose (устройства, тома, переменные), нужна команда docker compose up -d: просто перезапуск настройки не подхватит. Остановка по умолчанию даёт контейнеру короткое время на завершение; именно поэтому в примере задан увеличенный интервал, чтобы база данных закрылась корректно.

12База данных: SQLite, MariaDB или PostgreSQL

По умолчанию история хранится в файле SQLite в каталоге конфигурации. Для небольшого дома этого достаточно. Если история большая или вы хотите вынести базу на отдельный диск, подключите внешний сервер. Добавьте сервис в Compose, например PostgreSQL:

  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: hass
      POSTGRES_PASSWORD: ЗАМЕНИТЕ_НА_СВОЙ_ПАРОЛЬ
      POSTGRES_DB: homeassistant
    volumes:
      - /opt/homeassistant/db:/var/lib/postgresql/data

Так как Home Assistant работает в сети хоста, а база публикуется на хосте, укажите порт в сервисе db (ports: - "127.0.0.1:5432:5432"), чтобы она не торчала наружу. В configuration.yaml добавьте подключение:

recorder:
  db_url: postgresql://hass:ЗАМЕНИТЕ_НА_СВОЙ_ПАРОЛЬ@127.0.0.1/homeassistant
  purge_keep_days: 14

Перезапустите Home Assistant. Пароль в примере замените на свой и лучше вынесите его в secrets.yaml. Параметр purge_keep_days ограничивает срок хранения истории и заметно снижает размер базы. Для MariaDB подход тот же, меняется образ и строка подключения.

13Полезные детали настройки

Доступ из-за обратного прокси

Если Home Assistant публикуется через обратный прокси (nginx, Caddy, Traefik), в configuration.yaml нужно разрешить прокси, иначе вы получите ошибку 400:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 192.168.1.10

Замените адрес на адрес вашего прокси и перезапустите контейнер. Порт 8123 напрямую в интернет не открывайте.

Редактирование конфигурации

Файлы лежат в подключённом каталоге, их можно править прямо на сервере. Перед перезапуском проверяйте корректность конфигурации через раздел инструментов разработчика в интерфейсе (название пункта может отличаться по версии), чтобы опечатка не уронила систему.

Права доступа

Внутри контейнера Home Assistant работает от суперпользователя, поэтому файлы в подключённом каталоге принадлежат root. Для редактирования используйте sudo или настройте права под своего пользователя.

Ограничение размера журналов Docker

Без ограничений журнал контейнера со временем занимает много места. В сервисе Compose задайте драйвер json-file с лимитом:

    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

HACS в Container

Магазин дополнений недоступен, но пользовательский магазин интеграций HACS устанавливается и в Container: скрипт запускают внутри каталога конфигурации, после чего контейнер перезапускают и добавляют интеграцию в интерфейсе. Актуальную команду берите в документации HACS.

Если есть проблемы с памятью

В документации Home Assistant для Container описана переменная окружения, отключающая библиотеку jemalloc, на случай странного потребления памяти. Включайте её только если столкнулись с такой проблемой.

14Типичные ошибки и решения

Симптом	Причина	Что сделать
Порт 8123 не отвечает	идёт инициализация, контейнер упал, закрыт порт, неверный IP	подождать, проверить docker ps и логи, открыть порт в брандмауэре
Нет автообнаружения	нет network_mode host, Docker Desktop, разные подсети	включить host-режим, использовать Linux, проверить подсеть
Ошибка 400 за прокси	прокси не в trusted_proxies	добавить блок http
Контейнер перезапускается	ошибка в YAML, повреждённая база, нет места	смотреть логи, вернуть копию конфигурации
Стик не виден	неверный путь, права, занят хостом	проверить devices и пересоздать контейнер
Нет магазина дополнений	в Container нет Supervisor	запускать сервисы контейнерами или выбрать HAOS

Страница на порту 8123 не открывается

• Подождите: инициализация занимает минуту-две, на слабом железе дольше.
• Выполните docker ps: контейнер должен быть в состоянии Up. Если он перезапускается, смотрите docker logs homeassistant.
• Проверьте IP сервера, порт 8123 и протокол http.
• Убедитесь, что порт не занят и не закрыт брандмауэром. В Ubuntu с UFW разрешите его: sudo ufw allow 8123/tcp.
• Если в Compose заданы публикация портов и network_mode: host одновременно, уберите публикацию: эти режимы несовместимы.

Контейнер постоянно перезапускается

Откройте журнал. Частые причины: ошибка в YAML-конфигурации (опечатка или табуляция вместо пробелов), повреждённая база после аварийного выключения, нехватка места. Временно переименуйте проблемный файл или восстановите копию конфигурации.

15Резервные копии в Container-установке

В Home Assistant OS копии охватывают всю систему вместе с дополнениями. В Container главным носителем состояния служит каталог конфигурации. Остановите контейнер и сохраните каталог целиком, чтобы файлы базы не оказались записанными наполовину:

cd /opt/homeassistant
docker compose stop
sudo tar -czf /root/ha-config-backup.tar.gz config
docker compose start

Архив копируйте на другой компьютер или сетевое хранилище, а не оставляйте на том же диске. Для регулярных копий настройте задачу cron, которая выполняет эти команды ночью. Встроенный раздел резервных копий в Container может быть ограничен, поэтому не считайте его единственной защитой. Восстановление: остановить контейнер, распаковать архив на место каталога и запустить снова.

16Переезд с Home Assistant OS на Container

Архив резервной копии HAOS нельзя просто развернуть в Container, потому что он включает дополнения и данные Supervisor. Практичный путь: перенести каталог конфигурации (configuration.yaml, .storage, файлы автоматизаций и панелей), а то, что раньше делали дополнения (MQTT-брокер, Zigbee2MQTT, редактор файлов), запустить отдельными контейнерами и заново указать адреса в интеграциях. Заранее сверьте список используемых дополнений.

17Как проверить, что установка работает правильно

Прежде чем добавлять устройства, убедитесь, что основа надёжна. Пройдите короткий список:

1. Выполните docker ps и убедитесь, что контейнер homeassistant в состоянии Up уже несколько минут и не перезапускается.
2. Перезагрузите сервер и проверьте, что контейнер поднялся сам благодаря политике unless-stopped, а служба Docker включена в автозагрузку (sudo systemctl enable docker).
3. Откройте интерфейс со смартфона в той же сети: так вы проверите и порт, и брандмауэр.
4. Перезапустите контейнер командой docker restart homeassistant и убедитесь, что настройки и пользователь на месте.
5. Сделайте тестовую резервную копию каталога конфигурации и проверьте, что архив открывается.
6. Посмотрите журнал: в нём не должно быть повторяющихся ошибок интеграций или базы данных.

18Что запускать рядом с Home Assistant

Поскольку магазина дополнений нет, типичные спутники запускаются отдельными сервисами в том же файле Compose: брокер MQTT (например, Eclipse Mosquitto), Zigbee2MQTT, сервис долгой истории. Каждому нужен свой каталог данных и при необходимости проброшенное устройство. В интеграции MQTT указываются адрес сервера, порт 1883 и учётные данные брокера. Подход гибче дополнений, но вы сами следите за обновлениями каждого контейнера. Если гибкость контейнеров вам не нужна, проще Home Assistant OS: Container выбирают осознанно, когда на сервере уже живут другие службы или нужен полный контроль над системой.

19Итог

Установка Home Assistant Container сводится к понятным действиям: подготовить Linux-сервер с Docker Engine, создать каталог конфигурации, описать сервис в compose.yaml с образом ghcr.io/home-assistant/home-assistant:stable и режимом network_mode: host, запустить его и открыть порт 8123. Взамен вы получаете гибкость и возможность держать на одном сервере много сервисов, но теряете магазин дополнений и обновление из интерфейса. Обновляйте образ командами docker compose pull и docker compose up -d, храните копию каталога конфигурации вне сервера и пробрасывайте USB-устройства по путям из /dev/serial/by-id.