admin/.wiki/concepts/portainer-stack-management-books-vds.md

title: Portainer stack management on books VDS — pattern application + migration log status: live tags: [books-vds, portainer, docker-compose, ops, migration] related: books-vds, portainer-stack-management-vds, books-vds-backup-daily-kreknin-2026-05-25

Portainer stack management on books VDS

Application of the canonical pattern from portainer-stack-management-vds к books VDS (89.253.255.133, host4g.ru, CentOS 7).

Canonical rule (same as VDS-infra): all docker-compose стеки на books VDS управляются через Portainer https://portainer.kzntsv.site (endpoint 1). SSH-compose в /usr/docker/<svc>/ — anti-pattern post-2026-05-25.

2026-05-25 retro-migrated 6 ранее SSH-compose стеков: proxy-chain, imgproxy (2 контейнера), minio, mongo, books-db, elasticsearch. Skipped traefik + portainer (management plane). Adapter script scripts/books-vds-portainer-migration/migrate.sh.

Diffs from VDS-infra pattern

Aspect	vds-kzntsv	books VDS
Portainer URL	portainer.vds.kzntsv.site	portainer.kzntsv.site
Auth	JWT через admin/password (PAT 401'd)	X-API-Key header — PAT works
Stack dir prefix	/opt/stacks/<stack>/	/usr/docker/<stack>/
Endpoint ID	1 (single docker daemon)	1 (books VDS local). Endpoint 6 = stostayer — НЕ наш
Compose down	cd $DIR && docker compose down	docker rm -f by com.docker.compose.project label
env_file: directives	many stacks had them	none — env was inline в compose
.env files	many stacks had them	none — все env inline
Sibling files	nginx.conf, certs, scripts	nginx.conf for imgproxy-nginx only
docker-compose binary	v2 plugin only	v2 plugin (2.27.1) + v1 standalone (1.29.2). Script uses neither — direct docker rm -f

Pre-flight quirks on books VDS

1. No jq installed, no python3, yum is broken (CentOS 7 EOL since 2024-06, mirrors retired). Mitigation: pre-install static jq 1.7.1 binary:

   curl -fsSL https://github.com/jqlang/jq/releases/download/jq-1.7.1/jq-linux-amd64 \
     -o /usr/local/bin/jq && chmod +x /usr/local/bin/jq
   

2. No /root/.docker/config.json — no docker login registry.kzntsv.site configured. Risk: if Portainer create force-pulls :latest for private registry images (proxy-chain, books-*) → pull fail. Mitigation in practice: Portainer create использует local image cache when available; for current :latest cached images миграция прошла без issue. Future-proofing: docker login registry.kzntsv.site before any registry-managed stack force-pull.
3. Mongo image lost tag — running container's image was retagged (digest 0bf62880fec3 only). Portainer create pulls fresh mongo:4.2 — may be different sub-version digest. 4.2 schema stable, accepted as low risk. Mitigation if reproducibility critical: pin to digest.

Stack inventory (2026-05-25 post-migration, Portainer Ids)

Endpoint 1 (books VDS):

Id	Name	Compose dir	Note
22	books-job-scheduler	(Portainer-only, pre-migration)	agenda jobs + embedded mongo
23	books-api	(Portainer-only)	books API server, Nitro, port 3021
24	books-web	(Portainer-only)	books Nuxt front-end
25	books-ntfy	(Portainer-only)	local ntfy (separate from ntfy.vds.kzntsv.site)
26	books-ops-mcp	(Portainer-only)	+ books-docker-proxy + books-docker-proxy-ro + bootstrap
27	chrome	(Portainer-only)	Puppeteer for PDFs/scraping
28	proxy-chain	/usr/docker/proxy-chain	upstream HTTP-proxy chain, internal-only
29	imgproxy	/usr/docker/imgproxy	imgproxy + imgproxy-nginx, serves imgproxy.kzntsv.site
30	minio	/usr/docker/minio	S3 blob store, minio.kzntsv.site
31	mongo	/usr/docker/mongo	shared MongoDB 4.2, used by books-api + books-task-runner
32	books-db	/usr/docker/books-db	MariaDB latest, books application DB
33	elasticsearch	/usr/docker/elasticsearch	ES 7.10.0 + path.repo=/snapshots for backup

Non-Portainer (management plane, скип migration):

• traefik — /usr/docker/traefik/, ad-hoc compose, бинд ./letsencrypt (acme.json) + ./data/traefik.yml
• portainer — /usr/docker/portainer/, ad-hoc compose, named volume portainer_data

Endpoint 6 (stostayer VDS, не наш — user-confirmed 2026-05-25). Stacks listed: Traefik, minio, mariadb, imgproxy, stostayer-{franchise,web,tireservice-api}, registry. Same Portainer UI manages, but physical machine not ours.

Migration ladder

Used 2026-05-25, lowest → highest blast radius. Successful in this order:

1. proxy-chain — internal-only, no traefik exposure → smoke for the script
2. imgproxy — 2-container compose with sibling nginx.conf
3. minio — read-mostly, books-api retries OK
4. mongo — shared, used by books-api + books-task-runner. Reconnect transparent (~13s)
5. books-db — MariaDB, books-api connection-pool reconnect (~15s)
6. elasticsearch — single-node, snapshot repo kreknin preserved through bind

Все 6 stacks Up + smoke green в одну сессию (~10 минут end-to-end).

Gotchas hit during migration

All 8 gotchas from portainer-stack-management-vds applied; books-specific additions:

9. CentOS 7 base OS, yum dead — package install через yum невозможно. Static jq binary download — единственный путь без EPEL mirror работающего. Documented above.
10. No registry login — docker login registry.kzntsv.site не настроен. Кэшированные образы спасают, но fresh-pull для private images → auth fail. Setup docker login если планируется image-rotation от Portainer UI.
11. Compose v1 + Compose v2 plugin co-existence — docker-compose (1.29.2) и docker compose (2.27.1) обе installed. Migration script использует docker rm -f для down → не зависит ни от той ни от другой. Чище.

Smoke commands per stack (post-migration)

# proxy-chain — internal smoke (HTTP 400 = service responding, not a valid proxy GET)
curl -sS -o /dev/null -w "%{http_code}\n" http://localhost:8778/

# imgproxy — traefik HTTP route
curl -ksS -o /dev/null -w "%{http_code}\n" https://imgproxy.kzntsv.site/

# minio
curl -ksS -o /dev/null -w "%{http_code}\n" https://minio.kzntsv.site/minio/health/live

# mongo (auth via root/MONGO_INITDB_ROOT_PASSWORD)
docker exec mongo mongo --quiet --eval 'db.adminCommand({ping:1}).ok' -u root -p '<from pass>'

# books-db
docker exec books-db mariadb -uroot -p'<from pass>' -e 'SELECT 1'

# elasticsearch
docker exec elasticsearch curl -sS localhost:9200/_cluster/health | jq .status
docker exec elasticsearch curl -sS localhost:9200/_snapshot   # verify kreknin repo

What's preserved post-migration

• Bind data paths — /usr/docker/<stack>/data (and ./snapshots, ./config, etc.) stay on host disk. Bind preserved through container recreate.
• Backup pipeline — scripts/books-vds-backup-daily-kreknin/run.sh rsync paths unchanged. ES path.repo=/snapshots bind preserved → snapshot repo kreknin continues to write.
• Traefik labels — propagate automatically. Routes for imgproxy.kzntsv.site / minio.kzntsv.site / elasticsearch.kzntsv.site re-attach as containers come up (docker socket events).
• Network — все 6 stacks join external proxy network as before. No re-configuration.
• Compose file on disk — /usr/docker/<stack>/docker-compose.yml remains as reference. Дата-stamp backup docker-compose.yml.bak-pre-portainer-migration-2026-05-25 создан per stack.

What changed

• working_dir label: было /usr/docker/<stack> (ad-hoc), стало /data/compose/<id>/ (Portainer-managed). Compose files в /usr/docker/<stack>/ теперь reference-only.
• Lifecycle management: edit / restart / view logs — всё через Portainer UI или API. Editing /usr/docker/<stack>/docker-compose.yml напрямую больше не имеет эффекта на runtime (Portainer владеет compose state в /data/compose/<id>/docker-compose.yml).

Cross-refs

• portainer-stack-management-vds — source pattern (vds-kzntsv).
• books-vds — host factsheet (updated 2026-05-25).
• books-vds-backup-daily-kreknin-2026-05-25 — backup pipeline stand-up; depends on bind paths preserved through this migration.
• scripts/books-vds-portainer-migration/{migrate.sh,README.md} — implementation.