--- okf: "0.1" type: runbook visibility: private status: active updated: 2026-08-05 links: - ../services/kb-site.md - ./npm-api.md - ../phases/okit-cloudflare.md --- # kb-site — deploy, publikacja treści, ingress (kb-e2a24af3.okit.pl) Serwis: `services/kb-site/` (nginx:alpine na PIHA, host port **8250**). Generator: `scripts/kb/gen_pages.py`. Publiczny adres: `https://kb-e2a24af3.okit.pl`. Kolejność ma znaczenie: **DNS → NPM host → cert**. Certyfikat Let's Encrypt leci challenge'em HTTP-01, więc rekord A musi już wskazywać na łącze domowe, a vhost musi już odpowiadać na porcie 80, zanim zamówisz cert. --- ## 0. Wymagania wstępne - PIHA ma checkout repo w `~/homelab-codex-ws` i działającego Dockera. - npm@PIHA działa (`http://192.168.31.5:81`), port 80/443 z routera jest przekierowany na PIHA — tak samo jak dla `vikunja.okit.pl`. - `scripts/npm/.env` wypełniony poświadczeniami (patrz `kb/runbooks/npm-api.md`). - Strefa `okit.pl` w Cloudflare (patrz `kb/phases/okit-cloudflare.md`). - **Token bramki dostępny na węźle, z którego generujesz** (SATURN/SOLARIA — nie na PIHA): plik `/opt/homelab/config/kb-site/.env` z jedną linią `ACCESS_TOKEN=`, `chmod 600`. To wyjątek od konwencji z CLAUDE.md: `config//` trzyma zwykle sekrety węzła, który serwis *uruchamia*, a ten token jest potrzebny tam, gdzie serwis się *generuje*. Kontener nginx na PIHA nadal nie ma żadnej konfiguracji ani sekretów. Wartość to ten sam token, co w advanced config proxy hosta w NPM. Żyje wyłącznie w bazie NPM i w tym pliku — **nigdy w repo**. --- ## 1. Deploy serwisu na PIHA ```bash # na PIHA cd ~/homelab-codex-ws git pull docker compose -f services/kb-site/docker-compose.yml up -d ``` Bez `.env` i bez override'a — serwis nie ma konfiguracji ani sekretów. Kontener wstanie, ale healthcheck będzie **unhealthy do czasu wgrania treści** (pusty wolumen = brak `index.html`). To normalne między krokiem 1 a 3. ```bash docker ps --filter name=kb-site docker volume ls | grep kb-site # kb-site_kb-site_content ``` --- ## 2-3. Generacja, kontrola wycieków, wgranie treści (SATURN / SOLARIA) Kroki 2-4 (generacja → `--check` → upload przez helper alpine → smoke test) robi jeden skrypt: ```bash bash scripts/kb/publish.sh ``` Zobacz kod (`scripts/kb/publish.sh`) dla dokładnej kolejności komend. Poniżej zostaje wyjaśnienie **co** skrypt robi i **dlaczego** — nie trzeba już klikać kroków ręcznie, ale bramki i uzasadnienia poniżej wciąż obowiązują. Uruchamiamy w checkoucie repo, na węźle z którego pracujesz — nie na PIHA. Docelowy host PIHA jest parametrem na górze skryptu (zmienna `PIHA_HOST`, domyślnie `piha.local`). Skrypt jest fail-closed na każdym etapie: brak/pusty `ACCESS_TOKEN`, `--check` z exit 1, albo 0 wystąpień `key=` w wygenerowanym `index.html` — każde z tych zatrzymuje publikację przed dotknięciem PIHA. ### Token w linkach Generator czyta `ACCESS_TOKEN` ze środowiska i dopisuje `?key=` do **każdego linku wewnętrznego** (karty na spisie, linki między dokumentami, powrót „All documents"). Bez tego bramka NPM odbija 403 przy każdym kliknięciu i działa wyłącznie ręcznie sklejony URL — strona jest wtedy technicznie żywa, ale nie da się po niej chodzić. Token podajemy zmienną środowiskową, nie flagą `--access-token`: argument z linii poleceń ląduje w historii shella i jest widoczny w `ps` dla każdego użytkownika węzła. Flaga istnieje do jednorazowych generacji testowych. Sanity check tuż po generacji — `Token: TAK` w wyjściu generatora, a w HTML: ```bash grep -c 'key=' build/kb-site/index.html # > 0; 0 = build bez tokenu ``` Generacja bez tokenu **nie jest błędem** — to tryb lokalnego podglądu (`build/` do przejrzenia w przeglądarce, bez publikacji). Nie wolno jej tylko wgrać na PIHA. Token nie jest sekretem chroniącym treść — jest zaporą przed przypadkowym trafieniem. Po tej zmianie siedzi w treści każdej serwowanej strony, więc jedna zapisana strona wydaje go w całości. To nie zmienia modelu zagrożeń (URL wejściowy zawsze go niósł), ale przesądza, że bramką prywatności jest `--check` i pole `visibility`, nie ten token. ### Kontrola wycieków `--check` skanuje **wygenerowany HTML**, nie źródła: adresy IP (RFC1918, Tailscale 100.64/10, publiczne v4/v6), porty 1024-65535, ścieżki `/home/` i `/opt/`, długie hexy i ciągi base64 wyglądające na tokeny. **Kontrola jest bramką publikacji — nie kopiuj treści na PIHA przy exit 1.** Stan na 2026-08-04 (11 dokumentów public): **exit 0 — czysto, 22 trafienia wyciszone whitelistą.** Wszystkie wyciszone to `path-host` `/opt/homelab/...` w dokumentach opisujących layout runtime (`subsystems/observer`, `subsystems/standards`, `subsystems/service-model`, `subsystems/event-system`, `subsystems/agent-operating-procedures`, `subsystems/action-approval-model`, `runbooks/node-onboarding`). Zero IP, zero portów, zero tokenów. Decyzja operatora 2026-08-04: `/opt/homelab` jest świadomym wyjątkiem — standardowa ścieżka deploy rootu, ta sama na każdym węźle, nie ujawnia sekretów ani topologii. Wpis siedzi w `scripts/kb/check_whitelist.txt` razem z uzasadnieniem. Wycisza wyłącznie warianty `/opt/homelab/...`; `/home/...`, adresy, porty i tokeny dalej zapalają czerwone. Każdy kolejny wyjątek podlega tej samej regule: najpierw próba wyczyszczenia źródła, wpis do whitelisty dopiero jako świadoma decyzja, zawsze z komentarzem i datą. ### Wgranie treści do wolumenu (helper alpine) Wzorzec z `services/narty27/README.md`, rozszerzony z jednego pliku na drzewo: `docker cp` nie zapisze do montowania `:ro`, więc treść wjeżdża jednorazowym kontenerem pomocniczym, który montuje wolumen zapisywalnie. `publish.sh` robi dokładnie to: pakuje `build/kb-site` do tarballa, `scp` na PIHA, i podmienia wolumen przez ten sam wzorzec helpera co niżej. `rm -rf /content/*` przed rozpakowaniem jest **obowiązkowe**: bez tego strona dokumentu przełączonego z `public` na `private` zostałaby w wolumenie i dalej serwowała treść, której już nie publikujemy. Publikacja jest podmianą całości, nie dogrywaniem plików. Skrypt kończy smoke testem (`ssh $PIHA_HOST curl -s localhost:8250`) — jeśli chcesz dodatkowej weryfikacji z samej PIHA: ```bash services/kb-site/healthcheck.sh curl -sI http://192.168.31.5:8250/index.html | head -1 ``` --- ## 4. Cloudflare — rekord A ``` Type: A Name: kb-e2a24af3 Content: # ten sam, co ma vikunja.okit.pl Proxy: DNS only (szara chmurka) TTL: Auto ``` Docelowy IP weź z istniejącego rekordu `vikunja` w tej samej strefie zamiast wpisywać z pamięci — łącze domowe potrafi zmienić adres. **DNS only, nie proxied**: challenge HTTP-01 w kroku 5 musi trafić na nginx, a nie na krawędź Cloudflare. Włączenie proxy to osobna decyzja, po tym jak cert już działa. Split-horizon (patrz `kb/phases/okit-cloudflare.md`): w Pi-hole na PIHA dodaj Local DNS Record `kb-e2a24af3.okit.pl → 192.168.31.5`, żeby klienci w LAN szli prosto do npm, a nie przez hairpin NAT na routerze. Sprawdzenie propagacji (z hosta poza LAN albo przez publiczny resolver): ```bash dig +short kb-e2a24af3.okit.pl @1.1.1.1 ``` --- ## 5. NPM — proxy host + certyfikat Wszystkie komendy `npm_api.py` są **dry-run domyślnie**; realna zmiana dopiero z `--apply`. Puść najpierw bez `--apply` i przeczytaj payload. ```bash # 5a. host: kb-e2a24af3.okit.pl -> PIHA:8250 python3 scripts/npm/npm_api.py --npm piha create-host \ --domain kb-e2a24af3.okit.pl \ --forward-host 192.168.31.5 --forward-port 8250 \ --block-exploits --http2-support # ...i to samo z --apply # 5b. cert Let's Encrypt (HTTP-01 — wymaga działającego kroku 4 i 5a) python3 scripts/npm/npm_api.py --npm piha create-cert --domain kb-e2a24af3.okit.pl --apply # 5c. podepnij cert pod host i wymuś HTTPS python3 scripts/npm/npm_api.py --npm piha list-hosts # weź HOST_ID python3 scripts/npm/npm_api.py --npm piha list-certs # weź CERT_ID python3 scripts/npm/npm_api.py --npm piha set-cert HOST_ID CERT_ID --ssl-forced --apply ``` Jeśli w npm@PIHA istnieje już wildcard `*.okit.pl` (faza 1 z `kb/phases/okit-cloudflare.md`), pomiń 5b i w 5c podepnij jego `CERT_ID` — jeden cert DNS-01 zamiast kolejnego per-host HTTP-01. Diagnostyka nieudanego certu: `ssh piha 'docker logs npm --tail 100'` — NPM zwraca wyjście certbota w treści błędu, a przy porażce challenge'u kasuje wiersz certyfikatu (szczegóły w `kb/runbooks/npm-api.md`). --- ## 6. Weryfikacja końcowa ```bash set -a; . /opt/homelab/config/kb-site/.env; set +a BASE=https://kb-e2a24af3.okit.pl curl -sI "$BASE/?key=$ACCESS_TOKEN" | head -1 # 200 curl -s "$BASE/?key=$ACCESS_TOKEN" | grep -c 'class="cards"' # spis jest curl -s "$BASE/subsystems/observer.html?key=$ACCESS_TOKEN" | tail -5 # stopka: data + commit # bramka faktycznie broni — bez tokenu ma NIE być 200 curl -sI "$BASE/" | head -1 # przejście po linku ze spisu, tak jak zrobi to przeglądarka: # wyciągnij pierwszy href z indexu i pobierz go bez dopisywania niczego ręcznie LINK=$(curl -s "$BASE/?key=$ACCESS_TOKEN" \ | grep -o 'href="[^"]*key=[^"]*"' | head -1 | cut -d'"' -f2) curl -sI "$BASE/$LINK" | head -1 # 200 ``` Ostatni test jest właściwą weryfikacją tej bramki: sprawdza, że link *wygenerowany przez generator* przechodzi przez NPM, a nie że ręcznie sklejony URL działa. W przeglądarce: `https://kb-e2a24af3.okit.pl/?key=` — spis pogrupowany per type, kłódka bez ostrzeżeń, wejście w dowolną kartę **kliknięciem** (nie przez pasek adresu), powrót linkiem „All documents", i z powrotem w inną kartę. Kontrola treści (ręczna, jednorazowa po pierwszej publikacji): przejrzyj spis i potwierdź, że nie ma tam nic, czego nie chcesz mieć w internecie. Generator pilnuje pola `visibility`, ale to człowiek decyduje, co dostaje `public`. --- ## 7. Rutynowa aktualizacja treści Po każdej zmianie w `kb/**/*.md`, która dotyczy dokumentów `public`: ```bash bash scripts/kb/publish.sh ``` To ten sam skrypt co w krokach 2-3 — rutynowa aktualizacja to po prostu ponowne uruchomienie całej publikacji. Bramki (`ACCESS_TOKEN` pusty, `--check` exit 1, brak `key=` w spisie) zatrzymują ją przed dotknięciem PIHA przy każdym uruchomieniu, nie tylko przy pierwszym. Kontener nie wymaga restartu — nginx czyta wolumen na bieżąco. --- ## 8. Rollback i typowe problemy | Objaw | Przyczyna | Reakcja | |---|---|---| | healthcheck unhealthy, 404 na `/` | pusty wolumen — treść nigdy nie wjechała | krok 3 | | stara strona po publikacji | pominięte `rm -rf /content/*` | powtórz krok 3 w całości | | dokument nie pojawia się na stronie | brak `visibility: public` albo niepoprawny frontmatter (fail-closed) | `python3 scripts/kb/check_okf.py`, potem regeneracja | | link renderuje się jako tekst z `[private]` | cel jest prywatny albo nie istnieje | tak ma być — to nie błąd | | index otwiera się z tokenem, ale **kliknięcie w kartę daje 403** | build wygenerowany bez `ACCESS_TOKEN` — linki nie niosą `?key=` | ustaw token (krok 0) i powtórz kroki 2-3; `grep -c 'key=' build/kb-site/index.html` | | 403 także na URL z tokenem | token w NPM został wymieniony i rozjechał się z `/opt/homelab/config/kb-site/.env` | zsynchronizuj plik z advanced config w NPM, przegeneruj i opublikuj — stary build zostaje z martwym tokenem w każdym linku | | `--check` zapala nowe trafienie | do dokumentu `public` wjechał adres/ścieżka/token | popraw źródło; whitelist tylko świadomie | | cert nie schodzi | rekord A nie propagował, proxy Cloudflare włączone, albo port 80 niedostępny | krok 4, potem 5b ponownie | Awaryjne wygaszenie wystawki (bez ruszania NPM i DNS): ```bash ssh piha 'cd ~/homelab-codex-ws && docker compose -f services/kb-site/docker-compose.yml down' ``` Wolumen zostaje; `up -d` przywraca stan sprzed. Pełne odtworzenie od zera to kroki 1-3 — treść jest artefaktem repo, nie danymi.