Files
homegate/REGISTRY.md
DizelBadCoder 5661de72b7
All checks were successful
Test and publish Homegate / checks (push) Successful in 29s
Test and publish Homegate / publish (push) Successful in 12m43s
Add UI DNS challenge issuance and automatic home NPM renewal
2026-10-15 05:42:15 +03:00

284 lines
21 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.

# Один Compose-файл и Gitea Container Registry
Для запуска без environment, secrets и пароля панели используйте [compose.simple.yaml](SIMPLE.md):
все адреса и подключения задаются в UI. Ниже описан расширенный вариант с отдельными контейнерами.
Homegate 0.4 поддерживает два способа установки:
| Файл | Назначение |
| --- | --- |
| `compose.registry.yaml` | Готовый образ из Gitea; именованные volumes, автоматическая первичная настройка |
| `compose.yaml` | Прежний запуск из исходников с `build`, `setup.sh` и каталогами на хосте |
Для установки дождитесь успешной публикации образа в Gitea Actions.
Имена `git.example.home` и `your-user` ниже — примеры.
В варианте с одним файлом Compose записывает `configs.content` и `secrets.environment`
в файловую систему контейнера до его запуска. Поэтому у `initialize`, `homegate` и `ui`
задано `read_only: false`; у `ssh-export` остаётся `read_only: true`. Иначе создание
контейнера завершается ошибкой `cannot create config/secret ... in read-only service`.
Это ограничение проверяется в `ci/check_compose.py` без запуска контейнеров.
Ограничения UID, capabilities и `no-new-privileges` сохраняются. В варианте установки
из исходников configs/secrets берутся из файлов на хосте и не требуют этого исключения.
Если скачали ранний `compose.registry.yaml` для `0.4.0`, добавьте `read_only: false`
в каждый из сервисов `initialize`, `homegate`, `ui` после `<<: *runtime`, затем выполните
`docker compose up -d`. Исправление совместимо с образом `0.4.0`; новый образ не нужен.
Сохраняйте прежнее имя Compose-проекта и volumes с настройками и CA.
## 1. Настройте репозиторий и runner один раз
Загрузите содержимое каталога проекта в корень репозитория Gitea, включая скрытую папку
`.gitea/workflows/`. Включите **Enable Repository Actions** в настройках репозитория.
В Gitea должен быть включён Package Registry.
Оба job используют **Linux runner** с меткой `ubuntu-latest`. Среда job должна содержать:
- Python 3.11+ с `venv` и pip, Git, OpenSSH client, Bash, Node.js 20+;
- Docker Engine, Buildx и Docker Compose **2.30.0+**;
- права на использование Docker и установку QEMU/binfmt через `setup-qemu-action`;
- доступ к Gitea/registry, GitHub для загрузки actions, Docker Hub и PyPI при сборке.
Метка в workflow — `runs-on: ubuntu-latest`; зарегистрируйте runner с этой меткой.
Для runner с контейнерными jobs среда job должна включать перечисленные инструменты
и доступ к Docker daemon.
Используйте отдельную VM для сборок: job исполняет код репозитория и имеет доступ к Docker.
Внешние PR запускайте только после проверки авторства и содержимого либо на изолированном
одноразовом runner. Registry secrets используются только в job публикации Git-тега.
В **Repository Settings → Actions → Secrets** добавьте:
| Secret | Значение |
| --- | --- |
| `REGISTRY_USERNAME` | Пользователь Gitea, которому разрешено публиковать пакеты владельца репозитория |
| `REGISTRY_TOKEN` | Personal access token этого пользователя с правом `write:package` |
Для репозитория организации учётная запись должна иметь право записи её пакетов.
Встроенный `GITEA_TOKEN` используется только для checkout; отдельный registry token
обеспечивает совместимость с инсталляциями, где job token не может публиковать пакеты.
Не добавляйте сюда пароли NPM, Pi-hole или панели — они нужны только при развёртывании.
Если публикация завершается с `Password required`, шаг входа в registry получил пустой
`REGISTRY_TOKEN`. Предупреждение Node.js про `punycode` не является причиной этой ошибки.
В **User Settings → Applications → Manage Access Tokens** создайте токен с правом
`write:package`, затем сохраните его значение в **Repository Settings → Actions → Secrets**
под именем `REGISTRY_TOKEN`. `REGISTRY_USERNAME` должен содержать логин владельца токена.
Значения в **Actions → Variables**, `.env` production-сервера или окружении runner
не подставляются в `${{ secrets.REGISTRY_TOKEN }}`.
После сохранения secrets повторно запустите упавший workflow для того же тега через
**Re-run** в Actions. Для исправления credentials новый тег не нужен. Workflow проверяет
наличие обоих secrets в начале job публикации, не выводя их значения в лог.
Эта проверка не проверяет права токена: корректность credentials проверяет вход в registry,
а право на публикацию — push образа.
По умолчанию registry берётся из адреса Gitea, image — из `owner/repository` в нижнем регистре:
```text
git.example.home/your-user/homegate:0.6.0
```
Если registry доступен по другому имени/порту, задайте Actions **variable** `REGISTRY`,
например `registry.example.home:5000`, без `https://` и без пути. Этот адрес должен действительно
обслуживать Gitea Container Registry. Для имён владельца/репозитория используйте латинские
буквы, цифры и разделители, допустимые в Docker image names.
Для Gitea с локальным CA настройте доверие к CA у runner, Docker daemon и BuildKit builder.
В workflow не отключается TLS-проверка. Если используете отдельный builder, его настройка
доверия независима от системного хранилища сертификатов.
## 2. Выпустите образ
Файл `VERSION` сейчас содержит `0.6.0`. После загрузки проверенного кода в Gitea:
```sh
git tag v0.6.0
git push origin v0.6.0
```
При следующем выпуске измените `VERSION`, закоммитьте его вместе с изменениями и создайте
соответствующий тег. Тег должен совпасть с файлом `VERSION`: например `v0.6.0` и `0.6.0`.
Предварительные версии вида `v0.6.0-rc.1` также поддерживаются. Полный номер задаётся
в `VERSION`; примеры в Compose, Dockerfile и документации при выпуске также обновите.
Workflow `.gitea/workflows/release.yaml` выполняет:
1. На push в ветку, тег или PR — Python/HTTP-тесты, проверку JavaScript и shell,
проверку обоих Compose-файлов.
2. Сборку образа для архитектуры runner без запуска контейнеров Homegate.
Локальный тег проверочного образа удаляется после сборки.
3. Только для push тега `v*`, после успешных проверок — проверку `VERSION`, сборку
`linux/amd64` + `linux/arm64` и публикацию в Gitea Container Registry.
Образ получает два тега: `0.6.0` и `sha-<полный SHA коммита>`. Тег `latest` не создаётся.
`org.opencontainers.image.source` связывает метаданные образа с URL исходников.
Права на просмотр/скачивание пакета проверьте в Gitea Packages отдельно от доступа к коду.
Workflow не запускает контейнеры Homegate и не развёртывает приложение.
Собранный образ скачивается и запускается отдельно на production-сервере по инструкции ниже.
Видимость пакетов workflow не меняет.
Необязательный runtime-тест можно запустить вручную локально, если Docker запущен.
Gitea Actions этот скрипт не выполняет:
```sh
docker build --build-arg VERSION="$(cat VERSION)" -t homegate:test .
sh ci/smoke_image.sh homegate:test
```
Тест создаёт временный Compose-проект со случайным именем `homegate-smoke-*` и удаляет
только его контейнеры и volumes при завершении. Образ не публикуется.
## 3. Разверните, скачав только Compose
Скопируйте **только `compose.registry.yaml`** на Linux Docker-хост и переименуйте
в `compose.yaml`. Клонировать проект, устанавливать Python и запускать `setup.sh` не нужно.
В Bash укажите свои адреса. Здесь `.10`, `.11` и `.2` — примеры:
```bash
export HOMEGATE_IMAGE=git.example.home/your-user/homegate:0.6.0
export HOMEGATE_LAN_IP=192.168.0.10
export HOMEGATE_PROXY_IP=192.168.0.11
export HOMEGATE_ALLOWED_NETWORKS='[192.168.0.0/24]'
export HOMEGATE_ZONES='[home, home.arpa, lab.internal]'
export UI_ORIGIN=http://192.168.0.10:8098
export NPM_URL=http://192.168.0.11:81
export NPM_IDENTITY=admin@example.com
export PIHOLE_URL=http://192.168.0.2
read -rsp 'Пароль панели (от 12 символов): ' UI_PASSWORD; printf '\n'
read -rsp 'Пароль NPM: ' NPM_PASSWORD; printf '\n'
read -rsp 'Пароль Pi-hole: ' PIHOLE_PASSWORD; printf '\n'
export UI_PASSWORD NPM_PASSWORD PIHOLE_PASSWORD
```
Пароли вводятся скрыто, не записываются в Compose и не передаются как environment контейнера:
Compose монтирует их отдельными secret-файлами только в нужные сервисы. Имена параметров,
которые заканчиваются на `_IP`, принимают приватные IP. `HOMEGATE_LAN_IP` — IPv4 Docker-хоста,
`HOMEGATE_PROXY_IP` — адрес NPM. Это могут быть разные машины.
Для Pi-hole 5 или ручного DNS вместо автоматического режима:
```bash
export HOMEGATE_DNS_MODE=manual
export PIHOLE_PASSWORD=not-used
```
Для приватного образа войдите в registry, указав свой Gitea username и token вместо пароля:
```sh
docker login git.example.home
docker compose pull
docker compose up -d
```
Для общедоступного образа `docker login` не нужен. Остальные команды одинаковы.
Не публикуйте порты через NAT роутера или внешние туннели.
Откройте `UI_ORIGIN`. Вход — паролем панели. Начальный список сервисов пуст:
добавьте нужные VM в интерфейсе. Контроллер получает конфигурацию из того же volume.
Защищённый HTTPS сервисов потребует установки корневого CA на клиентские устройства.
О настройке HTTPS самой панели см. [WEB.md](WEB.md#https-самой-панели).
`HOMEGATE_ZONES`, `HOMEGATE_PROXY_IP`, `HOMEGATE_ALLOWED_NETWORKS`, `HOMEGATE_DNS_MODE`
используются для начального YAML **только один раз**. После первого запуска изменяйте
эти настройки в панели. Изменение seed в Compose при обновлении не затирает ваши настройки.
Зоны лучше определить до первого запуска CA; расширение списка позже может потребовать
явной смены CA по [DOMAINS.md](DOMAINS.md).
Переменные нужны Compose и при последующих `up`, `pull`, `run` и `exec`; после закрытия
терминала задайте их снова. По желанию можно сохранить их в локальном `.env` с правами `600`
и исключить его из Git. Дополнительный файл не является обязательным.
Если административные API используют локальный HTTPS CA, его PEM bundle можно скопировать
в volume конфигурации по примеру импорта ниже и указать `API_CA_BUNDLE=/config/management-ca.pem`.
CA самой VM для `upstream_ca_file` по-прежнему устанавливается отдельно внутри NPM.
## Хранение, обновление и восстановление
Создаются volumes `homegate_config`, `homegate_state`, `homegate_control` (префикс зависит
от имени Compose-проекта). Не меняйте имя проекта при обычном обновлении, иначе Docker
создаст другой набор volumes и новый CA.
| Volume | Содержимое | У кого есть доступ |
| --- | --- | --- |
| config | YAML, его резервные копии, необязательный management CA | UI — запись; контроллер и SSH-export — чтение |
| state | Закрытый ключ CA, выданные сертификаты, реестр NPM | Только контроллер |
| control | Публичное состояние и запросы синхронизации | UI и контроллер |
Инициализатор однократно запускается от root без сети, портов и паролей: готовит права
каталогов для UID/GID `1000:1000`, создаёт YAML только при отсутствии, затем завершается.
При новом запуске он проверяет существующий файл и сохраняет его. Остальные сервисы
всегда работают от UID/GID `1000:1000`. Инициализатор не выпускает и не заменяет CA.
Обновление до уже опубликованной версии:
```sh
export HOMEGATE_IMAGE=git.example.home/your-user/homegate:0.6.0
docker compose pull
docker compose up -d
```
Обычные `up`, `restart` и `down` сохраняют volumes. **`docker compose down -v` удалит данные,
включая доверенный CA.** Сделайте резервную копию перед обновлением. Удаление state при
сохранённых настройках в NPM означает потерю ключа и связей с ранее созданными объектами.
Экспорт YAML и публичного CA:
```sh
docker compose cp ui:/config/services.yaml ./services.backup.yaml
docker compose cp homegate:/data/root-ca.crt ./root-ca.crt
```
Для полной резервной копии остановите три долгоживущих сервиса, чтобы YAML и реестр
не менялись во время копирования. Архив state содержит приватные ключи:
```sh
umask 077
mkdir -p backup/config backup/state backup/control
docker compose stop homegate ui ssh-export
docker compose cp ui:/config/. ./backup/config/
docker compose cp homegate:/data/. ./backup/state/
docker compose cp ui:/control/. ./backup/control/
docker compose start homegate ui ssh-export
```
При восстановлении используйте тот же Compose project name, сначала запустите только
`initialize`, затем импортируйте файлы через одноразовый контейнер `initialize`
(`docker compose run --rm --no-deps -T --entrypoint python initialize -c ...`).
Он видит все три volumes и имеет права выставить владельца восстановленных файлов `1000:1000`.
Не запускайте контроллер с пустым state до импорта резервной копии CA и реестра.
Для разового импорта YAML без копирования закрытых ключей:
```sh
docker compose stop homegate ui ssh-export
docker compose run --rm --no-deps -T --entrypoint python ui -c \
'import sys; from pathlib import Path; Path("/config/services.yaml").write_bytes(sys.stdin.buffer.read())' \
< services.backup.yaml
docker compose run --rm --no-deps homegate validate
docker compose start homegate ui ssh-export
```
Команды предполагают, что volumes уже инициализированы. Миграцию существующей установки
на bind mounts выполняйте через резервное копирование: автоматический перенос старого `state/`
в новые volumes не выполняется. Используйте новое имя Compose-проекта во время подготовки
миграции; старый стек остановите перед запуском нового на тех же портах/API.
## Что проверено
Локально проходят 63 теста, включая первый запуск, сохранение пользовательских изменений
и CA, отказ от повреждённого конфига и проверку адреса/версии публикуемого образа.
Оба Compose-файла проверяются установленным Docker Compose, включая совместимость
`read_only` с источниками configs/secrets. Синтаксис shell, JavaScript и YAML workflow проверен.
После исправления `read_only` локально проверены сборка образа для ARM64 и контейнерный
smoke-test на Docker Compose 5.3.1: инициализация volumes, вход в панель, изоляция secrets,
SSH-export и сохранение настроек/CA при повторной инициализации. Проверка использует
временные volumes без портов хоста и без доступа к NPM/Pi-hole; их реальные API этим тестом
не проверяются. Контейнерный smoke-test остаётся ручной проверкой и исключён из Gitea Actions.
Официальные контракты: [Gitea Container Registry](https://docs.gitea.com/usage/packages/container/),
[Gitea Actions](https://docs.gitea.com/usage/actions/quickstart/),
[Compose secrets из environment](https://docs.docker.com/reference/compose-file/secrets/),
[Compose configs с content](https://docs.docker.com/reference/compose-file/configs/),
[ограничение read_only в реализации Compose](https://github.com/docker/compose/blob/v2.40.0/pkg/compose/secrets.go).