homelab-codex-ws/docs/sessions/2026-07-23-kb-f4-ingress.md

# Sesja 2026-07-23 — KB faza 4: ingress kb.kapala.org (krok 5/§8)

**Zakres**: wyłącznie ingress (`docs/kb/modules/05-faza4-plan.md` §8, krok 5) —
frontend i `/search` już LIVE na PIHA (port 8230) od sesji 2026-07-22. Zero
zmian w kodzie kb-query w tej sesji.

## Zrobione

### 1. Vhost npm@PIHA
`scripts/npm/npm_api.py --npm piha create-host --domain kb.kapala.org
--forward-host 192.168.31.5 --forward-port 8230 --cert-id 49 --ssl-forced
--http2-support --block-exploits --websocket --apply` → **proxy host #35**.
Parametry skopiowane 1:1 z `paper.kapala.org` (#33) po odczytaniu jego configu
przez API — `forward_scheme=http`, `access_list_id=0`, `caching_enabled=false`,
`advanced_config` puste (lekcja z `docs/sessions/2026-06-30-kapala-cloudflare-wildcard-mesh.md`:
`proxy_http_version` ręcznie w Advanced + Websockets ON = duplikat dyrektywy,
`nginx -t` odrzuca cały plik). Cert #49 = `*.kapala.org` wildcard, DNS-01
Cloudflare, ważny do 2026-09-28 — **żaden nowy cert nie powstał**, zgodnie z
planem.

### 2. Pi-hole split-horizon
Mechanizm: `/etc/pihole/custom.list` na PIHA (Pi-hole v5.18.4, natywny/systemd
`pihole-FTL`, nie kontener) — runtime, poza GitOps, dokładnie jak reszta
`~15` wpisów w tym pliku. Dodano `192.168.31.5 kb.kapala.org` + `pihole
restartdns`. Zweryfikowane: `dig kb.kapala.org @127.0.0.1` na PIHA i z hosta
LAN (SOLARIA, resolver = Pi-hole) → `192.168.31.5`.

**Rozbieżność z założeniem planu** (STOP, wyjaśnione i zatwierdzone przez
operatora): zadanie zakładało "ten sam mechanizm co istniejące ~15 domen [dla
kapala.org]" — w rzeczywistości tych 15 wpisów to wyłącznie `*.okit.pl`,
**zero** istniejących `kapala.org` w `custom.list`. `paper./ha./immich./
vikunja./forgejo.kapala.org` **nie mają** dziś override'u LAN — `dig` z PIHA i
z 8.8.8.8 zwracał identycznie `100.108.208.3` (Tailscale IP) dla
`paper.kapala.org`, czyli LAN-owy klient robi dziś hairpin przez Tailscale dla
wszystkich istniejących usług `kapala.org`. `kb.kapala.org` jest więc
**pierwszym** split-horizon wpisem dla tej domeny. Mechanizm (plik, komenda)
jest ten sam i poprawnie odtworzony — tylko przesłanka "już tak jest dla 15
domen kapala.org" była błędna. Nie dotykano innych vhostów (poza zakresem) —
retrofit pozostałych `kapala.org` do LAN split-horizon to osobny, potencjalny
follow-up.

### 3. Cloudflare A-record — częściowo poza tą sesją
Brak tokena Cloudflare API w środowisku wykonawczym. Operator dodaje ręcznie:
`kb.kapala.org` → `100.108.208.3` (Tailscale PIHA), DNS only — analogicznie do
`paper./ha./immich./vikunja./forgejo.kapala.org`. Bez tego rekordu
`kb.kapala.org` rozwiązuje się wyłącznie w LAN (Pi-hole); poza LAN (Tailscale)
nie zadziała, dopóki operator nie doda rekordu. Status: **do potwierdzenia
przez operatora**, nie zweryfikowane w tej sesji.

### 4. OIDC — STOP wg instrukcji zadania
Potwierdzone w repo (zgodnie z `05-faza4-plan.md` §1.4): **brak wzorca
forward-auth/reverse-proxy-level auth** — NPM community edition go nie ma
(sprawdzone: brak `oauth2-proxy`/`authelia`/`forward_auth` w kodzie repo poza
wzmiankami "przyszła opcja" w `docs/kb/kb-02-documents-design.md` i
`hosts/vps/README.md`). Wszystkie 3 precedensy (paperless/nextcloud/vikunja)
robią OIDC **wewnątrz aplikacji**. kb-query nie ma dziś żadnego logowania.

Zgodnie z instrukcją zadania: **nie budowano** nowego komponentu auth.
Zaproponowane operatorowi 2 opcje:
1. **Zostaw bez auth na razie** — `authlib` + `/login`/`/auth/callback`
   wbudowane w kb-query (plan §8) to osobna sesja z kodem (~1 sesja szacunku
   planu), poza zakresem tego zadania infra.
2. **Doraźny NPM Access List (Basic Auth)** — wbudowana funkcja NPM (wspólne
   hasło na poziomie vhosta), zero kodu, zero nowego komponentu, ale to nie
   SSO/Forgejo — tylko gate.

**Decyzja operatora (2026-07-23): opcja 1** — `kb.kapala.org` zostaje bez auth
(LAN/Tailscale, jak dziś) do czasu osobnej sesji budującej `authlib` OIDC w
kb-query. Gotcha do pamięci na tamtą sesję (z Vikunja-precedensu): Forgejo
OAuth2 app wymaga **pełnego** redirect URI z kluczem providera
(`.../auth/callback` czy analogiczny, do potwierdzenia przy implementacji) —
niedokładny redirect URI w konfiguracji aplikacji OAuth to najczęstszy błąd
przy pierwszym logowaniu w tym repo (paperless miał podobny problem z
username collision, `docs/sessions/2026-07-10-paperless-deploy.md`).

## Weryfikacja (DoD)

- `curl -I` / `curl -v` przez `--resolve kb.kapala.org:443:192.168.31.5`:
  `HTTP/2 200` na `/healthz`, cert `CN=*.kapala.org`, TLSv1.3, ważny do
  2026-09-28.
- `/search?q=test` przez vhost vs bezpośrednio na `192.168.31.5:8230`:
  **identyczny** `envelope_id`/`dist`/`chunk_index`/`text` (ten sam kod, HTTP
  to tylko opakowanie — zgodnie z kryterium bramki §9 planu, choć to nie jest
  jeszcze formalny `retrieval_eval.py --transport http`, tylko ręczny
  smoke-test tej sesji).
- Rozwiązywanie `kb.kapala.org` z hosta LAN (SOLARIA, resolver = Pi-hole) →
  `192.168.31.5`, potwierdzone `dig`/`getent hosts`.
- Auth: brak (zgodnie z decyzją) — nic nie powinno wymagać logowania, i nic
  nie wymaga (potwierdzone: `/search` i `/healthz` odpowiadają bez tokenu).

## Stan na koniec sesji

| Element | Status |
|---|---|
| npm@PIHA vhost #35 kb.kapala.org → 192.168.31.5:8230, cert 49 | ✅ LIVE |
| Pi-hole custom.list kb.kapala.org → 192.168.31.5 | ✅ LIVE (pierwszy kapala.org wpis) |
| Cloudflare A kb.kapala.org → 100.108.208.3 | ⏳ operator, ręcznie, nie zweryfikowane |
| OIDC | ⛔ świadomie odłożone — osobna sesja z kodem |

## Pliki repo zmienione

- `services/kb-query/README.md` — sekcja "Ingress" (co żyje, co nie, dlaczego
  auth odłożone) zastępuje starą notatkę "not wired up yet".
- `docs/sessions/2026-07-23-kb-f4-ingress.md` — ten dokument.

## Follow-upy (propozycje, nie w zakresie tej sesji)

- Retrofit Pi-hole split-horizon dla `paper./ha./immich./vikunja./
  forgejo.kapala.org` (dziś wszystkie hairpinują przez Tailscale nawet z LAN)
  — drobny, ale osobny task, nie dotykać przy okazji.
- `authlib` OIDC w kb-query (plan §8) — osobna sesja z kodem.
- `retrieval_eval.py --transport http` (plan §6 Decyzja 6, formalna bramka
  HTTP-equivalence) — dziś tylko ręczny smoke-test, nie automat.