Files
homegate/SIMPLE.md
DizelBadCoder eeffcfb616
All checks were successful
Test and publish Homegate / checks (push) Successful in 28s
Test and publish Homegate / publish (push) Successful in 12m47s
Add NPM certificate selection and read-only VDS certificate renewal sync
2026-10-15 05:12:03 +03:00

63 lines
5.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Homegate: запуск и настройка через браузер
Используйте образ `gitea.hyperdog.dev/dizyaka/homegate:0.5.0` после успешной публикации
версии в Gitea Actions. Содержимое [compose.simple.yaml](compose.simple.yaml) сохраните
на сервере как `compose.yaml`. Файл не содержит адресов, environment, secrets или паролей.
```sh
docker compose pull
docker compose up -d --remove-orphans
```
Для приватного пакета один раз выполните `docker login gitea.hyperdog.dev`.
Это авторизация скачивания образа; параметры Homegate через неё не передаются.
Откройте `http://IP-СЕРВЕРА:8098`. Панель открывается без логина и показывает форму
первой настройки. Укажите прямо в ней:
- IP NPM, домашние подсети и доменные зоны;
- URL административного API NPM, его логин и пароль;
- URL Pi-hole 6 и его пароль, режим «Pi-hole без пароля» либо ручной режим DNS;
- при необходимости другой URL SSH-конфига и PEM корневого CA для HTTPS API.
Нажмите **Сохранить и начать**, затем добавляйте сервисы и SSH-хосты. Вся последующая
настройка доступна в разделе **Настройки**. Адреса и credentials перечитываются
контроллером без перезапуска. Пустое поле пароля при редактировании сохраняет прежнее значение. Если в Pi-hole пароль
отключён, включите **Pi-hole без пароля**: сохранённый пароль подключения будет удалён,
и Homegate будет работать с API без токена сессии. Адрес Pi-hole укажите без `/admin` и `/api`.
UI, контроллер и SSH-export работают в одном контейнере. До завершения первой настройки
работает только UI; запросы к NPM/Pi-hole ещё не выполняются. Открытые порты: `8098` для
панели и `8099` для `/ssh-config`. До настройки UI принимает подключения с loopback,
RFC1918 и ULA адресов; после настройки действует список разрешённых подсетей.
Пароль NPM и, если включён, пароль Pi-hole вводятся в форме и сохраняются в config volume.
Они не возвращаются в API состояния, скачиваемом YAML или SSH-конфиге.
Локальные HTTPS сертификаты и ключ CA Homegate создаёт сам. Публичный корневой сертификат
скачивается в разделе **Сертификаты**; установите его на клиентские устройства для доверия HTTPS.
Для публичных доменов, например `disk.hyperdog.dev`, можно использовать сертификат NPM
без установки CA на устройства. В карточке сервиса выберите **Существующий сертификат
домашнего NPM** или **Копия из NPM на VDS — автообновление**. Подключение к VDS
задаётся в разделе **Настройки → Сертификаты с NPM на VDS**.
Подробные шаги и поведение при продлении: [CERTIFICATES.md](CERTIFICATES.md).
## Обновление с прежнего Compose
Сохраните имя проекта `homegate` и volumes `config`, `state`, `control` из прежнего файла.
Новый Compose использует те же данные: сервисы, SSH, история и CA сохраняются.
Замените файл на `compose.simple.yaml` и выполните команды выше. `--remove-orphans`
удаляет прежние отдельные контейнеры `initialize`, `ui`, `ssh-export`, освобождая их порты;
volumes остаются. Адреса и credentials API из прежнего окружения один раз введите в UI.
## Проверки
Unit/HTTP-тесты проверяют первичную настройку без env, LAN-доступ, сохранение credentials,
их отсутствие в публичных ответах, изменение API-подключений и остановку дочерних процессов.
`ci/check_compose.py` проверяет, что простой Compose не требует environment/configs/secrets.
Контейнерную проверку запускайте только локально на отдельном временном Compose-проекте:
`ci/smoke_setup.py` выполняется внутри контейнера с аргументом `write`, а после перезапуска —
с `verify`. Используются API-заглушки на loopback и временные пароли. В Gitea Actions
контейнеры Homegate не запускаются: только тесты, проверка Compose, сборка и публикация образа.