oskar/homelab-codex-ws
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
homelab-codex-ws/kb/runbooks/kb-query-deploy.md
oskar 6b85c7ef68 feat(kb): SPLIT service+runbook — 10 serwisow -> 20 dokumentow 
Wzorzec mechaniczny: sekcje deploy/verify/install/testy wycinane do
kb/runbooks/<serwis>-*.md, reszta zostaje dokumentem type: service.
Wzajemne `links` w obie strony. Tresc sekcji nietknieta — przenoszone
doslownie, dodany wylacznie naglowek H1 nowego runbooka.

kb-query, paperless-worker, planner-agent, ha-diag-agent, ollama-piha,
narty27, home-assistant, ha-mcp, job-gmail-header-backfill, job-mail-body-ingest.

Weryfikacja: dla kazdego pliku multizbior niepustych linii
(main + runbook) == oryginal z HEAD. Zero zgubionych, zero dodanych.

Recon szacowal 13 splitow service+runbook; faktycznie 2-typowych jest 10,
pozostale 5 (paperless, nextcloud, gokapi, fleet-prometheus, deploy-runner)
sa 3-typowe i ida osobno jako splity wielotypowe.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 16:58:46 +02:00

2.4 KiB
Raw Blame History

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

kb-query — deploy i weryfikacja (PIHA)

Deploy (PIHA)

  1. Prerequisite: ollama-piha deployed and bge-m3 pulled — see services/ollama-piha/README.md (the pull is a manual deploy step).
  2. git pull on PIHA (~/homelab-codex-ws).
  3. 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.
  4. docker compose -f services/kb-query/docker-compose.yml \
  -f hosts/piha/runtime/kb-query/docker-compose.override.yml up -d --build
  5. 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/.