From f1042877b2d5d15360a840c077eaa0a924eb4872 Mon Sep 17 00:00:00 2001 From: "a.tolmachev" Date: Tue, 7 Apr 2026 12:36:32 +0300 Subject: [PATCH] docs: add deploy and staging smoke runbook --- README.md | 1 + TASKS.md | 11 +- docs/demo-runbook.md | 6 + docs/deploy-and-staging-smoke.md | 216 +++++++++++++++++++++++++++++++ docs/deployment.md | 2 + 5 files changed, 230 insertions(+), 6 deletions(-) create mode 100644 docs/deploy-and-staging-smoke.md diff --git a/README.md b/README.md index a453896..b1aa0b2 100644 --- a/README.md +++ b/README.md @@ -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 и пошаговый план реализации. diff --git a/TASKS.md b/TASKS.md index c10ccf2..60d1640 100644 --- a/TASKS.md +++ b/TASKS.md @@ -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 diff --git a/docs/demo-runbook.md b/docs/demo-runbook.md index 03b9c0a..21d67fb 100644 --- a/docs/demo-runbook.md +++ b/docs/demo-runbook.md @@ -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) diff --git a/docs/deploy-and-staging-smoke.md b/docs/deploy-and-staging-smoke.md new file mode 100644 index 0000000..0e96236 --- /dev/null +++ b/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:/// +curl -I https:///login +curl -I https:///agents +curl -I https:///secrets +curl -I https:///wizard/ +curl -I https:///api/auth/session +curl -I https:///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:///html/login.html +curl -I https:///html/agents.html +curl -I https:///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. diff --git a/docs/deployment.md b/docs/deployment.md index 614893e..58a1331 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -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 принимается контейнерная модель: