homelab-codex-ws/kb/runbooks/kb-query-deploy.md

---
okf: "0.1"
type: runbook
visibility: private
status: active
updated: 2026-07-29
links:
  - ../services/kb-query.md
---

# kb-query — deploy i weryfikacja (PIHA)

## Deploy (PIHA)

0. Prerequisite: `ollama-piha` deployed and `bge-m3` pulled — see
   `kb/services/ollama-piha.md` (the pull is a **manual** deploy step).
1. `git pull` on PIHA (`~/homelab-codex-ws`).
2. `cp services/kb-query/env.example services/kb-query/.env` and fill in the
   real `KB_DSN` password (the template already sets `EMBED_FALLBACK_URL`).
   On an existing install: add `EMBED_FALLBACK_URL=http://192.168.31.5:11434`
   to the existing `.env`.
3. ```
   docker compose -f services/kb-query/docker-compose.yml \
     -f hosts/piha/runtime/kb-query/docker-compose.override.yml up -d --build
   ```
4. Verify: `services/kb-query/healthcheck.sh`, then from PIHA:
   `curl "http://192.168.31.5:8230/search?q=test"` and open
   `http://192.168.31.5:8230/` in a browser.

## Fallback verification (execution: operator, after deploy)

- **Test A — SOLARIA online**: query via UI/`curl`; response has
  `"embed_backend": "solaria"`, `docker logs kb-query` shows
  `backend=solaria`, latency ~sub-second.
- **Test B — SOLARIA offline**: either wait for the nightly power-off, or
  simulate: set `EMBED_PRIMARY_URL=http://192.0.2.1:11434` (TEST-NET, always
  unreachable) in `.env` and `docker compose … up -d` again. Query still
  works; response has `"embed_backend": "piha"`, log shows `backend=piha`
  plus a `circuit open for 30s` warning on the first hit; latency visibly
  higher (CPU + cold model load each time, `OLLAMA_KEEP_ALIVE=0`). Revert
  `.env` afterwards if simulated.
- **Test C — SOLARIA returns**: after it is back up, within ≤30 s (one
  health-cache TTL) responses show `"embed_backend": "solaria"` again, no
  restart needed.

## Tests

```
pip install -e packages/kb-retrieval/
cd services/kb-query && pip install -r requirements.txt pytest pytest-asyncio && pytest
```

Unit tests mock the DB connection and Ollama HTTP session (no live DB/Ollama
required) — same style as `packages/kb-retrieval/tests/`. `tests/test_frontend.py`
drives `GET /`/`/static/*` through FastAPI's `TestClient` without entering it
as a context manager, so the DB-requiring `lifespan` never runs.

Frontend JS has its own pure-function tests (query-URL encoding, threshold
colouring, envelope grouping), run without a browser via Node's built-in
test runner: `node --test services/kb-query/tests/frontend/`.