docs: add deploy and staging smoke runbook

2026-04-07 12:36:32 +03:00
parent 01bf5a1188
commit f1042877b2
5 changed files with 230 additions and 6 deletions
@@ -46,6 +46,7 @@ Crank - платформа для публикации внешних API в в
 - `docs/manual-regression-checklist.md` - post-integration regression baseline и ручной smoke checklist.
 - `docs/runtime-config.md` - конфигурация окружения.
 - `docs/deployment.md` - деплой, reverse proxy и CI/CD.
+- `docs/deploy-and-staging-smoke.md` - канонический post-deploy smoke pass для staging/production-like окружения.
 - `docs/demo-runbook.md` - демонстрационный сценарий.
 - `docs/public-smoke-targets.md` - готовые публичные upstream-сервисы и payload-ы для smoke-проверки MCP.
 - `docs/secrets-auth-plan.md` - целевая модель upstream secrets, auth profiles и пошаговый план реализации.
@@ -2,19 +2,18 @@

 ## Current

-### `feat/post-regression-fixes`
+### `feat/deploy-and-staging-smoke`

 Status: completed

 DoD:
- misleading non-functional UI actions are clearly marked or disabled
- login page no longer suggests working password-reset/SSO/request-access flows
- settings planned capabilities look explicitly read-only and non-interactive
- node checks, UI docker build, affected Playwright specs and workspace check pass
+- deploy/staging smoke checklist exists
+- checklist covers server health, proxy routing, auth, UI pages, secrets, MCP, streaming
+- deployment, demo and README docs link to the same smoke runbook

 ## Next

- `feat/deploy-and-staging-smoke`
+- `feat/staging-regression-notes`

 ## Backlog

@@ -110,3 +110,9 @@ YAML roundtrip считается успешным, если:
 - `mcp-server` подхватывает published changes без restart;
 - ошибки `admin-api` и runtime возвращаются в читаемом виде;
 - логи позволяют понять, какая операция создавалась, тестировалась, публиковалась или импортировалась.
+
+## 9. Post-deploy smoke
+
+Если demo запускается не локально, а на staging/production-like стенде, после deploy нужно пройти отдельный checklist:
+
+- [deploy-and-staging-smoke.md](/home/a.tolmachev/code/rust/mcpaas/docs/deploy-and-staging-smoke.md)
@@ -0,0 +1,216 @@
+# Deploy And Staging Smoke
+
+## 1. Назначение
+
+Этот документ фиксирует обязательный post-deploy smoke pass для staging/production-like окружения.
+
+Он нужен для двух задач:
+
+- быстро проверить, что свежий deploy реально жив, а не просто "docker compose up -d завершился";
+- дать следующему агенту и оператору один канонический сценарий проверки после релиза.
+
+## 2. Когда использовать
+
+Запускать после:
+
+- merge в `main` и успешного `Deploy`;
+- изменения `nginx`/routing;
+- изменения auth/session;
+- изменения `mcp-server`;
+- изменения streaming/tool execution;
+- изменения secrets/auth profiles;
+- изменения UI routing и login flow.
+
+## 3. Предусловия
+
+Нужно иметь:
+
+- задеплоенный стек `ui`, `admin-api`, `mcp-server`, `postgres`;
+- корректный `.env` на сервере;
+- валидный deploy через `.github/workflows/deploy.yml`;
+- включенный `CRANK_DEMO_SEED=true`, если нужен предзаполненный smoke state;
+- bootstrap admin credentials для входа в UI.
+
+## 4. Server-side smoke
+
+На сервере:
+
+```bash
+cd /opt/rmcp
+docker compose ps
+docker compose logs --tail=100 admin-api
+docker compose logs --tail=100 mcp-server
+```
+
+Ожидаемо:
+
+- `admin-api` в `Up` / `healthy`;
+- `mcp-server` в `Up` / `healthy`;
+- нет циклических restart-ов;
+- нет `NotPresent`, `password authentication failed`, `panic`, `invalid transition` и аналогичных fatal ошибок.
+
+Проверка health endpoints:
+
+```bash
+curl --fail --silent http://127.0.0.1:3001/health
+curl --fail --silent http://127.0.0.1:3002/health
+```
+
+## 5. Reverse proxy smoke
+
+Проверить снаружи:
+
+```bash
+curl -I https://<domain>/
+curl -I https://<domain>/login
+curl -I https://<domain>/agents
+curl -I https://<domain>/secrets
+curl -I https://<domain>/wizard/
+curl -I https://<domain>/api/auth/session
+curl -I https://<domain>/mcp/health
+```
+
+Ожидаемо:
+
+- `/`, `/login`, `/agents`, `/secrets`, `/wizard/` -> `200`;
+- `/api/auth/session` -> `200` или `401` с JSON, но не HTML fallback;
+- `/mcp/health` -> `200`;
+- старые `/html/...` пути редиректят на clean routes.
+
+Дополнительно проверить:
+
+```bash
+curl -I https://<domain>/html/login.html
+curl -I https://<domain>/html/agents.html
+curl -I https://<domain>/html/wizard/
+```
+
+Ожидаемо:
+
+- `302` на `/login`, `/agents`, `/wizard/`.
+
+## 6. UI smoke
+
+В браузере:
+
+1. Открыть `/login`
+2. Проверить:
+   - нет redirect loop;
+   - invalid login показывает ошибку;
+   - страница честно помечает password-only flow;
+   - `Forgot password`, `Google SSO`, `Request access` визуально disabled/planned.
+3. Выполнить login.
+4. Проверить navbar:
+   - workspace switch;
+   - user identity;
+   - clean routing без `/html/...`.
+
+## 7. Core page smoke
+
+После входа открыть и проверить:
+
+- `/`
+- `/agents`
+- `/api-keys`
+- `/secrets`
+- `/logs`
+- `/usage`
+- `/workspace-setup`
+- `/settings`
+- `/stream-sessions`
+- `/async-jobs`
+- `/wizard/`
+
+Для каждой страницы:
+
+- данные грузятся;
+- нет бесконечных spinners;
+- нет console errors;
+- empty/loading/error states выглядят корректно;
+- language switch не ломает layout.
+
+## 8. Auth and secrets smoke
+
+Обязательная связка:
+
+1. Открыть `/secrets`
+2. Создать secret
+3. Создать или выбрать auth profile
+4. Открыть `/wizard/`
+5. На шаге 2:
+   - выбрать existing auth profile;
+   - проверить quick-create secret;
+   - проверить quick-create auth profile;
+6. Сохранить upstream
+7. Выполнить `Test run`
+
+Smoke считается успешным, если:
+
+- wizard не требует `${secrets.*}`;
+- `auth_profile_ref` реально доезжает до execution path;
+- plaintext не возвращается после create/rotate.
+
+## 9. MCP and protocol smoke
+
+Использовать примеры из [public-smoke-targets.md](/home/a.tolmachev/code/rust/mcpaas/docs/public-smoke-targets.md).
+
+Обязательные ручные кейсы:
+
+- `REST` -> `Open-Meteo`
+- `GraphQL` -> `Countries`
+- `gRPC` -> `grpcb.in`
+
+Порядок:
+
+1. создать operation;
+2. выполнить `Test run`;
+3. publish;
+4. привязать к agent;
+5. проверить MCP path;
+6. выполнить `tools/list` и `tools/call`.
+
+## 10. Streaming smoke
+
+На deployed стенде проверить:
+
+- `window` tool выполняется и не возвращает бесконечный поток;
+- `session` tool создает записи в `/stream-sessions`;
+- `async_job` tool создает записи в `/async-jobs`;
+- UI pages `/stream-sessions` и `/async-jobs` не пустые после вызовов.
+
+Если есть real upstream:
+
+- `WebSocket window/session`
+- `SOAP import + inspect + test run`
+
+Если real upstream нет, это остается на локальном e2e/fixture stack.
+
+## 11. Acceptance criteria
+
+Deploy/staging smoke считается успешным, если:
+
+- server health зеленый;
+- reverse proxy отдает правильные routes;
+- login/session живы;
+- all core pages открываются;
+- secrets/auth/wizard связка работает;
+- минимум `REST`, `GraphQL`, `gRPC` проходят `create -> test-run -> publish -> MCP call`;
+- streaming pages отображают реальные session/job artifacts;
+- нет критичных JS ошибок в браузере.
+
+## 12. Если что-то падает
+
+Порядок разбора:
+
+1. `docker compose ps`
+2. `docker compose logs --tail=100 admin-api`
+3. `docker compose logs --tail=100 mcp-server`
+4. `curl` локальных `/health`
+5. `curl -I` публичных routes
+6. browser devtools:
+   - network;
+   - console;
+   - `/api/auth/session`;
+   - page-specific API requests
+
+Не надо сразу трогать БД, env или `nginx`, пока не найден точный failing layer.
@@ -13,6 +13,8 @@

 Документ не привязан к конкретному hypervisor, cloud provider, типу VM или домашней инфраструктуре.

+Практический post-deploy smoke checklist вынесен отдельно в [deploy-and-staging-smoke.md](/home/a.tolmachev/code/rust/mcpaas/docs/deploy-and-staging-smoke.md).
+
 ## 2. Базовая модель деплоя

 Для MVP принимается контейнерная модель: