Команда docker pull homeassistant/home-assistant завершается ошибкой «manifest not found» или контейнер стартует и сразу падает — типичная ситуация, когда образ Home Assistant скачан не с того репозитория на Docker Hub или запущен без обязательных параметров. Официальный репозиторий проекта на Docker Hub называется homeassistant/home-assistant, и именно его нужно указывать целиком: сокращённое имя вроде home-assistant без префикса организации приведёт к поиску несуществующего образа.
В этой статье разберём, какой образ выбрать на Docker Hub, как правильно запустить контейнер через docker run и docker compose, как обновлять Home Assistant без потери конфигурации и какие ограничения есть у контейнерной установки по сравнению с Home Assistant OS.
Какие образы Home Assistant есть на Docker Hub
На Docker Hub проект публикует несколько репозиториев, и путаница между ними — частая причина ошибок при установке. Основной образ для пользовательской установки — homeassistant/home-assistant. Он содержит Home Assistant Core в готовом контейнере и подходит для большинства сценариев на Linux-хостах.
Кроме основного, существуют вспомогательные образы: homeassistant/amd64-hassio-supervisor и аналогичные под другие архитектуры используются установщиком Home Assistant Supervised, а образы аддонов (например, Mosquitto, MariaDB) публикуются отдельно. Вручную образы Supervisor скачивать и запускать не нужно — это делает установочный скрипт.
Теги образа homeassistant/home-assistant включают latest, stable и конкретные версии вида 2026.12.5. Для воспроизводимой установки лучше фиксировать версию, а не использовать latest: так вы контролируете момент обновления и можете быстро откатиться на предыдущий тег.
- 🏠
homeassistant/home-assistant— основной образ Home Assistant Container - 🧩
homeassistant/*-hassio-supervisor— образы для установки Supervised - 🔌 Образы аддонов — отдельные репозитории для сервисов вроде MQTT-брокера
- 🏷️ Теги:
latest,stableи конкретные номера версий
Home Assistant Container против Home Assistant OS
Перед установкой стоит понимать ключевое ограничение: Home Assistant Container не включает Supervisor, а значит, в нём нет магазина аддонов и системы автоматических резервных копий в привычном виде. Всё, что в HA OS ставится «в один клик» (Mosquitto, Zigbee2MQTT, Node-RED), в контейнерном варианте разворачивается отдельными контейнерами и подключается вручную.
Зато Container-вариант даёт полный контроль над хостом: вы сами управляете сетью, томами, обновлениями и можете держать на одной машине другие сервисы. Для опытных пользователей Docker это часто предпочтительнее, чем выделенная ОС.
| Критерий | HA Container (Docker Hub) | Home Assistant OS |
|---|---|---|
| Supervisor и аддоны | Нет | Да, из коробки |
| Управление хостом | Полный доступ пользователя | Закрытая управляемая ОС |
| Обновление | Пересоздание контейнера вручную | Кнопка в интерфейсе |
| Резервные копии | Архивация папки конфигурации | Встроенный механизм бэкапов |
| Порог входа | Нужен опыт работы с Docker | Минимальный |
Установка через docker run
Базовый запуск выполняется одной командой. Ключевые параметры: проброс папки конфигурации, сетевой режим host (нужен для автоматического обнаружения устройств в локальной сети) и политика перезапуска.
docker run -d \
--name homeassistant \
--privileged \
--restart=unless-stopped \
-e TZ=Europe/Moscow \
-v /opt/homeassistant:/config \
--network=host \
homeassistant/home-assistant:stable
Разберём важные моменты. Параметр -v /opt/homeassistant:/config монтирует папку хоста в контейнер — именно там лежат configuration.yaml и вся база данных. Без этого тома при пересоздании контейнера конфигурация будет потеряна. Режим --network=host работает только на Linux; на Windows и macOS Docker работает через виртуальную машину, и host-сеть там не даёт того же эффекта.
☑️ Проверка после первого запуска
⚠️ Внимание: флаг--privilegedдаёт контейнеру расширенный доступ к устройствам хоста. Он упрощает проброс USB-стиков (Zigbee, Z-Wave), но снижает изоляцию. Если USB-устройств нет, запускайте без этого флага и пробрасывайте устройства точечно через--device=/dev/ttyUSB0.
После запуска интерфейс будет доступен по адресу http://IP-хоста:8123. Первая загрузка может занять несколько минут — контейнер создаёт базу данных и начальную конфигурацию.
Установка через Docker Compose
Для постоянной эксплуатации удобнее описать сервис в файле docker-compose.yml — так конфигурация хранится в виде кода и легко переносится между машинами.
services:
homeassistant:
container_name: homeassistant
image: homeassistant/home-assistant:stable
volumes:
- /opt/homeassistant:/config
- /etc/localtime:/etc/localtime:ro
restart: unless-stopped
privileged: true
network_mode: host
Запуск выполняется командой docker compose up -d из папки с файлом. Обратите внимание на монтирование /etc/localtime в режиме только чтения — это синхронизирует время контейнера с хостом, что критично для корректной работы автоматизаций по расписанию.
Обновление контейнера до новой версии
Обновление Home Assistant в Docker сводится к трём шагам: скачать новый образ, остановить и удалить старый контейнер, запустить новый с теми же параметрами. Конфигурация сохраняется, потому что лежит в смонтированной папке на хосте, а не внутри контейнера.
docker pull homeassistant/home-assistant:stable
docker stop homeassistant
docker rm homeassistant
docker compose up -d
При использовании Compose достаточно docker compose pull и docker compose up -d — пересоздание произойдёт автоматически. Перед обновлением сделайте копию папки конфигурации: откат образа на старый тег возможен, но база данных, уже мигрированная на новую версию, может оказаться несовместимой со старой.
⚠️ Внимание: не обновляйтесь сразу на свежий мажорный релиз, если у вас критичные автоматизации. Проверьте примечания к релизу на предмет ломающих изменений (breaking changes) — они публикуются в официальном блоге проекта для каждой версии.
Проброс USB-устройств и сетевые нюансы
Если вы используете Zigbee- или Z-Wave-стик, его нужно пробросить в контейнер. Сначала определите путь устройства на хосте командой ls /dev/serial/by-id/ — путь вида /dev/serial/by-id/usb-... предпочтительнее, чем /dev/ttyUSB0, так как не меняется при переподключении.
devices:
- /dev/serial/by-id/usb-ITead_Sonoff_Zigbee:/dev/ttyUSB0
По сети есть важный нюанс: режим host необходим для работы функций обнаружения (mDNS, SSDP), через которые Home Assistant находит умные устройства в локальной сети. Если вы используете bridge-сеть с пробросом портов, автоматическое обнаружение может не работать, и интеграции придётся добавлять вручную по IP-адресам.
Что делать, если устройства не обнаруживаются автоматически
Проверьте, что контейнер запущен с network_mode: host. Убедитесь, что устройство и хост находятся в одной подсети — mDNS не проходит через маршрутизаторы и VLAN без дополнительной настройки. Если используете VLAN для IoT-устройств, потребуется mDNS-репитер (например, avahi с включённым reflection) на маршрутизаторе или хосте.
Типичные ошибки и их решение
Разберём проблемы, с которыми чаще всего сталкиваются при работе с образом Home Assistant с Docker Hub.
- 🔴 Ошибка «manifest unknown» — указан несуществующий тег или опечатка в имени репозитория. Проверьте точное имя:
homeassistant/home-assistant. - 🔴 Контейнер перезапускается в цикле — смотрите логи командой
docker logs homeassistant. Частая причина — повреждённыйconfiguration.yamlпосле правки. - 🔴 Нет доступа к USB-устройству — не хватает прав: добавьте
--privilegedили настройте права на устройство на хосте. - 🔴 Неправильное время в логах и автоматизациях — не задана переменная
TZи не смонтирован/etc/localtime. - 🔴 Порт 8123 недоступен снаружи — при host-сети проверьте файрвол хоста, при bridge-сети — проброс портов
-p 8123:8123.
Если контейнер стартует, но веб-интерфейс не открывается, сначала проверьте docker ps — жив ли контейнер, затем docker logs homeassistant --tail 50 — нет ли ошибок конфигурации. Home Assistant при синтаксической ошибке в YAML может не поднять веб-сервер, и это будет видно в логе.
Резервное копирование конфигурации
Поскольку в Container-версии нет встроенных бэкапов Supervisor, за сохранность данных отвечаете вы. Хорошая новость: достаточно архивировать одну папку — ту, что смонтирована в /config.
Простой вариант — периодическое создание архива:
tar -czf ha-backup-$(date +%F).tar.gz /opt/homeassistantДелать архив лучше при остановленном контейнере, чтобы база данных не была в процессе записи, либо использовать средства самой СУБД, если вы вынесли базу во внешний PostgreSQL или MariaDB. Также удобно хранить папку конфигурации в git-репозитории, исключив из него файлы базы данных и секреты.
Часто задаваемые вопросы
Какой официальный образ Home Assistant на Docker Hub?
Официальный репозиторий — homeassistant/home-assistant. Образы от других авторов с похожими именами не поддерживаются проектом и могут содержать устаревшие или модифицированные версии.
Можно ли установить аддоны в Home Assistant Container?
Нет, магазин аддонов доступен только в установках с Supervisor (HA OS и Supervised). В контейнерном варианте аналогичные сервисы запускаются отдельными контейнерами — например, официальный образ Mosquitto для MQTT.
Работает ли Home Assistant Container на Windows?
Контейнер запускается через Docker Desktop, но с ограничениями: host-сеть и проброс USB работают иначе, чем на Linux, поэтому обнаружение устройств и подключение Zigbee-стиков могут быть затруднены. Для полноценной работы рекомендуется Linux-хост.
Как откатиться на предыдущую версию?
Укажите в compose-файле тег предыдущей версии (например, конкретный номер вместо stable) и пересоздайте контейнер. Однако если новая версия уже мигрировала базу данных, для чистого отката понадобится резервная копия конфигурации, сделанная до обновления.
Потеряются ли настройки при пересоздании контейнера?
Нет, если папка конфигурации смонтирована как том (-v /opt/homeassistant:/config). Все настройки, интеграции и история хранятся на хосте. Без монтирования тома данные внутри контейнера будут удалены вместе с ним.