diff --git a/architecture/deployment.md b/architecture/deployment.md index 5097112..bc6955b 100644 --- a/architecture/deployment.md +++ b/architecture/deployment.md @@ -12,12 +12,18 @@ 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` пользователя `wealthledger-ci`. Эта же учётная запись + используется сервером для загрузки образов. Для публикации нужны + browse/read/add/edit на `docker-hosted`; фактически выданный набор прав + настраивается в Nexus. Built-in workflow token не заменяет эту настройку. - На сервере Caddy уже завершает TLS и передаёт весь домен на `127.0.0.1:8080` (или выбранный frontend port). Отдельного `/api` upstream нет. @@ -63,7 +69,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 +79,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 и настройте +пользователя `wealthledger-ci`. В 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 пользователем `wealthledger-ci` на сервере приложения, +проверьте 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: @@ -103,10 +145,10 @@ backup directory и Docker. Заполните env локальным защищ если переименовываете, согласуйте также WAL/SHM companion names до старта. Не запускайте старый и новый backend на одной базе одновременно. -Войдите в registry server identity без помещения token в командную строку: +Войдите в registry пользователем `wealthledger-ci` без помещения пароля в командную строку: ```bash -docker login git.personal.ksv741.ru --username SERVER_PULL_USER +docker login nexus.ksv741.keenetic.pro --username wealthledger-ci export COMPOSE_FILE=compose.yaml export COMPOSE_PROJECT_NAME=wealthledger export COMPOSE_ENV_FILES=/srv/wealthledger/production.env