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

Deploy And Staging Smoke

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

Этот документ фиксирует обязательный post-deploy smoke pass для Community 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;
• изменений secrets/auth profiles;
• изменений UI routing и login flow;
• изменений deploy/community/*.

3. Предусловия

Нужно иметь:

• задеплоенный стек ui, admin-api, mcp-server, postgres;
• корректный .env на сервере;
• валидная сборка и доставка образов в выбранной инфраструктуре;
• server deployment path, собранный из deploy/community/docker-compose.yml;
• 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-ов;
• нет 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;
3. Выполнить login.
4. Проверить navbar:
   • workspace switch;
   • user identity;
   • clean routing без /html/....

7. Core page smoke

После входа открыть и проверить:

• /
• /agents
• /api-keys
• /secrets
• /logs
• /usage
• /workspace-setup
• /settings
• /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 REST smoke

Использовать пример из public-smoke-targets.md.

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

• REST -> Open-Meteo

Порядок:

1. создать operation;
2. выполнить Test run;
3. publish;
4. привязать к agent;
5. проверить MCP path;
6. выполнить tools/list и tools/call.

10. Acceptance criteria

Deploy или staging smoke считается успешным, если:

• server health зеленый;
• reverse proxy отдает правильные routes;
• login/session живы;
• все core pages открываются;
• связка Secrets -> Auth Profiles -> Wizard -> Test run работает;
• минимум один REST operation проходит create -> test-run -> publish -> MCP call;
• нет критичных JS ошибок в браузере.

11. Если что-то падает

Порядок разбора:

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.