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

Для целевой модели:

• operation хранит только auth_profile_ref;
• AuthProfile хранит только ссылки на secret_id;
• plaintext секреты не должны попадать в YAML export;
• plaintext секреты не должны логироваться;
• runtime получает секрет только на короткое время перед upstream вызовом.

Стартовая реализация:

• PostgreSQL-backed secret store;
• ciphertext хранится в БД;
• шифрование выполняется через CRANK_MASTER_KEY;
• ключ шифрования приходит только из env.

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

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

• POSTGRES_HOST
• POSTGRES_PORT
• POSTGRES_DB
• POSTGRES_USER
• POSTGRES_PASSWORD
• POSTGRES_MAX_CONNECTIONS
• POSTGRES_MIN_CONNECTIONS
• POSTGRES_ACQUIRE_TIMEOUT_MS
• POSTGRES_IDLE_TIMEOUT_MS
• POSTGRES_MAX_LIFETIME_MS
• CRANK_ADMIN_API_IMAGE
• CRANK_MCP_SERVER_IMAGE
• CRANK_UI_IMAGE
• CRANK_STORAGE_ROOT
• CRANK_PUBLISH_BIND
• CRANK_ADMIN_BIND
• CRANK_MCP_BIND
• CRANK_MCP_REFRESH_MS
• CRANK_LOG_LEVEL
• CRANK_MASTER_KEY
• CRANK_BASE_URL

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

• CRANK_ADMIN_TOKEN
• CRANK_DEMO_SEED

Стартовое значение для 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.
• при необходимости UI можно наполнить живыми demo-данными через CRANK_DEMO_SEED=true.

Demo/deployment:

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

Auth env

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

• CRANK_SESSION_SECRET
• CRANK_PASSWORD_PEPPER
• CRANK_BOOTSTRAP_ADMIN_EMAIL
• CRANK_BOOTSTRAP_ADMIN_PASSWORD
• CRANK_BOOTSTRAP_ADMIN_DISPLAY_NAME

Для secret store foundation нужен:

• CRANK_MASTER_KEY

CRANK_MASTER_KEY обязателен и для admin-api, и для mcp-server, потому что оба приложения должны уметь резолвить secret_id в runtime.

Для опционального demo-seed:

• CRANK_DEMO_SEED=true

В deployment workflow больше не используется монолитный DEPLOY_ENV_FILE.

.env на сервере собирается из отдельных GitHub secrets, причем имя секрета совпадает с именем runtime env-переменной. Это значит, что:

• CRANK_MASTER_KEY хранится как GitHub secret CRANK_MASTER_KEY;
• CRANK_DEMO_SEED хранится как GitHub secret CRANK_DEMO_SEED;
• и так же для остальных runtime-переменных.

Для БД основной runtime-контракт теперь компонентный:

• POSTGRES_HOST
• POSTGRES_PORT
• POSTGRES_DB
• POSTGRES_USER
• POSTGRES_PASSWORD
• POSTGRES_MAX_CONNECTIONS
• POSTGRES_MIN_CONNECTIONS
• POSTGRES_ACQUIRE_TIMEOUT_MS
• POSTGRES_IDLE_TIMEOUT_MS
• POSTGRES_MAX_LIFETIME_MS

Для pool behavior используются явные defaults:

• POSTGRES_MAX_CONNECTIONS=20
• POSTGRES_MIN_CONNECTIONS=2
• POSTGRES_ACQUIRE_TIMEOUT_MS=5000
• POSTGRES_IDLE_TIMEOUT_MS=600000
• POSTGRES_MAX_LIFETIME_MS=1800000

CRANK_DATABASE_URL допускается только как backward-compatible fallback для локальных тестов и переходного периода, но не как основная deployment-модель.

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_id и как ротируется CRANK_MASTER_KEY;
• на каких bind-address запускаются admin-api и mcp-server;
• какой transport использует MCP server.