oskar/homelab-codex-ws
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
homelab-codex-ws/docs/sessions/2026-07-23-kb-f4-ingress.md
oskar fbe81f9bf5 docs(kb-query): ingress kb.kapala.org live — npm vhost + Pi-hole DNS, OIDC deferred 
Runtime steps (not in Git, logged here): npm@PIHA proxy host #35
(kb.kapala.org -> 192.168.31.5:8230, cert #49 *.kapala.org wildcard, same
pattern as paper./vikunja.kapala.org); Pi-hole custom.list split-horizon
entry added and verified (first kapala.org entry in that file — the other
kapala.org vhosts turned out to have no LAN override at all, a plan
assumption that didn't hold). Cloudflare A-record left for the operator (no
API token available here). OIDC intentionally not built: confirmed no
forward-auth pattern exists anywhere in this repo, and building authlib
OIDC into kb-query is real service code out of scope for an infra-only
task — operator decided to leave kb.kapala.org without auth for now.
2026-07-23 18:38:34 +02:00

6.2 KiB
Raw Blame History

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.