# Один 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.5.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.5.0`. После загрузки проверенного кода в Gitea: ```sh git tag v0.5.0 git push origin v0.5.0 ``` При следующем выпуске измените `VERSION`, закоммитьте его вместе с изменениями и создайте соответствующий тег. Тег должен совпасть с файлом `VERSION`: например `v0.5.0` и `0.5.0`. Предварительные версии вида `v0.5.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.5.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.5.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.5.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).