@@ -1,19 +1,21 @@
# Контейнерная поставка
Runbook для одного Docker host, одного backend и краткого простоя.
Поставка для одного Docker host, одного backend и краткого простоя.
[Топология ](containers.md#контейнерная-поставка ) и
[ADR 015 ](../adr/015-single-server-sqlite-deployment.md ) объясняют границы.
Команды выполняются из checkout `WealthLedger/main` , содержащего `compose.yaml`
Development дополнительно требует checkout `frontend/` и `backend/` .
Production-комплект находится в отдельном [ репозитории deploy ]( https://git.personal.ksv741.ru/WealthLedger/deploy ) .
Его README — единственная пошаговая инструкция установки, обновления и recovery;
[ADR 016 ](../adr/016-versioned-deployment-bundle.md ) объясняет выбор релиза комплекта.
Development-команды ниже выполняются из workspace с `frontend/` и `backend/` .
## Предпосылки
- Docker Engine с **не ниже 2.24.4 ** (`!override` в development),
доступ к registry и достаточно свободного диска для non-root UID 1000.
Локально проверены Engine 29.8.0, Compose 5.5.1, Linux ar m64.
Production images `0.2.3` опубликованы для Linux amd 64.
Другую архитектуру проверяют отдельно; multi-platform images не обещаны.
- Nexus Docker hosted repository `docker-hosted` , доступный через
`https://nexus.ksv741.keenetic.pro/v2 /` . Docker Bearer Token Realm включён;
`nexus.personal.ksv741.ru/docker-hosted /` . Docker Bearer Token Realm включён;
reverse proxy передаёт исходные host и HTTPS scheme. Адрес token realm
в `WWW-Authenticate` также должен начинаться с `https://` .
Deployment policy запрещает redeploy существующих release tags.
@@ -29,8 +31,8 @@ Development дополнительно требует checkout `frontend/` и `b
`127.0.0.1:8080` (или выбранный frontend port). Отдельного `/api` upstream нет.
DNS, TLS, firewall и provisioning Caddy выполняются вне этого runbook.
Реальная публикация и server pull-only login требуют отдельной про верки
на вашей инфраструктуре. Локальные images не доказывают registry permissions.
Серверный login и доступ к images проверяются на целевом сер вере
Локальный smoke не доказывает серверные registry permissions.
## Development
@@ -69,7 +71,7 @@ Project `wealthledger-dev` хранит SQLite в `development-data`. Обычн
version, затем выполняет `npm ci` , `npm run verify` ; backend дополнительно
выполняет `npm run test:e2e` . У
Images публикуются как `nexus.ksv741.keenetic.pro /wealthledger/frontend:X.Y.Z`
Images публикуются как `nexus.personal.ksv741.ru/docker-hosted /wealthledger/frontend:X.Y.Z`
и `.../backend:X.Y.Z` . `latest` не создаётся.
Workflow отказывается перезаписывать существующие release tags;
защита release tags и запрет параллельных publishers обязательны. Если одна
@@ -78,8 +80,8 @@ Workflow отказывается перезаписывать существу
Выберите опубликованные version tags, выполните pull и сравните OCI revision
с с
rollout. В production env хранится пара полных image references, например
`nexus.ksv741.keenetic.pro /wealthledger/frontend:0.2.0 ` . Сохраните versions/revisions
rollout. В `release.env` комплекта хранится пара полных image references, например
`nexus.personal.ksv741.ru/docker-hosted /wealthledger/frontend:0.2.3 ` . Сохраните versions/revisions
в deployment record. Release tags не должны переназначаться другим images.
## Перенос существующих images из Gitea
@@ -94,11 +96,11 @@ rollout. В
``` bash
skopeo login git.personal.ksv741.ru
skopeo login nexus.ksv741.keenetic.pro
skopeo login nexus.personal.ksv741.ru
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
" docker://nexus.personal.ksv741.ru/docker-hosted /wealthledger/ $component :0.2.0 " || exit 1
done
```
@@ -120,150 +122,60 @@ SQLite и не меняет encryption keys. Не переносите Git relea
## Первая установка
Создайте restricted environment file и data directory:
На подготовленном сервере оператор клонирует `deploy` , настраивает внешний
HTTPS и registry login, размещает server env, сертификат T-Bank и data directory
вне checkout. Для новой пустой базы команда вызывается с `--init` .
Для действующей установки сохраняются прежние данные и ключи, а первый переход
выполняется как полное обновление с backup. Отсутствующая БД без `--init` — ошибка.
Точные команды и разрешения каталогов приведены в README комплекта.
``` bash
sudo install -d -m 0700 /srv/wealthledger
sudo install -d -m 0700 -o 1000 -g 1000 /srv/wealthledger/data
sudo install -m 0600 .env.compose.example /srv/wealthledger/production.env
```
Дальнейшие команды выполняет оператор, имеющий доступ к environment file,
backup directory и Docker. Заполните env локальным защищённым редактором:
полные ссылки `FRONTEND_IMAGE` и `BACKEND_IMAGE` с опубликованными version tags,
публичный HTTPS origin и абсолютный data path. Версии в примере — образец
формата; перед запуском выберите реально опубликованные releases.
Пустые required значения блокируют config; некорректные secrets блокируют backend.
Не выводите полный rendered config с
Для новой базы создайте JWT secret длиной хотя бы 32 символа и отдельный
32-byte encryption key в base64 (`openssl rand -hex 32` и
`openssl rand -base64 32` в защищённом терминале). Сохраните ключ отдельно
от data backup. Для существующей установки перенесите прежние JWT secret
и encryption key, а согласованную копию **всего ** data directory — при
остановленном прежнем backend. Файл должен называться `wealthledger.db` ;
если переименовываете, согласуйте также WAL/SHM companion names до старта.
Не запускайте старый и новый backend на одной базе одновременно.
Войдите в registry пользователем `wealthledger-ci` без помещения пароля в командную строку:
``` bash
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
docker compose config --quiet
docker compose pull frontend backend migration
docker compose up -d --wait --wait-timeout 120
docker compose ps -a
```
Migration и backend используют один image и один data mount.
Migration должна завершиться с кодом 0; иначе backend не запускается.
Readiness принимает 401 от существующего `/api/v1/auth/me` без credentials.
Frontend становится healthy после backend. Backend host port отсутствует.
Runtime non-root; root filesystem read-only, nginx temp files находятся в tmpfs.
Проверьте SPA deep link, регистрацию/вход, refresh, существующие карты,
чтение старого зашифрованного подключения и один финансовый запрос.
Production refresh-cookie имеет Secure flag: проверяйте через HTTPS Caddy;
loopback HTTP curl без browser cookie jar не доказывает browser session.
При локальном smoke используйте disposable credentials и явную передачу cookie.
Направляйте Caddy на новый deployment только после успешной проверки.
Прежний runtime удаляйте только после проверки новой установки.
Git-тег `deploy` закрепляет пару images через `release.env` . Версия комплекта
не обязана совпадать с версиями компонентов. Публикация image не выпускает
комплект и не обновляет сервер автоматически. Команда получает выбранный тег,
загружает images до простоя и использует весь snapshot этого commit.
## Backup при остановленном backend
До backend update проверьте совместимость новой версии с текущим frontend
и схемой, а обратной версии — с новой схемой. При неизвестной совместимости
не обещайте image rollback. В
Ниже data path соответствует примеру env; при другом path замените его .
Сохраните текущую пару image references/revisions и отдельно — ключи.
``` bash
docker compose stop backend
docker compose ps -a backend
install -d -m 0700 /srv/wealthledger/backups
BACKUP_DIRECTORY = " /srv/wealthledger/backups/ $( date -u +%Y%m%dT%H%M%SZ) "
mkdir -m 0700 " $BACKUP_DIRECTORY "
cp -a /srv/wealthledger/data " $BACKUP_DIRECTORY /data "
```
Перед копированием убедитесь, что backend остановлен, migration не выполняется
и никто другой не пишет в каталог. Успех `cp` обязателен перед продолжением.
Не копируйте отдельный `.db` из работающего приложения. Проверяйте backup
на отдельной копии: migration status, `PRAGMA integrity_check` , auth, карты
и расшифровка тестового подключения исходным ключом. Backup без проверяемого
ключа недостаточен для восстановления подключения.
Сначала останавливаются писатели, затем копируется весь каталог данных,
включая возможные WAL/SHM. Только успешная копия допускает миграции. Локальные
backups находятся рядом с data directory, вне checkout, и автоматически
не удаляются. Незавершённая копия помечается `.partial-` и не подходит для restore.
Ключ шифрования хранится отдельно. Локальная копия не защищает от потери диска .
## Независимое обновление frontend
После проверки API compatibility замените только `FRONTEND_IMAGE` в env:
``` bash
docker compose pull frontend
docker compose up -d --no-deps --wait --wait-timeout 120 frontend
```
Backend container и SQLite не пересоздаются. Входная точка кратко недоступна.
Проверьте deep link, login/refresh и новую OCI revision. Старым browser tabs
может понадобиться reload: старые hashed chunks не сохраняются между images.
Если изменились только image или конфигурация frontend, backend не
пересоздаётся, backup и migration не выполняются. Возможен короткий перерыв
на внешней точке входа; старым browser tabs может потребоваться reload.
При неизменных исправных контейнерах повтор команды не пересоздаёт сервисы.
## Независимое обновление backend
Выпол нит е stopped-backend backup выше. Замените только `BACKEND_IMAGE` в env.
Последовательность не продолжаетс я после failed migration:
Измене ние image или конфигурации backend запускает stop → backup → migration →
readiness. Неизменный frontend не пересоздаётся. Во врем я пр тоя возможен 502.
Ошибка migration блокирует старт, ошибка готовности останавливает новый backend;
ошибка frontend не останавливает исправный backend. Успех фиксируется только
после проверок запуска затронутых компонентов.
``` bash
docker compose pull backend migration
docker compose up --no-deps --force-recreate --abort-on-container-exit \
--exit-code-from migration migration &&
docker compose up -d --no-deps --wait --wait-timeout 120 backend
```
Frontend не пересоздаётся; nginx повторно разрешает backend DNS. Во время
перерыва возможен 502. При failure оставьте backend остановленным, сохраните
диагностику migration и выберите совместимый image либо отдельный restore.
Не используйте `migrate reset` или автоматический `resolve` как recovery.
Проверьте migration status, health, login/refresh, карты и расшифровку подключения.
После успешного smoke запишите фактически установленную пару image references.
Одна file lock защищает установку от параллельных команд. Маркер незавершённого
обновления блокирует повтор до разбора оператором. Он содержит этап, версии
и путь к backup, но не секреты и не копию данных. После обновления нужен smoke
через HTTPS: healthcheck сам по себе не доказывает работу Secure refresh-cookie.
## Откат image
Для frontend верните предыдущий совместимый version tag и повторите frontend update.
Для backend сначала остановите процесс и подтвердите совместимость с тар ого
image с **текущей ** схемой. Верните предыдущий image reference и запустите только backend:
``` bash
docker compose pull backend
docker compose up -d --no-deps --wait --wait-timeout 120 backend
```
Данные и encryption key не заменяются. Migration service здесь намеренно
не запускается: старые migrations не являются down-migrations. Прочитайте
новые записи, сделанные после backup, и проверьте auth/cards/connection.
При несовместимости оставьте приложение остановленным до решения о recovery.
Откат версии и восстановление базы — разные операции. Прежний backend можно
запускать только после проверки совместимости с текущей схемой. Автоматическ ого
rollback нет; migration service при ручном image rollback не запускается.
Порядок ручных Compose-команд и проверки recovery находится в README комплекта.
## Explicit restore
Это отдельное решение оператора, **не часть image rollback ** . Оператор выбирает
backup timestamp и явно принимает потерю всех изменений после него, в ключая
сессии, карты и подключения. Сначала воспроизведите restore на isolated project
с отдельным data path/port и совместимым image; не используйте production data
как fixture. Убедитесь в наличии соответствующего encryption key.
После отдельного решения оста вите backend и убедитесь, что migration н е
работает. Сохраните нынешний каталог под новым именем, ничего не удаляя:
``` bash
docker compose stop backend
mv /srv/wealthledger/data /srv/wealthledger/data-before-restore-TIMESTAMP
cp -a /srv/wealthledger/backups/CHOSEN_TIMESTAMP/data /srv/wealthledger/data
```
Проверьте owner 1000:1000, permissions, выбранный compatible image и исходный
ключ. Запустите backend командой rollback с `--no-deps` , затем выполните smoke.
Сверьте наличие записей до backup и отсутствие известных записей потерянного
интервала. Сохраните прежний каталог для расследования. При необходимости
новой migration сначала выполните обычную backup/update последовательность.
Оператор выбирает проверенную копию и явно принимает потерю всех более новых
записей. Сначала восстановление проверяется на isolated данных с прежним ключом
и совместимым image. На целевой установке останавливаются писатели, текущий
каталог сохраняется под новым именем, затем восстанавливается выбранная копия.
Backend пересоздаётся, чтобы заново подключить заменённый bind-каталог:
простой stop/start может сохранить mount прежних данных.
Проверяются цел остность БД, auth/cards и расшифровка подключения. Только посл е
подтверждённого recovery можно снять маркер незавершённой операции.