crank/docs/deploy-and-staging-smoke.md

Deploy And Staging Smoke

1. Назначение

Этот документ фиксирует обязательный post-deploy smoke pass для staging/production-like окружения.

Он нужен для двух задач:

• быстро проверить, что свежий deploy реально жив, а не просто "docker compose up -d завершился";
• дать следующему агенту и оператору один канонический сценарий проверки после релиза.

Для Community-поставки source of truth для runtime manifests:

• deploy/community/docker-compose.yml
• deploy/community/.env.example

Результаты прохождения этого checklist нужно заносить в staging-regression-notes.md.

Для полного browser-authenticated прохода использовать отдельный документ:

• authenticated-staging-pass.md

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;
• server deployment path собран из public Community manifest, а не из ad-hoc compose файла;
• включенный CRANK_DEMO_SEED=true, если нужен предзаполненный smoke state;
• bootstrap admin credentials для входа в UI.

3.1. Быстрый automated smoke

Есть helper script:

just staging-smoke https://<domain>

или напрямую:

bash scripts/staging-smoke.sh https://<domain>

Он проверяет:

• public routes;
• /api/auth/session JSON contract;
• /mcp/health;
• legacy /html/... redirects.

Это не заменяет ручной smoke pass ниже, а только быстро отсеивает грубые deploy/routing поломки.

4. Server-side smoke

На сервере:

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:

curl --fail --silent http://127.0.0.1:3001/health
curl --fail --silent http://127.0.0.1:3002/health

5. Reverse proxy smoke

Проверить снаружи:

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.

Дополнительно проверить:

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.

Обязательные ручные кейсы:

• 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.