first commit

infra/forcad-local/README.md

@@ -0,0 +1,145 @@
+# forcad-local
+
+Автоматизированный локальный оркестратор для запуска ForcAD + игровых сервисов + чекеров в контейнерах.
+
+Инструмент делает:
+- auto-discovery сервисов в переданной папке;
+- preflight-проверки структуры сервисов и чекеров;
+- containerized сборку checker-артефактов (например `make` для `archive`) без хостовых dev-пакетов;
+- auto-cleanup хвостов прошлых запусков перед новым `up`;
+- prewarm k3d/k3s образов перед деплоем k3d-сервисов;
+- retry для k3d-деплоя и rollback при ошибке (настраивается);
+- генерацию runtime-конфига ForcAD без правок исходников борды/сервисов;
+- запуск `light` smoke-check `check` для каждого сервиса без полного ForcAD стека;
+- опциональный `full` режим с полным ForcAD стеком;
+- команды `up`, `down`, `status`, `validate`.
+
+## Требования
+
+- `docker` + `docker compose`
+- Python 3.10+
+- Для Helm/k3d-профилей сервисов: `helm`, `kubectl`, `k3d` (если требуется конкретному сервису)
+
+## Базовый запуск
+
+```bash
+python3 infra/forcad-local/forcad_local.py validate \
+  --services-root /path/to/services \
+  --checkers-root /path/to/checkers
+```
+
+```bash
+python3 infra/forcad-local/forcad_local.py up \
+  --services-root /path/to/services \
+  --checkers-root /path/to/checkers \
+  --mode light
+```
+
+```bash
+python3 infra/forcad-local/forcad_local.py status
+```
+
+```bash
+python3 infra/forcad-local/forcad_local.py down
+```
+
+После `up` борда доступна по `http://127.0.0.1:8080/` (или через `--board-port`).
+Это относится только к `--mode full`. В `--mode light` борда не запускается.
+
+## Какие структуры поддерживаются
+
+Для сервиса в `services-root/<service_name>/`:
+
+1. **Compose-профиль**
+   - должен быть `docker-compose.yml`
+2. **Script/Helm-профиль**
+   - `deploy.sh`, либо
+   - `redeploy.sh`, либо
+   - `deploy/chart/values.yaml` (с возможным `build-docker.sh`)
+
+Для чекера в `checkers-root/<service_name>/`:
+- должен быть `checker.py` **или** `*.checker.py`
+- если есть `requirements.txt` (или `requirments.txt`) — зависимости автоматически объединяются
+- если есть `Makefile` — сборка выполняется внутри builder-контейнера (`cpp-make` профиль по умолчанию)
+
+## Автопроверки (preflight)
+
+Команда `validate` проверяет:
+- обнаружены ли сервисы;
+- есть ли deploy-профиль;
+- есть ли checker entrypoint;
+- определён ли host-порт для сервиса;
+- нет ли конфликтов портов между сервисами и портом борды;
+- наличие системных команд (`docker`, а для helm/k3d-профиля — предупреждения про `helm`, `kubectl`, `k3d`).
+- валидность конфигурации containerized checker-build профиля.
+
+## Поведение `up` по умолчанию
+
+- сервисы сортируются в детерминированном порядке (k3d-сервисы сначала);
+- перед запуском выполняется auto-cleanup по обнаруженным сервисам;
+- для k3d-сервисов заранее выполняется pull базовых образов;
+- если k3d-деплой падает, делается retry (`--k3d-retries`);
+- в `strict` режиме падение одного сервиса прерывает запуск и откатывает уже поднятые;
+- в `best-effort` режимe проблемные сервисы пропускаются.
+
+## Runtime-файлы
+
+Все временные файлы создаются в:
+- `infra/forcad-local/.runtime/`
+
+Кэш сборки checker-артефактов:
+- `infra/forcad-local/.cache/checker-builds/`
+
+Там же сохраняется `state.json`, который используется командами `status` и `down`.
+
+## Переопределения через manifest
+
+Если auto-discovery не хватает, в `services-root` можно положить файл `forcad-local.json`:
+
+```json
+{
+  "services": {
+    "warehouse": {
+      "checker_dir": "warehouse",
+      "port": 31443,
+      "checker_timeout": 40,
+      "checker_type": "pfr",
+      "places": 2,
+      "profile": "helm_chart",
+      "start_cmd": "bash redeploy.sh",
+      "stop_cmd": "helm uninstall warehouse -n warehouse",
+      "checker_build": {
+        "enabled": false
+      }
+    },
+    "archive": {
+      "checker_build": {
+        "enabled": true,
+        "profile": "cpp-make",
+        "command": "make",
+        "artifacts": ["libgen"]
+      }
+    }
+  }
+}
+```
+
+Поля опциональны. Используй их, если сервис нестандартный или порт не удаётся вывести автоматически.
+
+## Полезные параметры
+
+- `--service <name>` — выбрать конкретные сервисы (можно повторять)
+- `--board-port 8080` — порт борды
+- `--mode light|full` — режим работы (`light` по умолчанию)
+- `--failure-policy strict|best-effort` — остановиться при первой ошибке или пропускать упавшие сервисы
+- `--rollback-on-failure / --no-rollback-on-failure` — откат уже поднятых сервисов при ошибке в strict режиме
+- `--auto-cleanup / --no-auto-cleanup` — очистка прошлых запусков перед новым `up`
+- `--prewarm-k3d / --no-prewarm-k3d` — предварительный pull k3d/k3s образов
+- `--k3d-retries` — число повторов деплоя для k3d-сервисов
+- `--k3d-retry-delay` — задержка между retry для k3d
+- `--image-pull-retries` — число дополнительных retry на pull docker-образов
+- `--image-pull-retry-delay` — задержка между retry pull
+- `--team-count 2` — число команд в runtime-конфиге
+- `--workers 2` — число celery worker'ов
+- `--cache-dir` — путь к кэшу сборки checker-артефактов
+- `--no-fast` — не использовать `docker-compose-fast.yml`