admin/.tasks/books-vds-stacks-to-portainer.md

# books-vds-stacks-to-portainer

Migrate SSH-compose стеки на books VDS (`89.253.255.133`) в Portainer-managed через API. Pattern parallel `[[.wiki/concepts/portainer-stack-management-vds]]` (VDS-infra retro-migration 2026-05-22), но другой endpoint/Portainer URL/stack dirs.

## Goal

Унифицировать ops surface на books VDS — все docker-compose стеки управляются через `https://portainer.kzntsv.site` (endpoint 1). Конец hybrid pain'у (Portainer для `books-{api,web,scheduler,...}` + SSH-compose для `elasticsearch/mongo/minio/books-db/traefik/proxy-chain`). CI deploy workflow (`.gitea/workflows/deploy.yml` в victor/books) только через Portainer API; SSH-compose vert не подключается; debug требует знать «is it Portainer or SSH compose» — больно.

## Scope

| Stack | Current dir | Adapt notes |
|---|---|---|
| `books-db` (MariaDB 10.6.4) | `/usr/docker/books-db/` | bind `./data` → absolutize. MYSQL_ROOT_PASSWORD env (передать через Portainer API env array). |
| `mongo` (shared) | `/usr/docker/mongo/` | bind `./data/{db,configdb}` → absolutize. MONGO_INITDB_ROOT_* env. |
| `minio` | `/usr/docker/minio/` | bind `./data` → absolutize. MINIO_ROOT_USER/PASSWORD env. |
| `elasticsearch` | `/usr/docker/elasticsearch/` | bind `./data` + `./snapshots` (added 2026-05-25 для backup) → absolutize. path.repo env preserved. |
| `proxy-chain` | `/usr/docker/proxy-chain/` | bind `./config` → absolutize. |

**Skip (management plane):**
- `traefik` — `/usr/docker/traefik/` — recreate ломает access всему остальному.
- `portainer` — `/usr/docker/portainer/` — self-managed; can't recreate себя.

## Acceptance

- 5 стеков (books-db, mongo, minio, elasticsearch, proxy-chain) появляются в `GET /api/stacks` под endpoint 1 (наряду с книгами `books-{api,web,scheduler,ntfy,ops-mcp}` + `chrome`).
- Контейнеры работают, бинды смонтированы, data preserved (named volumes + binds через migration).
- Smoke: каждый стек проходит health check соответствующий своему типу:
  - books-db: `docker exec books-db mariadb -uroot -p... -e 'SELECT 1'` → `1`
  - mongo: `docker exec mongo mongosh --eval 'db.adminCommand({ping:1})'` → `ok:1`
  - minio: HTTP `https://elasticsearch.kzntsv.site` (или внутренний minio endpoint) — `200 OK`
  - elasticsearch: `docker exec elasticsearch curl localhost:9200/_cluster/health` → `green|yellow`
  - proxy-chain: smoke через тестового агента (TBD)
- Backup pipeline (`books-vds-backup-daily-kreknin`) продолжает работать post-migration (compose dirs не используются runtime после migration, but `/usr/docker/<svc>/data` binds preserved — rsync paths остаются валидны).
- Document в `.wiki/concepts/portainer-stack-management-books-vds.md` (или extend existing `portainer-stack-management-vds.md` с books VDS sections).

## Decisions log

- 2026-05-25: создана по запросу user'а после успешного `books-vds-backup-daily-kreknin`. Promised after backup pipeline live.
- 2026-05-25: pattern reuse — `.wiki/concepts/portainer-stack-management-vds.md` migration script adaptable. Diff for books VDS: PORTAINER_URL, endpoint ID = 1, stack dirs `/usr/docker/<svc>/` instead of `/opt/stacks/<svc>/`. PAT в pass под `books-vds/full-env BOOKS_PORTAINER_API_KEY` (may need fallback to JWT if 401).

## Open questions

- [ ] **Endpoint 6** в books Portainer — stostayer VDS? Что мы за него отвечаем? Если **да** — после books-vds migration extend этой таски на stostayer. Если **нет** — отдельный вопрос, не блокер.
- [ ] **Volume preservation strategy** — `docker compose down` без `-v` preserves named volumes + binds. Verify для каждого стека что нет surprise named volumes которые могут эфемериться.
- [ ] **CI implications** — деплой books-* stacks уже Portainer-managed. After migration of mongo/minio/etc — никаких изменений в CI не нужно (deploy.yml только books-api/web/scheduler, не infra). Confirm.
- [ ] **ES snapshot path.repo edit preservation** — текущий `/usr/docker/elasticsearch/docker-compose.yml` имеет path.repo + snapshots bind (added 2026-05-25). Migration must preserve. Backup в `docker-compose.yml.bak-pre-snapshots-2026-05-25` есть для reference.

## Completed steps

- (not started)

## Plan (sketch)

**Phase 0 — pre-flight:**
1. Read each stack's `docker-compose.yml` + `.env` (if exists).
2. Document existing env vars + binds per stack.
3. Backup current compose files (`docker-compose.yml.bak-pre-portainer-migration-2026-MM-DD`).

**Phase 1 — Portainer API setup:**
1. Verify PAT works (`curl ... /api/stacks`). If 401 → fallback to JWT via admin password (from `pass show books-vds/full-env BOOKS_VDS_ROOT_PASS` adapted to Portainer admin — may differ).
2. Build adapter script `scripts/books-vds-portainer-migrate.sh` (clone-and-adapt of VDS-infra version, see [[.wiki/concepts/portainer-stack-management-vds]] § Migration script).

**Phase 2 — per-stack migrate (one at a time, verify between):**
1. proxy-chain (lowest blast radius)
2. minio (read-mostly, books-api retries OK)
3. mongo (shared) — books-api + books-task-runner retry-tolerant? **VERIFY first**
4. books-db (MariaDB) — books-api uses connection-pool, brief downtime survivable
5. elasticsearch — currently unused (per user), zero impact

**Phase 3 — wiki + close:**
1. Document в `.wiki/concepts/portainer-stack-management-books-vds.md` (or extend existing).
2. Update `.wiki/entities/books-vds.md` — flip каждый стек в SSH-managed → Portainer-managed table.
3. Update STATUS.md → 🟢.

## Notes

- **`books-job-scheduler-mongo`** уже Portainer-managed (часть `books-job-scheduler` stack). Не в scope этой таски.
- **`books-docker-proxy` + `books-docker-proxy-ro`** — часть `books-ops-mcp` stack (Portainer). Not in scope.
- **Buildx builders** (`buildx_buildkit_builder-*`) — transient containers без compose, игнорируем.
- **Backup pipeline depend** — после migration paths `/usr/docker/<svc>/data` остаются как bind sources, поэтому `books-vds-backup-daily-kreknin/run.sh` не требует изменений. Compose files (`/usr/docker/<svc>/docker-compose.yml`) станут reference only после migration.

## Cross-refs

- [[.wiki/concepts/portainer-stack-management-vds]] — VDS-infra retro-migration pattern (source of script).
- [[.wiki/entities/books-vds]] — host factsheet (will update post-migration).
- [[books-vds-backup-daily-kreknin]] — backup taskdone 2026-05-25; depend on stable bind paths.
- victor/books `deploy/README.md` — books-* CI deploy через Portainer API (already migrated).

<!-- created-by: claude / 2026-05-25 / trigger: user-requested follow-up after books-vds-backup-daily-kreknin 🟢 -->