---
okf: "0.1"
type: session-log
visibility: private
status: active
updated: 2026-07-23
links: []
---

# 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
Brak tokena Cloudflare API w środowisku wykonawczym — operator dodał ręcznie
przez dashboard: `kb.kapala.org` → `100.108.208.3` (Tailscale PIHA), DNS only,
analogicznie do `paper./ha./immich./vikunja./forgejo.kapala.org`. Zweryfikowane
w tej samej sesji, osobnym przebiegiem po zgłoszeniu przez operatora:
- Pierwsza próba (`dig @8.8.8.8`/`@1.1.1.1`) — pusta odpowiedź, `dig
  @dom.ns.cloudflare.com` (autorytatywny NS strefy) zwracał SOA/NXDOMAIN dla
  `kb.kapala.org`, podczas gdy `paper.kapala.org` na tym samym serwerze
  odpowiadał poprawnie — **nie opóźnienie propagacji, rekord faktycznie
  jeszcze nie istniał** w strefie w momencie pierwszej weryfikacji.
- Operator poprawił/dokończył zapis w dashboardzie; ponowny `dig` (ten sam
  autorytatywny NS + 8.8.8.8 + 1.1.1.1) → `100.108.208.3`, TTL 300, zgodne z
  pozostałymi `kapala.org`. `curl https://kb.kapala.org/healthz` → `200`,
  cert `*.kapala.org` ważny, treść zgodna.
- Pi-hole split-horizon (LAN → `192.168.31.5`) niezmieniony, zweryfikowany
  ponownie po zmianie w CF — obie warstwy działają niezależnie, jak
  zaprojektowano.

### 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`.
- Rozwiązywanie `kb.kapala.org` z publicznych resolverów (8.8.8.8, 1.1.1.1) i
  z autorytatywnego NS strefy (`dom.ns.cloudflare.com`) → `100.108.208.3`,
  TTL 300 — zweryfikowane po dodaniu rekordu przez operatora, `curl` przez tę
  ścieżkę → `200`.
- 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 | ✅ LIVE (dodany przez operatora, zweryfikowany) |
| 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.
