From 5de85c296f7681882f58476343d3da71f1dee28d Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Thu, 17 Sep 2026 20:41:24 +0300 Subject: [PATCH] docs: document Nexus registry migration #18 --- architecture/deployment.md | 55 +++++++++++++++++++++++++++++++++----- 1 file changed, 48 insertions(+), 7 deletions(-) diff --git a/architecture/deployment.md b/architecture/deployment.md index 5097112..f2ed8fe 100644 --- a/architecture/deployment.md +++ b/architecture/deployment.md @@ -12,12 +12,17 @@ Development дополнительно требует checkout `frontend/` и `b доступ к registry и достаточно свободного диска для non-root UID 1000. Локально проверены Engine 29.8.0, Compose 5.5.1, Linux arm64. Другую архитектуру проверяют отдельно; multi-platform images не обещаны. -- Gitea Container Registry; проверяемая версия сервера — 1.27.3. +- Nexus Docker hosted repository `docker-hosted`, доступный через + `https://nexus.ksv741.keenetic.pro/v2/`. Docker Bearer Token Realm включён; + reverse proxy передаёт исходные host и HTTPS scheme. Адрес token realm + в `WWW-Authenticate` также должен начинаться с `https://`. + Deployment policy запрещает redeploy существующих release tags. Runner label — `ubuntu-latest`, runner должен иметь Docker CLI, buildx и daemon. Наличие label само по себе не доказывает Docker capability. -- В Actions каждого component repo нужны `REGISTRY_USERNAME` и - `REGISTRY_TOKEN` отдельной identity с package write permission. Server - использует другую identity только с package read permission. Built-in +- В Actions каждого component repo нужны `NEXUS_USERNAME` и + `NEXUS_PASSWORD` отдельной Nexus identity с правами browse/read/add/edit + только на `docker-hosted`, без delete и административных прав. Server + использует другую identity только с browse/read на этот repository. Built-in workflow token не заменяет эту настройку. - На сервере Caddy уже завершает TLS и передаёт весь домен на `127.0.0.1:8080` (или выбранный frontend port). Отдельного `/api` upstream нет. @@ -63,7 +68,7 @@ Project `wealthledger-dev` хранит SQLite в `development-data`. Обычн version, затем выполняет `npm ci`, `npm run verify`; backend дополнительно выполняет `npm run test:e2e`. У каждого image OCI version/revision labels. -Images публикуются как `git.personal.ksv741.ru/wealthledger/frontend:X.Y.Z` +Images публикуются как `nexus.ksv741.keenetic.pro/wealthledger/frontend:X.Y.Z` и `.../backend:X.Y.Z`. `latest` не создаётся. Workflow отказывается перезаписывать существующие release tags; защита release tags и запрет параллельных publishers обязательны. Если одна @@ -73,9 +78,45 @@ Workflow отказывается перезаписывать существу Выберите опубликованные version tags, выполните pull и сравните OCI revision с release commit. Выполните smoke с disposable data/config до первого server rollout. В production env хранится пара полных image references, например -`git.personal.ksv741.ru/wealthledger/frontend:0.1.0`. Сохраните versions/revisions +`nexus.ksv741.keenetic.pro/wealthledger/frontend:0.2.0`. Сохраните versions/revisions в deployment record. Release tags не должны переназначаться другим images. +## Перенос существующих images из Gitea + +До переключения CI и server references проверьте HTTPS token realm и настройте +Nexus identities. В Actions добавьте `NEXUS_USERNAME`/`NEXUS_PASSWORD`; прежние +`REGISTRY_USERNAME`/`REGISTRY_TOKEN` сохраните для отката старого workflow. +Пароли вводятся интерактивно или через `--password-stdin`, не через аргументы. + +Скопируйте каждый опубликованный release без пересборки. Например, для `0.2.0` +с установленным Skopeo и доступом чтения Gitea/записи Nexus: + +```bash +skopeo login git.personal.ksv741.ru +skopeo login nexus.ksv741.keenetic.pro +for component in frontend backend; do + skopeo copy --all --preserve-digests \ + "docker://git.personal.ksv741.ru/wealthledger/$component:0.2.0" \ + "docker://nexus.ksv741.keenetic.pro/wealthledger/$component:0.2.0" || exit 1 +done +``` + +`--all` переносит весь image index, включая платформы и вложенные attestation +manifests; `--preserve-digests` прерывает перенос при изменении digest. +До копирования проверьте наличие destination tag: если он уже существует, +сравните исходный и целевой index digest и вложенные manifests. Совпадающий +artifact повторно не публикуйте; несовпадение требует расследования, не удаления +или перезаписи tag. Частичный перенос не считается завершённым. + +После копирования сравните digests через `skopeo inspect --raw` и SHA-256, +выполните `docker pull` обоих images отдельной server read-only identity, +проверьте OCI revision и container smoke на disposable data. +Только после этого меняйте production image references и запускайте обычную +последовательность обновления ниже. Старые Gitea packages и references сохраните: +откат registry возвращает прежние адреса тех же artifacts, не восстанавливает +SQLite и не меняет encryption keys. Не переносите Git release tags и не +запускайте заново старый tag workflow для копирования существующего image. + ## Первая установка Создайте restricted environment file и data directory: @@ -106,7 +147,7 @@ backup directory и Docker. Заполните env локальным защищ Войдите в registry server identity без помещения token в командную строку: ```bash -docker login git.personal.ksv741.ru --username SERVER_PULL_USER +docker login nexus.ksv741.keenetic.pro --username SERVER_PULL_USER export COMPOSE_FILE=compose.yaml export COMPOSE_PROJECT_NAME=wealthledger export COMPOSE_ENV_FILES=/srv/wealthledger/production.env