146 lines
6.8 KiB
Markdown
146 lines
6.8 KiB
Markdown
# 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`
|