Цели make¶

Все цели корневого Makefile суперпроекта — единого механизма запуска, проверки и документации платформы. Статья для инженера, который поднимает стенд, прогоняет проверки перед коммитом или собирает это руководство. Запускайте make из корня суперпроекта; make без аргументов печатает список целей с описаниями (make help).

Сводка¶

Цель	Параметры	Что делает
`help`	—	Список целей с описаниями (цель по умолчанию).
`secrets`	—	Создаёт `.env` из `.env.example` (если его нет), заполняет пустые секреты, генерирует ключи подписи.
`config`	`PROFILES`	Проверяет `compose.yml` после интерполяции для выбранных профилей.
`build`	`PROFILES`	Собирает образы выбранных профилей.
`up`	`PROFILES`	Собирает и поднимает выбранные профили в фоне.
`down`	—	Останавливает и удаляет контейнеры всех профилей; volumes сохраняются.
`ps`	—	Состояние контейнеров всех профилей.
`logs`	`svc`	Поток логов сервиса (или всех).
`smoke`	—	Проверяет health поднятых сервисов через порты `127.0.0.1`.
`bootstrap`	`ARGS`	Первичная инициализация: tenant, principals, PAT, bindings, каталог.
`reset-state`	—	После сброса volumes переносит state bootstrap и выданные им credentials в `secrets/stale-<время>/`.
`check`	—	Lint + unit-тесты всех компонентов ядра (как обязательный CI).
`check-frozen`	—	То же для замороженного периметра.
`check-<компонент>`	—	Lint + тесты одного компонента.
`lint-<компонент>`	—	Только lint одного компонента.
`test-<компонент>`	—	Только тесты одного компонента.
`packages-check`	—	Проверка пакетов каталога `packages/`.
`adr-index`	—	Пересобирает сводный реестр ADR `docs/adr/index.md`.
`docs-gen`	`ARGS=--check`	Генерирует разделы справочника руководства из кода (переменные окружения, API); с `--check` только проверяет, что они актуальны.
`linkcheck`	—	Проверяет относительные ссылки в документации.
`submodules`	—	Инициализирует сабмодули на закреплённых ревизиях.
`status`	—	Указатели сабмодулей и незакоммиченные изменения.
`guide`	—	Собирает это руководство в `guide/site`.
`guide-serve`	—	Руководство с живой перезагрузкой на `http://127.0.0.1:8008`.

Переменные make¶

Переменная	По умолчанию	Где используется
`PROFILES`	`core edge`	`config`, `build`, `up`: превращается в `docker compose --profile <p> …` для каждого профиля.
`svc`	пусто (все сервисы)	`logs`.
`ARGS`	пусто	`bootstrap`: дополнительные аргументы `deploy/bootstrap.py`.
`BOOTSTRAP_PY`	`uv run --no-project --quiet --with pyyaml --with jsonschema python3`, если uv установлен; иначе `python3`	`bootstrap`: интерпретатор скрипта.
`ENV_NAME`	`COMPOSE_PROJECT_NAME` из `.env`, иначе `taimen`	`reset-state`: имя файла состояния.

Внутренние списки компонентов:

Список	Состав
`COMPONENTS_PY` (ядро, `make check`)	`platform-auth-sdk`, `platform-llm`, `skill-sdk`, `iam-service`, `control-plane`, `memory-service`
`COMPONENTS_FROZEN` (`make check-frozen`)	`entitlement-service`, `policy-service`

Запуск стека¶

make secrets¶

make secrets

Если .env нет — копирует .env.example в .env и ставит права 600.
tools/fill_secrets.py .env заполняет только пустые значения из фиксированного списка случайными hex-строками (secrets.token_hex): пароли БД (CP_, IAM_, MEMORY_, PLATFORM_, KEYCLOAK_DB_, REDIS_, ENT_, POL_), bootstrap-токены (CP_, IAM_, ENT_, POL_), MEMORY_API_KEY, KEYCLOAK_ADMIN_PASSWORD, KEYCLOAK_CLIENT_SECRET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY. Существующие значения не трогаются; повторный запуск безопасен.
Создаёт каталог secrets.
Генерирует RSA 3072 ключи secrets/iam-signing.pem и secrets/entitlement-signing.pem, если их нет, и ставит 600.

На Linux — владелец uid 10001

Контейнеры читают ключи под uid 10001. После make secrets выполните chown 10001 secrets/*.pem, иначе IAM не прочитает ключ подписи.

IAM_TENANT_ID, SUPPORT_WORKSPACE_ID, SUPPORT_BOT_PAT цель не заполняет: сгенерировать их нечем. В compose.yml они по умолчанию пусты, поэтому make up для core edge работает сразу после make secrets; нужны они только своим профилям — см. Переменные окружения.

make config¶

make config
make config PROFILES="core platform edge"

docker compose … config --quiet; при успехе печатает compose.yml корректен для профилей: …. Ловит пустые обязательные переменные и ошибки интерполяции до запуска.

make build / make up¶

make up                                   # core edge
make up PROFILES="core platform edge"     # с замороженной панелью
make up PROFILES="core fleet edge"
make build PROFILES="core"

up выполняет docker compose --profile … up -d --build: пересобирает изменившиеся образы и пересоздаёт контейнеры. Замороженные и экспериментальные профили (entitlement, policy, platform) включаются только явно.

make down / ps / logs¶

make down
make ps
make logs svc=control-plane-api
make logs                       # все сервисы

Эти цели работают с --profile "*" — со всеми профилями сразу, независимо от PROFILES. down не удаляет volumes: данные сохраняются.

make smoke¶

make smoke

tools/smoke.py читает порты из .env (или окружения) и опрашивает health-эндпоинты поднятых сервисов; не запущенные помечает «не запущен» и ошибкой не считает. Код выхода 1, если хотя бы один поднятый сервис ответил ≥ 400. Перечень проверок — в Сервисы и порты.

make bootstrap¶

make bootstrap
make bootstrap ARGS="--name staging --secrets-dir secrets --packages deploy/packages.yaml"
make bootstrap ARGS=--policy

Запускает deploy/bootstrap.py --env .env $(ARGS): если uv установлен — через uv run --no-project --quiet --with pyyaml --with jsonschema python3 (PyYAML и jsonschema ставить в систему не нужно), иначе системным python3, в котором тогда должны быть PyYAML и jsonschema. Скрипт идемпотентен: состояние хранится в deploy/state/<env>.json, повторный запуск пропускает сделанное. Аргументы:

Аргумент	По умолчанию	Назначение
`--env`	`.env`	Файл окружения (цель передаёт `.env`).
`--name`	`COMPOSE_PROJECT_NAME`	Имя окружения — имя файла состояния.
`--operator`	значение из кода	Отображаемое имя human-оператора.
`--tenant-slug`	`COMPOSE_PROJECT_NAME`	Slug tenant.
`--pat-ttl`	`15552000` (180 дней)	Срок выпускаемых PAT, секунды.
`--secrets-dir`	`secrets`	Куда писать PAT и env-файлы service accounts.
`--packages`	`deploy/packages.yaml`	Файл установки каталога (`kind: Installation`).
`--policy`	выкл.	Профиль `policy` обязателен: ждать policy-service до 30 с и падать, если его нет. Без флага шаг 7 выполняется, только если policy-service уже отвечает.

Что делает по шагам и какие права выдаёт — Bootstrap и Права и scopes.

make reset-state¶

docker compose --profile "*" down -v   # сброс volumes
make reset-state
make up && make bootstrap

Нужна после удаления volumes: файл состояния bootstrap ссылается на tenant и principals, которых в пустых базах уже нет, и bootstrap в этом случае останавливается с подсказкой make reset-state. Цель переносит в secrets/stale-<ГГГГММДД-ЧЧММСС>/:

deploy/state/<ENV_NAME>.json;
secrets/harness-pat, secrets/control-plane-iam.env, secrets/memory-service-iam.env, secrets/policy-service-cp.env.

Ключи подписи (secrets/*.pem) и .env не трогает. Если переносить нечего, печатает нечего убирать. Файлы не удаляются — старые credentials можно отозвать или удалить вручную позже.

Проверки¶

make check / check-frozen¶

make check            # ядро: как обязательный CI
make check-frozen     # entitlement-service, policy-service

Для каждого компонента выполняется lint-<компонент> и test-<компонент>.

make check-<компонент>, lint-<компонент>, test-<компонент>¶

make check-control-plane
make lint-memory-service
make test-iam-service

lint-<компонент> — uv run ruff check . и uv run ruff format --check . в каталоге компонента.

test-<компонент> по умолчанию — uv run pytest -q в каталоге компонента. Для некоторых компонентов есть свои правила:

Цель	Что делает дополнительно
`test-control-plane`	Поднимает `db-test` из `control-plane/docker-compose.yml` (профиль `test`, порт 5434), запускает `pytest tests/unit tests/client`, затем останавливает БД.
`test-policy-service`	Поднимает OpenFGA из `policy-service/compose.test.yml` (порт 18090), `POL_TEST_FGA_URL=http://127.0.0.1:18090`.
`test-skill-sdk`	Тесты `skill-sdk` со всеми extras, затем сквозной тест исполнителя через `control-plane` (`tests/test_executor_e2e.py`).
`test-memory-service`	`pytest` с extra `mcp`, без `tests/integration`.

Тестовые БД занимают порты хоста

test-control-plane и test-policy-service поднимают контейнеры на портах 5434 и 18090. Если порт занят, тесты не стартуют.

make packages-check¶

make packages-check

tools/cp_packages.py check — схема, ссылки и валидаторы ядра для пакетов в packages/.
tools/cp_packages.py check --install deploy/staging/packages.yaml — проверка файла установки.
pytest -q tools/tests (через uv run --no-project с pytest, pyyaml, jsonschema, regex, ruamel.yaml).

См. Пакеты каталога.

Документация и репозиторий¶

Цель	Команда	Примечание
`adr-index`	`python3 tools/adr_index.py`	Реестр четырёх рядов ADR (`TAI-`, `CP-`, `PC-`, `MEM-`).
`docs-gen`	`uv run --no-project --with pyyaml python tools/docs_gen.py`	Разделы `guide/` между маркерами `<!-- generated:… -->` (ADR-0046).
`linkcheck`	`python3 tools/linkcheck.py`	Относительные ссылки в документации суперпроекта.
`submodules`	`git submodule update --init --recursive`	После клонирования и после bump указателей.
`status`	`git submodule status` и `git status --short`	Быстрый обзор состояния.
`guide`	`cd guide && uv run --with-requirements requirements.txt mkdocs build --strict`	Любое предупреждение MkDocs — ошибка сборки.
`guide-serve`	`… mkdocs serve -a 127.0.0.1:8008`	Живой просмотр руководства.

Типичные последовательности¶

Первый запускЗаново после сброса volumesПеред коммитом в компонентОбновление стенда

make submodules
make secrets
make config
make up
make smoke
make bootstrap
# вписать выведенный IAM_TENANT_ID в .env, затем
make up

docker compose --profile "*" down -v
make reset-state
make up
make bootstrap

make check-control-plane

git pull --ff-only
make submodules
make up PROFILES="core edge"
make smoke