a.tolmachev
168 lines
5.5 KiB
Markdown
168 lines
5.5 KiB
Markdown
# 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.
|
||
|
||
Рекомендуемая структура:
|
||
|
||
```text
|
||
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_ADMIN_API_IMAGE`
|
||
- `CRANK_MCP_SERVER_IMAGE`
|
||
- `CRANK_UI_IMAGE`
|
||
- `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`
|
||
- `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`
|
||
|
||
Для опционального demo-seed:
|
||
|
||
- `CRANK_DEMO_SEED=true`
|
||
|
||
## 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.
|