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.