docs(dev): add release runbook for sofiia-console

Made-with: Cursor
2026-03-02 10:00:08 -08:00
parent 6a0d2ff103
commit 47073ba761
1 changed files with 109 additions and 0 deletions
--- a/docs/runbook/release-runbook-sofiia-console.md
+++ b/docs/runbook/release-runbook-sofiia-console.md
@@ -0,0 +1,109 @@
+# Release Runbook: Sofiia Console (One-Page)
+
+Короткий сценарій релізу для `sofiia-console` з мінімальним ризиком та швидким rollback.
+
+## 1) Preflight
+
+```bash
+cd /opt/microdao-daarion
+bash ops/preflight_sofiia_console.sh
+```
+
+Для прод-вікна (warnings -> fail):
+
+```bash
+cd /opt/microdao-daarion
+STRICT=1 bash ops/preflight_sofiia_console.sh
+```
+
+## 2) Deploy order
+
+Рекомендований порядок:
+
+1. **NODA2 precheck (control plane)** — health/metrics локально.
+2. **NODA1 rollout (data plane)** — оновлення runtime сервісів.
+3. **NODA2 finalize (control plane)** — фінальний restart/control-plane підтвердження.
+
+Приклад команд:
+
+```bash
+# NODA1 rollout
+ssh root@144.76.224.179 "cd /opt/microdao-daarion && docker compose -f docker-compose.node1.yml up -d router gateway memory-service"
+```
+
+```bash
+# NODA2 finalize
+cd /opt/microdao-daarion
+docker compose -f docker-compose.node2-sofiia.yml up -d sofiia-console router
+```
+
+## 3) Smoke
+
+### 3.1 Health + metrics
+
+```bash
+curl -fsS http://127.0.0.1:8002/api/health
+curl -fsS http://127.0.0.1:8002/metrics | rg "sofiia_"
+```
+
+### 3.2 Redis idempotency (коли backend=redis)
+
+```bash
+cd /opt/microdao-daarion
+bash ops/redis_idempotency_smoke.sh
+```
+
+### 3.3 Audit auth check
+
+```bash
+# без ключа має бути 401
+curl -s -o /dev/null -w "%{http_code}\n" "http://127.0.0.1:8002/api/audit"
+```
+
+```bash
+# з ключем має бути 200
+KEY="<SOFIIA_CONSOLE_API_KEY>"
+curl -s -o /dev/null -w "%{http_code}\n" \
+  -H "X-API-Key: ${KEY}" \
+  "http://127.0.0.1:8002/api/audit"
+```
+
+## 4) Rollback
+
+1. Повернути попередню ревізію/образ.
+2. Перезапустити сервіси у зворотному порядку релізу.
+3. Виконати мінімальний smoke (health/metrics + audit auth).
+
+Приклад:
+
+```bash
+# NODA2 rollback
+cd /opt/microdao-daarion
+git checkout <previous_release_tag_or_sha>
+docker compose -f docker-compose.node2-sofiia.yml up -d sofiia-console router
+```
+
+```bash
+# NODA1 rollback
+ssh root@144.76.224.179 "cd /opt/microdao-daarion && git checkout <previous_release_tag_or_sha> && docker compose -f docker-compose.node1.yml up -d router gateway memory-service"
+```
+
+Після rollback:
+
+```bash
+curl -fsS http://127.0.0.1:8002/api/health
+curl -fsS http://127.0.0.1:8002/metrics | rg "sofiia_"
+```
+
+## 5) Post-release checklist
+
+- Перевірити `sofiia_rate_limited_total` та `sofiia_idempotency_replays_total`.
+- Перевірити, що audit пишеться/читається:
+  - `POST /api/chats/.../send`
+  - `GET /api/audit` з ключем.
+- Запустити retention dry-run:
+
+```bash
+cd /opt/microdao-daarion
+python3 ops/prune_audit_db.py --dry-run
+```