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

okf	type	visibility	status	updated	links
0.1	session-log	private	active	2026-07-23

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.