crank/docs/runtime-config.md

Runtime Config

1. Назначение документа

Этот документ фиксирует конфигурацию окружения, storage и базовые operational assumptions для MVP.

Его задача - убрать неявные решения, которые обычно всплывают уже в процессе написания кода.

2. Базовые решения для MVP

• каноническая БД: PostgreSQL
• локальная разработка и тесты используют ту же PostgreSQL-модель хранения
• artifact storage: локальная файловая система
• MCP transport: Streamable HTTP
• admin API и mcp-server запускаются как отдельные приложения

3. Artifact storage

В MVP sample JSON, .proto, descriptor set и YAML import payload должны храниться в локальном файловом storage.

Требования:

• все файлы кладутся в контролируемый базовый каталог;
• в БД хранится только storage_ref;
• структура каталогов должна быть детерминированной;
• storage слой должен быть абстрагирован, чтобы потом заменить его на S3-compatible backend.

Рекомендуемая структура:

var/crank/
  samples/
  descriptors/
  yaml-imports/

4. Секреты и auth profiles

Для MVP:

• operation хранит только auth_profile_ref;
• auth profile хранит только secret_ref;
• реальные секреты не должны попадать в YAML export;
• секреты не должны логироваться.

Допустимые варианты secret storage:

• env-backed secret store;
• encrypted local secret storage.

Минимальный безопасный вариант для MVP:

• secret_ref указывает на env variable alias или key в локальном secret store;
• приложение резолвит его на runtime.

5. Переменные окружения

Минимально ожидаются:

• CRANK_DATABASE_URL
• CRANK_STORAGE_ROOT
• CRANK_ADMIN_BIND
• CRANK_MCP_BIND
• CRANK_MCP_REFRESH_MS
• CRANK_LOG_LEVEL
• CRANK_SECRET_PROVIDER
• CRANK_PUBLIC_BASE_URL
• CRANK_MCP_PUBLIC_URL

Опционально:

• CRANK_ADMIN_TOKEN
• CRANK_MASTER_KEY

Стартовое значение для refresh published tools:

• CRANK_MCP_REFRESH_MS=5000

6. Логирование и трассировка

Для MVP нужно использовать:

• structured logging через tracing;
• correlation id для test runs и runtime execution;
• раздельные стадии ошибок: schema, mapping, adapter, external service.

7. Таймауты и retries

Рекомендуемые стартовые значения:

• default timeout: 10s
• retry default: 1 attempt, то есть без автоматического повтора

Причина:

• сначала важнее детерминированность и прозрачность;
• aggressive retries могут маскировать реальные ошибки интеграции.

8. Режимы запуска

Минимально нужны два режима:

• local development
• demo/deployment

Local development:

• локальное окружение должно иметь доступ к PostgreSQL;
• локальный storage;
• app-level auth и bootstrap admin user через .env.

Demo/deployment:

• PostgreSQL;
• локальный или сетевой storage;
• включенная app-level auth-защита admin-api;
• стабильный Streamable HTTP endpoint для MCP.
• containerized runtime через Docker и docker-compose.

Auth env

Для app-level auth нужны:

• CRANK_SESSION_SECRET
• CRANK_PASSWORD_PEPPER
• CRANK_BOOTSTRAP_ADMIN_EMAIL
• CRANK_BOOTSTRAP_ADMIN_PASSWORD
• CRANK_BOOTSTRAP_ADMIN_DISPLAY_NAME

8.1. Delivery artifacts

Для production-like запуска проект должен поставляться с:

• Dockerfile для backend приложений;
• docker-compose.yml;
• .env.example;
• healthcheck endpoints;
• reverse proxy configuration examples.

Подробности вынесены в docs/deployment.md.

9. Что важно не допустить

• пути к storage, зашитые в код;
• секреты в .yaml exports;
• разные конфигурационные модели для local и production без причины;
• смешивание runtime config и business config operation.

10. Практический итог

До старта разработки должны быть приняты как минимум такие решения:

• где лежит БД;
• где лежат artifacts;
• как резолвятся secret_ref;
• на каких bind-address запускаются admin-api и mcp-server;
• какой transport использует MCP server.