Initial Homegate 0.4.0 with web UI, Compose and Gitea Actions
This commit is contained in:
246
REGISTRY.md
Normal file
246
REGISTRY.md
Normal file
@@ -0,0 +1,246 @@
|
||||
# Один Compose-файл и Gitea Container Registry
|
||||
|
||||
Homegate 0.4 поддерживает два способа установки:
|
||||
|
||||
| Файл | Назначение |
|
||||
| --- | --- |
|
||||
| `compose.registry.yaml` | Готовый образ из Gitea; именованные volumes, автоматическая первичная настройка |
|
||||
| `compose.yaml` | Прежний запуск из исходников с `build`, `setup.sh` и каталогами на хосте |
|
||||
|
||||
Gitea здесь ещё не подключена, образ не опубликован. Workflow готов к запуску в вашем
|
||||
репозитории. Имена `git.example.home` и `your-user` ниже — примеры.
|
||||
|
||||
## 1. Настройте репозиторий и runner один раз
|
||||
|
||||
Загрузите содержимое каталога проекта в корень репозитория Gitea, включая скрытую папку
|
||||
`.gitea/workflows/`. Включите **Enable Repository Actions** в настройках репозитория.
|
||||
В Gitea должен быть включён Package Registry.
|
||||
|
||||
Workflow использует выделенный **Linux runner** с меткой `homegate:host`:
|
||||
|
||||
- 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: homegate`; если у вашего runner другое имя метки, замените
|
||||
его в обоих jobs. Для runner с контейнерными jobs нужна специально подготовленная среда,
|
||||
включающая эти инструменты и доступ к Docker daemon. Шаблон рассчитан на `homegate:host`.
|
||||
Используйте отдельную 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 или панели — они нужны только при развёртывании.
|
||||
|
||||
По умолчанию registry берётся из адреса Gitea, image — из `owner/repository` в нижнем регистре:
|
||||
|
||||
```text
|
||||
git.example.home/your-user/homegate:0.4.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.4.0`. После загрузки проверенного кода в Gitea:
|
||||
|
||||
```sh
|
||||
git tag v0.4.0
|
||||
git push origin v0.4.0
|
||||
```
|
||||
|
||||
При следующем выпуске измените `VERSION`, закоммитьте его вместе с изменениями и создайте
|
||||
соответствующий тег. Тег должен совпасть с файлом `VERSION`: например `v0.4.1` и `0.4.1`.
|
||||
Предварительные версии вида `v0.4.1-rc.1` также поддерживаются. Полный номер задаётся
|
||||
в `VERSION`; примеры в Compose, Dockerfile и документации при выпуске также обновите.
|
||||
|
||||
Workflow `.gitea/workflows/release.yaml` выполняет:
|
||||
|
||||
1. На push в ветку, тег или PR — Python/HTTP-тесты, проверку JavaScript и shell,
|
||||
проверку обоих Compose-файлов.
|
||||
2. Сборку образа для архитектуры runner и пробный запуск изолированного стека без
|
||||
портов хоста и доступа к NPM/Pi-hole. Проверяются вход по паролю, сохранение
|
||||
настроек, права volumes, отсутствие чужих secrets в UI и сохранность CA после повторной инициализации.
|
||||
3. Только для push тега `v*`, после успешных проверок — проверку `VERSION`, сборку
|
||||
`linux/amd64` + `linux/arm64` и публикацию в Gitea Container Registry.
|
||||
|
||||
Образ получает два тега: `0.4.0` и `sha-<полный SHA коммита>`. Тег `latest` не создаётся.
|
||||
`org.opencontainers.image.source` связывает метаданные образа с URL исходников.
|
||||
Права на просмотр/скачивание пакета проверьте в Gitea Packages отдельно от доступа к коду.
|
||||
Workflow не меняет видимость пакетов и не развёртывает Homegate на домашнем сервере.
|
||||
|
||||
Для runtime-тестов локально, если Docker запущен:
|
||||
|
||||
```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.4.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.4.1
|
||||
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.
|
||||
|
||||
## Что проверено
|
||||
|
||||
Локально проходят 55 тестов, включая первый запуск, сохранение пользовательских изменений
|
||||
и CA, отказ от повреждённого конфига и проверку адреса/версии публикуемого образа.
|
||||
Оба Compose-файла проверяются установленным Docker Compose. Синтаксис shell, JavaScript
|
||||
и YAML workflow проверен. Docker daemon при подготовке выключен, поэтому сборка образа,
|
||||
контейнерный smoke-test и исполнение самого workflow должны впервые пройти на вашем runner.
|
||||
|
||||
Официальные контракты: [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/).
|
||||
Reference in New Issue
Block a user