# Runbook

## Prerequisites

- Docker
- Docker Compose plugin
- GNU Make

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

## Start

```bash
cp .env.example .env
make up
```

## Stop

```bash
make down
```

## Logs

```bash
make logs
```

## Useful container shells

```bash
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:

```bash
make migrate
```