21 KiB
Один Compose-файл и Gitea Container Registry
Для запуска без environment, secrets и пароля панели используйте compose.simple.yaml: все адреса и подключения задаются в 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 в нижнем регистре:
git.example.home/your-user/homegate:0.4.2
Если 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.2. После загрузки проверенного кода в Gitea:
git tag v0.4.2
git push origin v0.4.2
При следующем выпуске измените VERSION, закоммитьте его вместе с изменениями и создайте
соответствующий тег. Тег должен совпасть с файлом VERSION: например v0.4.2 и 0.4.2.
Предварительные версии вида v0.4.2-rc.1 также поддерживаются. Полный номер задаётся
в VERSION; примеры в Compose, Dockerfile и документации при выпуске также обновите.
Workflow .gitea/workflows/release.yaml выполняет:
- На push в ветку, тег или PR — Python/HTTP-тесты, проверку JavaScript и shell, проверку обоих Compose-файлов.
- Сборку образа для архитектуры runner без запуска контейнеров Homegate. Локальный тег проверочного образа удаляется после сборки.
- Только для push тега
v*, после успешных проверок — проверкуVERSION, сборкуlinux/amd64+linux/arm64и публикацию в Gitea Container Registry.
Образ получает два тега: 0.4.2 и sha-<полный SHA коммита>. Тег latest не создаётся.
org.opencontainers.image.source связывает метаданные образа с URL исходников.
Права на просмотр/скачивание пакета проверьте в Gitea Packages отдельно от доступа к коду.
Workflow не запускает контейнеры Homegate и не развёртывает приложение.
Собранный образ скачивается и запускается отдельно на production-сервере по инструкции ниже.
Видимость пакетов workflow не меняет.
Необязательный runtime-тест можно запустить вручную локально, если Docker запущен. Gitea Actions этот скрипт не выполняет:
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 — примеры:
export HOMEGATE_IMAGE=git.example.home/your-user/homegate:0.4.2
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 вместо автоматического режима:
export HOMEGATE_DNS_MODE=manual
export PIHOLE_PASSWORD=not-used
Для приватного образа войдите в registry, указав свой Gitea username и token вместо пароля:
docker login git.example.home
docker compose pull
docker compose up -d
Для общедоступного образа docker login не нужен. Остальные команды одинаковы.
Не публикуйте порты через NAT роутера или внешние туннели.
Откройте UI_ORIGIN. Вход — паролем панели. Начальный список сервисов пуст:
добавьте нужные VM в интерфейсе. Контроллер получает конфигурацию из того же volume.
Защищённый HTTPS сервисов потребует установки корневого CA на клиентские устройства.
О настройке HTTPS самой панели см. WEB.md.
HOMEGATE_ZONES, HOMEGATE_PROXY_IP, HOMEGATE_ALLOWED_NETWORKS, HOMEGATE_DNS_MODE
используются для начального YAML только один раз. После первого запуска изменяйте
эти настройки в панели. Изменение seed в Compose при обновлении не затирает ваши настройки.
Зоны лучше определить до первого запуска CA; расширение списка позже может потребовать
явной смены CA по 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.
Обновление до уже опубликованной версии:
export HOMEGATE_IMAGE=git.example.home/your-user/homegate:0.4.2
docker compose pull
docker compose up -d
Обычные up, restart и down сохраняют volumes. docker compose down -v удалит данные,
включая доверенный CA. Сделайте резервную копию перед обновлением. Удаление state при
сохранённых настройках в NPM означает потерю ключа и связей с ранее созданными объектами.
Экспорт YAML и публичного CA:
docker compose cp ui:/config/services.yaml ./services.backup.yaml
docker compose cp homegate:/data/root-ca.crt ./root-ca.crt
Для полной резервной копии остановите три долгоживущих сервиса, чтобы YAML и реестр не менялись во время копирования. Архив state содержит приватные ключи:
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 без копирования закрытых ключей:
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, Gitea Actions, Compose secrets из environment, Compose configs с content, ограничение read_only в реализации Compose.