2026-08-04 14:56:25 +02:00
|
|
|
---
|
|
|
|
|
okf: "0.1"
|
|
|
|
|
type: session-log
|
|
|
|
|
visibility: private
|
|
|
|
|
status: active
|
|
|
|
|
updated: 2026-07-23
|
|
|
|
|
links: []
|
|
|
|
|
---
|
|
|
|
|
|
2026-07-23 18:27:51 +02:00
|
|
|
# Sesja 2026-07-23 — KB faza 4: ingress kb.kapala.org (krok 5/§8)
|
|
|
|
|
|
fix(kb): przepiecie wszystkich odwolan wewnetrznych po migracji
126 plikow (md, yaml, sh, py) odwolywalo sie do sciezek sprzed migracji.
15 markdown-linkow [..](..) -> policzona sciezka WZGLEDNA wobec pliku
odsylajacego (wczesniej czesc z nich byla repo-root-relative i nie
rozwiazywala sie z katalogu, w ktorym lezala)
200 odwolan tekstowych (backticki, proza, yaml, importy w kodzie)
-> nowa sciezka repo-root-relative, zgodnie z konwencja repo
5 linkow rodzenstwa (gole nazwy plikow, np. "](DEPLOY.md)") — dzialaly
tylko w starym katalogu; przeliczone recznie
Objete m.in.: CLAUDE.md (scripts/onboard/README.md -> kb/runbooks/
node-onboarding-tool.md, docs/backlog.md -> kb/phases/backlog.md),
README.md, .claude/skills/, 20 session logow, kod jobow.
Ostatnie 5 odwolan pochodzi z tresci wciagnietej rebasem z origin/master
(session log 2026-07-31, override node-agenta na SOLARII, dwie pozycje
backlogu) — wskazywaly na docs/incidents/, docs/kb/modules/ i
services/narty27/README.md sprzed migracji.
Dodany wzajemny link miedzy kb/services/control-plane.md (stub kodu)
a kb/subsystems/control-plane.md (opis, deprecated) — dwa dokumenty o tym
samym systemie, latwe do pomylenia.
Weryfikacja na 790 plikach: 0 odwolan do starych sciezek,
0 martwych linkow markdown. Lint OKF: 190/190 plikow ZGODNE.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 15:12:24 +02:00
|
|
|
**Zakres**: wyłącznie ingress (`kb/phases/kb-m5-faza4.md` §8, krok 5) —
|
2026-07-23 18:27:51 +02:00
|
|
|
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.
|
|
|
|
|
|
2026-07-23 18:37:11 +02:00
|
|
|
### 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.
|
2026-07-23 18:27:51 +02:00
|
|
|
|
|
|
|
|
### 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
|
fix(kb): przepiecie wszystkich odwolan wewnetrznych po migracji
126 plikow (md, yaml, sh, py) odwolywalo sie do sciezek sprzed migracji.
15 markdown-linkow [..](..) -> policzona sciezka WZGLEDNA wobec pliku
odsylajacego (wczesniej czesc z nich byla repo-root-relative i nie
rozwiazywala sie z katalogu, w ktorym lezala)
200 odwolan tekstowych (backticki, proza, yaml, importy w kodzie)
-> nowa sciezka repo-root-relative, zgodnie z konwencja repo
5 linkow rodzenstwa (gole nazwy plikow, np. "](DEPLOY.md)") — dzialaly
tylko w starym katalogu; przeliczone recznie
Objete m.in.: CLAUDE.md (scripts/onboard/README.md -> kb/runbooks/
node-onboarding-tool.md, docs/backlog.md -> kb/phases/backlog.md),
README.md, .claude/skills/, 20 session logow, kod jobow.
Ostatnie 5 odwolan pochodzi z tresci wciagnietej rebasem z origin/master
(session log 2026-07-31, override node-agenta na SOLARII, dwie pozycje
backlogu) — wskazywaly na docs/incidents/, docs/kb/modules/ i
services/narty27/README.md sprzed migracji.
Dodany wzajemny link miedzy kb/services/control-plane.md (stub kodu)
a kb/subsystems/control-plane.md (opis, deprecated) — dwa dokumenty o tym
samym systemie, latwe do pomylenia.
Weryfikacja na 790 plikach: 0 odwolan do starych sciezek,
0 martwych linkow markdown. Lint OKF: 190/190 plikow ZGODNE.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 15:12:24 +02:00
|
|
|
wzmiankami "przyszła opcja" w `kb/subsystems/kb-documents-pillar.md` i
|
|
|
|
|
`kb/nodes/vps.md`). Wszystkie 3 precedensy (paperless/nextcloud/vikunja)
|
2026-07-23 18:27:51 +02:00
|
|
|
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`.
|
2026-07-23 18:37:11 +02:00
|
|
|
- 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`.
|
2026-07-23 18:27:51 +02:00
|
|
|
- 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) |
|
2026-07-23 18:37:11 +02:00
|
|
|
| Cloudflare A kb.kapala.org → 100.108.208.3 | ✅ LIVE (dodany przez operatora, zweryfikowany) |
|
2026-07-23 18:27:51 +02:00
|
|
|
| OIDC | ⛔ świadomie odłożone — osobna sesja z kodem |
|
|
|
|
|
|
|
|
|
|
## Pliki repo zmienione
|
|
|
|
|
|
fix(kb): przepiecie wszystkich odwolan wewnetrznych po migracji
126 plikow (md, yaml, sh, py) odwolywalo sie do sciezek sprzed migracji.
15 markdown-linkow [..](..) -> policzona sciezka WZGLEDNA wobec pliku
odsylajacego (wczesniej czesc z nich byla repo-root-relative i nie
rozwiazywala sie z katalogu, w ktorym lezala)
200 odwolan tekstowych (backticki, proza, yaml, importy w kodzie)
-> nowa sciezka repo-root-relative, zgodnie z konwencja repo
5 linkow rodzenstwa (gole nazwy plikow, np. "](DEPLOY.md)") — dzialaly
tylko w starym katalogu; przeliczone recznie
Objete m.in.: CLAUDE.md (scripts/onboard/README.md -> kb/runbooks/
node-onboarding-tool.md, docs/backlog.md -> kb/phases/backlog.md),
README.md, .claude/skills/, 20 session logow, kod jobow.
Ostatnie 5 odwolan pochodzi z tresci wciagnietej rebasem z origin/master
(session log 2026-07-31, override node-agenta na SOLARII, dwie pozycje
backlogu) — wskazywaly na docs/incidents/, docs/kb/modules/ i
services/narty27/README.md sprzed migracji.
Dodany wzajemny link miedzy kb/services/control-plane.md (stub kodu)
a kb/subsystems/control-plane.md (opis, deprecated) — dwa dokumenty o tym
samym systemie, latwe do pomylenia.
Weryfikacja na 790 plikach: 0 odwolan do starych sciezek,
0 martwych linkow markdown. Lint OKF: 190/190 plikow ZGODNE.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 15:12:24 +02:00
|
|
|
- `kb/services/kb-query.md` — sekcja "Ingress" (co żyje, co nie, dlaczego
|
2026-07-23 18:27:51 +02:00
|
|
|
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.
|