Установка одной командой

Хаб — это компьютер у вас дома (Raspberry Pi, мини-ПК, NUC), который держит связь с Zigbee-устройствами и мостом подключается к облаку Рокет Хоум. Управление и автоматизации работают в домашней сети, облако нужно для голоса, телефона и удалённого доступа. Как подготовить машину — Подготовка компьютера.

Установка

На машине под Ubuntu или Debian выполните одну команду:

curl -fsSL https://rocket-home.ru/install.sh | bash

Установщик всё поставит сам и запустит мастер первичной настройки. Ваше участие нужно на одном шаге — вход в аккаунт по ссылке.

Примечание

Если терминала нет — например, команду выполняет скрипт автоматизации или ssh без -t, — установка всё равно завершится, а мастер скажет об этом и предложит запустить себя позже командой rocket. Поставить сразу без мастера: добавьте -s -- --headless.

Примечание

Готовить машину заранее не нужно: Docker и Node.js ставит установщик. Нужны Ubuntu или Debian на процессоре amd64 или arm64 и около гигабайта свободного места. Что ещё понадобится — Что понадобится.

Что делает установщик

  1. Ставит пакеты: make, curl, git, jq, gettext-base, udev.

  2. Ставит Docker (официальный скрипт get.docker.com), если его ещё нет. Docker из snap не подходит: он не может работать с каталогом /opt/rocket-home. Установщик в этом случае остановится до любых изменений и подскажет, как его удалить.

  3. Ставит Node.js 22 LTS, если в системе нет Node 18 или новее. Отдельно проверяет npm: в Debian пакет nodejs идёт без него.

  4. Добавляет пользователя в группы docker и dialout (доступ к контейнерам и к USB-координатору).

  5. Скачивает инструмент в каталог /opt/rocket-home и переключает его на последний выпущенный релиз — не на «то, что сейчас в разработке».

  6. Заводит команду rocket.

Примечание

Группа docker начинает действовать только в новой сессии. Если rocket жалуется, что docker недоступен, — выйдите, зайдите снова и повторите. На свежей машине перезайти нужно почти всегда.

Мастер первичной настройки

Мастер идёт девятью шагами и показывает, на каком вы сейчас: Установка Rocket Home hub · шаг 3/9 · Прошивка. Перед каждым действием он печатает эквивалентную команду (→ make detect-device) — то же самое можно сделать руками, без мастера.

Шаг 1. Тулинг. Проверяет, что docker, jq, envsubst и остальное на месте, и создаёт файл настроек .env, сгенерировав пароли локального брокера.

Шаг 2. Координатор. Ищет подключённые Zigbee-стики (в мастере координатор так и называется — «стик») и предлагает выбрать нужный. Если его в списке нет, путь можно указать вручную или отложить настройку.

Примечание

«Пропустить (настрою позже)» доводит мастер только до шага 8: без координатора стек не поднимается, и мастер честно останавливается. Это нормальный исход, если координатор вы ждёте с доставкой, — вернётесь к мастеру, когда он приедет. Что при этом всё-таки можно запустить — диагностика.

Мастер установки предлагает выбрать Zigbee-координатор из найденных

Следом мастер предложит установить udev-правила: они закрепляют за координатором постоянное имя /dev/zigbee, и оно не «уедет», если переткнуть стик в другой порт.

Шаг 3. Прошивка. Сначала спрашивает разрешение — определение поднимает служебный контейнер и занимает минуту-две (на одноплатнике при первом запуске дольше: служебный образ ещё собирается), а работающий ZigBee2MQTT на это время останавливается (последовательный порт занимает кто-то один). Согласитесь: от ответа зависит следующий шаг. Если определить не удалось, семейство выбирается из списка вручную.

Ручной выбор семейства координатора, если автоопределение не удалось

Шаг 4. Версия ZigBee2MQTT. По матрице совместимости подбирает версию под вашу прошивку и предлагает её зафиксировать. Если семейство осталось неизвестным, мастер выберет консервативную версию и предложит обновиться позже — командой make update.

Шаг 5. Облако. Спрашивает, как хаб будет входить в облако: через rocket-home.ru (рекомендуется), по логину и паролю MQTT или совсем без облака. При первом варианте мастер покажет ссылку — откройте её, войдите и нажмите «Разрешить». Что сверить на странице и что делать, если локаций несколько, — Привязка хаба к облаку.

Шаг 6. Дополнения. Предлагает поставить Node-RED (локальные сценарии). По умолчанию — нет; включить его можно в любой момент позже.

Шаг 7. Конфигурация. Генерирует настройки ZigBee2MQTT и моста. Прежние версии файлов сохраняются рядом с суффиксом .bak-…. Уже существующий configuration.yaml мастер не трогает — переписать его можно только явно, FORCE=1 make gen-configs.

Шаг 8. Запуск. Поднимает контейнеры. Первый раз это несколько минут: образы скачиваются и собираются.

Шаг 9. Проверка. Сквозная проверка: локальный брокер → мост в облако → веб-интерфейс ZigBee2MQTT. В конце мастер печатает адрес этого интерфейса и токен входа в него — сохраните их.

Примечание

Проверка дожидается, пока ZigBee2MQTT поднимется (до трёх минут — после пересоздания контейнеров это нормально). Если она всё же покажет красное, установка на этом не обрывается: стек уже запущен, а повторить проверку можно командой make smoke.

Если мастер прервался, запустите его заново командой rocket → «Установка (визард)». Пройденные шаги он спросит снова — в том числе вход в облако, и код привязки будет новый.

Обновление хаба

Та же команда, что и при установке, но с флагом --headless — чтобы не запускался мастер:

curl -fsSL https://rocket-home.ru/install.sh | bash -s -- --headless

На уже установленной машине она не ставит всё заново, а обновляет /opt/rocket-home до последнего выпущенного релиза (список выпусков). Настройки, данные и токены (.env, data/, secrets/) не трогаются, контейнеры не перезапускаются. Чтобы применить обновление к работающему стеку, выполните make up.

Обновление самого ZigBee2MQTT — отдельная операция, по матрице совместимости: make update (см. Управление хабом).

Для опытных пользователей

Установщик принимает флаги — их передают после -s --:

# без мастера: только поставить и настроить окружение (годится для обновления)
curl -fsSL https://rocket-home.ru/install.sh | bash -s -- --headless

# зафиксировать конкретную версию инструмента (теги — в репозитории, ссылка ниже)
curl -fsSL https://rocket-home.ru/install.sh | bash -s -- --version=<тег>

# поставить в другой каталог
curl -fsSL https://rocket-home.ru/install.sh | bash -s -- --dir=/srv/rocket-home

Мастер — не единственный путь: то же самое делается руками теми командами, которые он и печатает.

cd /opt/rocket-home
make env-init                    # создать .env
make detect-device               # найти координатор: realpath и path для .env
make detect-firmware             # семейство и версия прошивки
nano .env                        # ZIGBEE_DEVICE_HOST, ZIGBEE_DEVICE_BYID, Z2M_ADAPTER, CLOUD_AUTH_MODE
make oauth-link                  # вход в аккаунт (если облако нужно)
make gen-configs up smoke

Важно

В ZIGBEE_DEVICE_HOST впишите реальный путь из поля realpath — например, /dev/ttyUSB0. Символическую ссылку (/dev/zigbee, /dev/serial/by-id/…) Docker как устройство не примет, и make up откажется. Ссылку из поля path сохраните в ZIGBEE_DEVICE_BYID — это постоянное имя стика. Если после пересадки в другой порт реальный путь сменился, make up остановится и предложит найти стик заново — make detect-device.

Важно

CLOUD_AUTH_MODE — как хаб входит в облако: oauth (по умолчанию, вход по ссылке — make oauth-link, см. Привязка хаба к облаку), static (логин и пароль MQTT из кабинета) или off — без облака, хаб работает только в домашней сети.

Важно

Z2M_ADAPTER (ember, zstack, deconz, zigate) заполняйте обязательно: из него берётся строка adapter в настройках ZigBee2MQTT, а без неё версии 2.x отказываются стартовать — No valid USB adapter found.

Совет

Как управлять хабом после установки, что делает каждая команда и как переподключить облако — страница управления хабом. Если что-то не завелось — диагностика.

Исходный код установщика открыт: rocket-home/rocket-installer. Какая версия ставится по умолчанию, видно там же в списке выпусков — установщик берёт последний тег.

Что дальше