import-stage: .wiki/concepts/ via split (temp prefix for merge into existing dir)

git-subtree-dir: .tmp-concepts
git-subtree-mainline: 98bcc37d32
git-subtree-split: c727aaa1b6

.tmp-concepts/portainer-2.21-admin-password-regression.md

@@ -0,0 +1,85 @@
+---
+title: Portainer 2.21 `--admin-password` regression + min 12-char policy
+type: concept
+tags: [portainer, password, bcrypt, regression, gotcha]
+sources: [../sources/vds-kzntsv-bootstrap-2026-05-20.md]
+updated: 2026-05-20
+---
+
+# Portainer 2.20+ admin-password regression
+
+## Симптом 1 — API init policy
+
+Portainer 2.20.0+ форсит **минимум 12 chars** на admin password при создании через API endpoint `POST /api/users/admin/init`. Короче — `{"message":"Password does not meet the requirements"}`.
+
+## Симптом 2 — CLI flag `--admin-password` broken
+
+CLI flag `--admin-password "<bcrypt-hash>"` (документированный путь init без API) в 2.21.5 ведёт себя странно:
+- Лог сервера показывает «created admin user with the given password.» — то есть admin **записывается**.
+- Login с паролем → `Invalid credentials`. Bcrypt verify fails.
+
+Пробовали и `$2y$` (htpasswd default), и `$2a$` (Go bcrypt), и YAML list form чтобы избежать compose env-interp escape (`$` → `$$`), и docker run direct без compose. Bcrypt hash в `docker inspect` Cmd корректный. Но login всё равно fails.
+
+Не покопали глубоко (возможно — flag тупо игнорируется и admin создаётся с auto-generated password, либо хеш re-hashится сервером).
+
+## Решение
+
+Bypass CLI flag. Использовать API init с **длинным паролем (12+ chars)**:
+
+```bash
+# Run portainer без --admin-password (fresh data dir)
+docker run -d --name portainer --network proxy \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -v $PWD/data:/data \
+  portainer/portainer-ce:2.21.5
+
+# API admin/init available 5 minutes after start
+curl -sk -X POST https://portainer.vds.kzntsv.site/api/users/admin/init \
+  -H 'Content-Type: application/json' \
+  -d '{"Username":"vitya","Password":"Pryakhin9-VDS-2026"}'
+
+# Login → JWT
+JWT=$(curl -sk -X POST https://portainer.vds.kzntsv.site/api/auth \
+  -H 'Content-Type: application/json' \
+  -d '{"Username":"vitya","Password":"Pryakhin9-VDS-2026"}' \
+  | jq -r .jwt)
+
+# Generate API key
+APIKEY=$(curl -sk -X POST https://portainer.vds.kzntsv.site/api/users/1/tokens \
+  -H "Authorization: Bearer $JWT" \
+  -H 'Content-Type: application/json' \
+  -d '{"description":"automation","password":"Pryakhin9-VDS-2026"}' \
+  | jq -r .rawAPIKey)
+```
+
+После init — local docker endpoint надо создать отдельным POST'ом:
+```bash
+curl -sk -X POST https://portainer.vds.kzntsv.site/api/endpoints \
+  -H "X-API-Key: $APIKEY" \
+  -F "Name=local" \
+  -F "EndpointCreationType=1"  # LocalDockerEnvironment
+```
+
+## Trade-off
+
+- ✗ Имя пользователя пароль user'а — приходится менять на «12+ chars» (`Pryakhin9-VDS-2026` вместо `Pryakhin9`).
+- ✔ Single source of truth — admin live в DB только через API, всегда последовательное состояние.
+- ✔ API token доступен сразу для дальнейшей автоматизации stacks через REST.
+
+## Compose эскейп bcrypt — separate gotcha
+
+При попытках использовать `--admin-password` в compose столкнулись с classic `$` escape trap:
+- В YAML string form `command: "... --admin-password '$$2y$$05$$abc'"` — compose unwraps `$$` → `$`, передаёт правильный hash.
+- В YAML list form `command: ["...", "--admin-password", "$$2y$$05$$abc"]` — compose unwraps аналогично, hash виден в `docker inspect` корректный.
+- Кавычки `'...'` вокруг hash в string form **становятся literal частью value** (shell tokenize'ит, не shell-context'ит), bcrypt получает паразитные `'` → broken hash.
+
+Решение для подобных escape-проблем — `docker run` direct (нет compose env-interp) или `--admin-password-file` (passes plain text from file, no escape) — но last не bypass'ит policy, ждёт plain text 12+ chars.
+
+## Где применено
+
+Portainer на [`vds-kzntsv`](../entities/vds-kzntsv.md), запущен через `docker run` (не compose) чтобы зафиксировать конкретный набор labels. Кред live в `~/projects/.common/secrets/vds-kzntsv.env`.
+
+## Ссылки
+
+- Portainer changelog 2.20.0 — введён password policy + auth refactor (https://github.com/portainer/portainer/releases/tag/2.20.0).
+- Сессия где упоролись: [`vds-kzntsv-bootstrap-2026-05-20`](../sources/vds-kzntsv-bootstrap-2026-05-20.md) Phase 1 cont.