From dc6c1db4397b8c50c1523c016e1a0b1bc4d15f7b Mon Sep 17 00:00:00 2001
From: Claude Agent <claude-agent@romfast.ro>
Date: Thu, 9 Jul 2026 11:17:14 +0000
Subject: [PATCH] =?UTF-8?q?docs(deploy):=20reguli=20Dokploy=20=E2=80=94=20?=
 =?UTF-8?q?env=20vars=20obligatorii=20inainte=20de=20push,=20chown=20volum?=
 =?UTF-8?q?=20la=20schimbare=20uid?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Recapitulare incident 2026-07-09: deploy Error la 0s = interpolare env
(variabile ${VAR:?} nesetate in Dokploy), apoi 404 din volum SQLite
detinut de root fata de userul app uid 10001.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 CLAUDE.md              |  1 +
 docs/deploy-dokploy.md | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+)
 create mode 100644 docs/deploy-dokploy.md

diff --git a/CLAUDE.md b/CLAUDE.md
index bf64c34..5628f68 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -40,6 +40,7 @@ AUTOPASS_LIVE_RAR=1 python3 -m pytest tests/test_live_rar.py -q  # LIVE opt-in:
 python3 -m tools.apikey create --account 2 | list | rotate | revoke
 
 docker compose up --build   # deploy: api + worker + autoheal, acelasi image + volum SQLite
+                            # prod = Dokploy cu autodeploy la push; reguli in docs/deploy-dokploy.md
 ```
 
 ## Arhitectura
diff --git a/docs/deploy-dokploy.md b/docs/deploy-dokploy.md
new file mode 100644
index 0000000..ceecba9
--- /dev/null
+++ b/docs/deploy-dokploy.md
@@ -0,0 +1,36 @@
+# Deploy pe Dokploy (autopass.romfast.ro)
+
+Serviciul ruleaza in Dokploy (LXC 103, dokploy.romfast.ro), proiect AUTOPASS/production,
+compose `autopass-roaautopass-jqqw1l`. Provider: Gitea → repo `rar-autopass` → branch `main`
+→ `./docker-compose.yml`, autodeploy la push. Detalii de infrastructura in
+`proxmox/lxc103-dokploy/docs/autopass.md` (repo-ul de infrastructura, nu acesta).
+
+## Reguli la modificarea docker-compose.yml / Dockerfile
+
+1. **Variabila noua obligatorie (`${VAR:?...}`)** → seteaz-o in Dokploy → service autopass →
+   Environment INAINTE de push. Altfel `docker compose` pica la interpolare, inainte de build,
+   cu `required variable VAR is missing a value`. Compose se opreste la PRIMA variabila lipsa,
+   deci mai multe variabile lipsa ies la iveala una pe runda de deploy.
+   Semnatura in Dokploy: deployment "Error" cu durata **0s** = interpolare env, nu build.
+
+2. **Schimbarea uid-ului userului non-root din Dockerfile** → volumul de date pastreaza
+   ownership-ul vechi si SQLite devine readonly (`attempt to write a readonly database`),
+   api + worker intra in crash-loop, Traefik ramane fara backend sanatos → site 404.
+   Inainte de deploy, pe hostul Dokploy:
+
+   ```bash
+   docker volume inspect autopass-roaautopass-jqqw1l_autopass-data --format '{{.Mountpoint}}'
+   docker run --rm <image-api> id app        # afla uid/gid curent (acum 10001:10001)
+   chown -R 10001:10001 /var/lib/docker/volumes/autopass-roaautopass-jqqw1l_autopass-data/_data
+   cd /etc/dokploy/compose/autopass-roaautopass-jqqw1l/code
+   docker compose -p autopass-roaautopass-jqqw1l -f ./docker-compose.yml restart api worker
+   ```
+
+## Incident 2026-07-09 (referinta)
+
+Deploy-urile picau la 0s dupa commit-ul care a facut obligatorii `AUTOPASS_RAR_ENV`,
+`AUTOPASS_SESSION_SECRET` si `AUTOPASS_WORKER_SEND_ENABLED` (cauza 1, doua runde de fix).
+Dupa setarea variabilelor (`AUTOPASS_RAR_ENV=prod`, `AUTOPASS_SESSION_SECRET=<hex32>`,
+`AUTOPASS_WORKER_SEND_ENABLED=true`), site-ul a dat 404 din cauza volumului detinut de root
+in fata userului `app` uid 10001 (cauza 2); rezolvat cu chown-ul de mai sus, fara pierdere
+de date.