From f9ffe29c30111426c2fbe5a696c09731996f3e4d Mon Sep 17 00:00:00 2001
From: vitya <vitya.kuznetsov@gmail.com>
Date: Tue, 25 Aug 2026 00:42:56 +0300
Subject: [PATCH] =?UTF-8?q?docs(runbook):=20gotcha=204b=20=E2=80=94=20PUT?=
 =?UTF-8?q?=20stack=20=D1=81=D0=B1=D1=80=D0=B0=D1=81=D1=8B=D0=B2=D0=B0?=
 =?UTF-8?q?=D0=B5=D1=82=20env-=D0=BC=D0=B0=D1=81=D1=81=D0=B8=D0=B2=20(v0.1?=
 =?UTF-8?q?3.1)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .wiki/concepts/mappa-vds-deploy-runbook.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.wiki/concepts/mappa-vds-deploy-runbook.md b/.wiki/concepts/mappa-vds-deploy-runbook.md
index 092f472..519bf76 100644
--- a/.wiki/concepts/mappa-vds-deploy-runbook.md
+++ b/.wiki/concepts/mappa-vds-deploy-runbook.md
@@ -93,6 +93,7 @@ ssh vds.kzntsv.site 'docker ps --filter name=mappa --format "{{.Status}}"'
 3. **Не ad-hoc compose** — все стеки VDS через Portainer (VDS ops rule). `docker rm -f`
    вручную снёс контейнер — Portainer recreate поднял, но это не путь.
 4. **mem_limit 512m** — канон app-стеков, не убирать (cgroup-лимит vs вся память хоста).
+4b. **PUT stack сбрасывает env!** — при обновлении compose через `PUT /api/stacks/:id` Portainer обнуляет env-массив стека (Env: null), если не передать `env` в payload. Симптом: контейнер в restart-loop с `SASL: client password must be a string` (подстановка `${MAPPA_DB_PASS}` падает). Фикс: повторный PUT с `{stackFileContent, env:[{name,value}×3]}` (значения из `pass mappa/full-env`). Поймано на деплое v0.13.1 (2026-08-24).
 5. **Внешний DATABASE_URL** — контейнерный `@postgres:5432` валиден только внутри docker-сети;
    для импорта с воркстейшена — `postgres.vds.kzntsv.site:5432` (+ TLS-verify-skip, self-signed).
 6. **Закрытие деплоя** — всегда пара «таска + письмо mappa» (канон `mappa-deploy-workflow`).