67 lines
5.5 KiB
Markdown
67 lines
5.5 KiB
Markdown
---
|
||
work_item: ORCH-009
|
||
stage: architecture
|
||
author_agent: architect
|
||
status: proposed
|
||
created_at: 2026-06-10
|
||
model_used: claude-opus-4-8
|
||
---
|
||
|
||
# 07 — Инфра-требования: ORCH-009 — Turnkey-онбординг проектов
|
||
|
||
Work Item: **ORCH-009** · Repo: **orchestrator** · Стадия: architecture
|
||
|
||
> Топология оркестратора **не меняется** (NFR-1/NFR-2: `src/**` и compose не трогаются).
|
||
> Файл фиксирует **предусловия исполнения способности** (токены/доступы/контуры) и инфра-границы
|
||
> операторского скрипта. Детали решений — `06-adr/ADR-001-turnkey-onboarding-kit-and-cli.md`.
|
||
|
||
## I-1. Топология / окружения
|
||
|
||
- **Прод (`orchestrator`, 8500):** не затрагивается. Скрипт не создаёт/не останавливает/не
|
||
рестартит контейнеры; в общую БД не пишет (читает только файлы чекаута и внешние API).
|
||
- **Staging (`orchestrator-staging`, 8501, БД `./data/staging`):** контур smoke-прогона (ADR D8).
|
||
Регистрация sandbox-проекта — в `.env.staging`; рестарт staging — штатный, свободный
|
||
(прод-инвариант на него не распространяется).
|
||
- **Новые внешние сущности** (создаются скриптом в `apply`): Plane-проект, Gitea-репо +
|
||
per-repo webhook. Аддитивно: существующие проекты/репо не модифицируются (BR-9).
|
||
- **Запуск скрипта:** хост mva154, из корня чекаута репо orchestrator. Среда исполнения —
|
||
venv с `requirements.txt` (httpx уже в зависимостях; новых pip-зависимостей нет) **или**
|
||
`docker compose exec orchestrator python scripts/onboard_project.py …` (read-only к рантайму,
|
||
без рестартов). Канонический способ фиксирует runbook `docs/operations/ONBOARDING.md`.
|
||
|
||
## I-2. Переменные окружения / секреты
|
||
|
||
**Новых env-переменных не вводится.** Используются существующие (предусловия запуска):
|
||
|
||
| Переменная | Роль в онбординге |
|
||
|---|---|
|
||
| `ORCH_PLANE_API_TOKEN` (+ `ORCH_PLANE_API_URL`, `ORCH_PLANE_WORKSPACE_SLUG`) | создание/чтение Plane-проекта, статусов, лейблов; токен с правом создания проектов в workspace |
|
||
| `ORCH_GITEA_TOKEN` (+ Gitea base URL) | создание репо (под `{{GITEA_OWNER}}`), per-repo webhook; токен с правом create-repo + hooks |
|
||
| `ORCH_GITEA_WEBHOOK_SECRET` | **переиспользуется** для webhook нового репо (приёмник валидирует один глобальный секрет, ADR D6); отсутствует → скрипт генерит и печатает оператору для `.env` |
|
||
| `ORCH_PROJECTS_JSON` | источник существующих записей для merged-вывода (ADR D7); **применение новой строки — операторский шаг** |
|
||
|
||
- Секреты — только в `.env`/`.env.staging` на хосте, в гит не попадают (правило #8 CLAUDE.md);
|
||
в логах/отчётах скрипта секреты маскируются (NFR-3).
|
||
- Kit несёт собственный `.env.example` нового проекта (дескрипторы без значений) — канон секретов
|
||
транслируется в онбордируемые репо.
|
||
|
||
## I-3. Деплой / рестарт
|
||
|
||
- **Скрипт НИКОГДА не рестартит/не останавливает прод-контейнер** (NFR-2, self-hosting инвариант).
|
||
- Регистрация проекта в реестре (Ф-3): правка `.env` (строка `ORCH_PROJECTS_JSON` из отчёта
|
||
скрипта) + **управляемый операторский рестарт** оркестратора — групповое окно для ВСЕХ проектов
|
||
общего инстанса; runbook помечает шаг self-hosting-предупреждением и командой проверки
|
||
(`GET /queue`, резолв статусов нового проекта).
|
||
- TTL-self-heal статусов Plane (ORCH-068, 300с) рестарта не требует: статусы/лейблы, созданные
|
||
после регистрации, подхватываются без вмешательства.
|
||
- Деплой самой задачи ORCH-009 — штатный конвейер: изменение docs/scripts/tests-only, образ
|
||
пересобирается стандартно, staging-гейт (8501) обязателен как обычно.
|
||
|
||
## I-4. CI/CD
|
||
|
||
- `.gitea/workflows/` — **без изменений**: новые тесты (`tests/test_onboarding_kit.py`,
|
||
`test_onboarding_script.py`, `test_onboarding_invariants.py`) подхватываются существующим
|
||
pytest-шагом; все детерминированы, без сети (NFR-5).
|
||
- Инфра-предусловий в образе нет: скрипт — операторский CLI вне рантайма, в образ ничего
|
||
дополнительно не запекается.
|