RoleForge/docs/runbook.md

Runbook

Prerequisites

• Docker
• Docker Compose plugin
• GNU Make

No Python/Ansible/PostgreSQL/Redis installation is required on host machine.

Start

cp .env.example .env
make up

Stop

make down

Logs

make logs

Useful container shells

make api-shell
make db-shell

Dynamic workers

• There is no static worker service in docker-compose.yml.
• When a job or test is launched, API starts an ephemeral runner runtime.
• Each runner contains a mini FastAPI service (app/runner/main.py) for direct HTTP/WS communication.
• docker mode: API requires Docker socket access (/var/run/docker.sock).
• k8s mode: API requires Kubernetes API access and RBAC rights to create Pod/Service in APP_K8S_NAMESPACE.

Selecting runtime mode

• Jobs: POST /api/v1/jobs/launch with runtime_mode (docker or k8s).
• Tests: POST /api/v1/tests/launch with runtime_mode (docker or k8s).

Runner lifecycle safety

• Runner is auto-stopped by API when run reaches terminal state.
• Heartbeat is updated while API can poll runner status.
• Timeout and fail-safe cleanup are controlled by:
  • APP_RUNNER_POLL_INTERVAL_SEC
  • APP_RUNNER_TIMEOUT_SEC
  • APP_RUNNER_MAX_POLL_ERRORS
• Active runner list endpoint: GET /api/v1/runners/active.
• Manual runner stop endpoint: POST /api/v1/runners/{runner_name}/stop with body { "runtime_mode": "docker" | "k8s" }.

Realtime test logs

• Launch test via POST /api/v1/tests/launch.
• Follow logs via WebSocket endpoint /ws/tests/{test_id}.

Database bootstrap

Schema bootstrap SQL file is stored in app/sql/001_init.sql and is mounted to PostgreSQL init directory by docker-compose.yml.

To apply it manually:

make migrate