---
paths:
  - docker-compose*.yml
  - Caddyfile
  - .github/workflows/**
  - scripts/setup-*.sh
---

# Deploy conventions

## GHA path triggers

- `backend/**`, `frontend/**`, `Caddyfile`, `docker-compose.prod.yml`, `data/sql/*.sql` → `deploy.yml` (main stack)
- `docker-compose.obsidian.yml`, `scripts/setup-couchdb.sh` → `deploy-obsidian.yml`
- `docs/**` alone → НЕ триггерит деплой

## После изменения .env на VPS

```bash
docker compose up -d --force-recreate --no-deps <service>
```

`docker compose restart` НЕ перечитывает `env_file`.

## Caddyfile

Bind-mounted → нужен явный `caddy reload` после изменения. `deploy.yml` делает автоматически после `compose up -d`.

## Sentry release tracking

`SENTRY_RELEASE=$IMAGE_TAG` пишется в `backend/.env.runtime` на VPS через `sed` — **не** полная перезапись файла (там user-managed `COUCHDB_PASSWORD` и пр.).

## VPS git state

`deploy.yml` делает `git reset --hard origin/main` → любые ручные правки в `/opt/gendesign` стираются. `.env`-файлы выживают (в `.gitignore`).

## DB migrations через deploy

`data/sql/NN_*.sql` применяются **до** `compose up -d`. Если SQL падает → deploy останавливается (exit 1), containers не обновляются.

Diagnose: GHA log "Apply DB migrations". См. `.claude/rules/sql.md` для migration order.

## Запреты

- ❌ Менять `env_file` секреты в `docker-compose*.yml` — секреты через VPS `.env` файлы
- ❌ Полностью перезаписывать `.env.runtime` — только `sed` для конкретных переменных
- ❌ `git pull` на VPS вручную — deploy.yml уже делает `git reset --hard`
- ❌ Hardcode tags / SHA в compose files — `${IMAGE_TAG}` через env
