homelab-codex-ws/kb/decisions/kb-dokumenty-otwarte.md

---
okf: "0.1"
type: decision
visibility: private
status: planned
updated: 2026-07-09
links: []
---

# Decyzje do podjęcia — filar dokumentów (moduły 2/3/4)

> Zbiorcza lista decyzji z przygotowania configów (2026-07-06, branch
> `task/paperless-nextcloud-config`; decyzje podjęte 2026-07-09, branch
> `task/paperless-decyzje`). Configi są zaktualizowane wg decyzji poniżej —
> NIC nie zostało zdeployowane, ten etap to tylko edycja plików w repo.

## Otwarte — do zrobienia PRZY DEPLOYU (nie są to już decyzje, tylko kroki wykonawcze)

### 3. Porty (potwierdzić na żywym PIHA przed deployem)

Dobrane wg inwentaryzacji 2026-06-30 (snapshot! zweryfikować `ss -tlnp`):

| Port | Serwis | Uwagi |
|---|---|---|
| 8210 | paperless web | za npm@PIHA |
| 5434 | paperless postgres | 5433 zajęte przez kb-postgres |
| 6380 | paperless redis (broker dla workera) | 6379 zajęte przez agent-system-redis |
| 8220 | nextcloud web | teraz na PIHA (decyzja #1) — potwierdzić że nadal wolny |

Wszystkie bindowane na LAN IP (nie 0.0.0.0); ruch worker↔broker/DB/NFS po
LAN 192.168.31.x, nie Tailscale.

### 7. Wyłączenie lokalnego loginu w Paperless po weryfikacji OIDC

Bootstrap idzie przez lokalnego admina (`PAPERLESS_ADMIN_USER`). Po
potwierdzeniu działania Forgejo-OIDC: ustawić
`PAPERLESS_DISABLE_REGULAR_LOGIN=true` + `PAPERLESS_REDIRECT_LOGIN_TO_SSO=true`
(decyzja podjęta — wykonać dopiero po potwierdzonym logowaniu OIDC; Vikunja
ma dziś oba tryby równolegle, ten sam wzorzec przejściowy).

### 9. Sizing workera OCR pod batch 70k załączników

`WORKER_CONCURRENCY=4` × `PAPERLESS_THREADS_PER_WORKER=4` = ~16 wątków na
24 rdzeniach SOLARII. Przed batchem 70k (moduł 5): zmierzyć na próbce i
zdecydować, czy podbić concurrency, czy zostawić zapas na ollama/AI.

---

## Rozstrzygnięte

- **1. Host Nextclouda: PIHA.** Oskar używa Nextclouda aktywnie (telefon,
  sync, rodzina) → musi być always-on; sesyjna dostępność SOLARII (sync
  dogania się dopiero po wybudzeniu) nie jest akceptowalna dla tego
  workloadu — mimo że moduł 4/kb-02 skłaniały się ku SOLARII (KB i tak
  czyta własną kopię z archiwum na PIHA, więc host Nextclouda nie warunkuje
  zapytań KB). `service.yaml`: `owner_node: piha`. `.env`: `LAN_BIND_IP`
  = 192.168.31.5, `TRUSTED_PROXIES` = docker bridge subnet (npm i nextcloud
  na tym samym hoście teraz). Uzasadnienie pełne: `services/nextcloud/README.md`.

- **2. Backup Paperlessa: SOLARIA (LAN), na start.** Nocny
  `document_exporter` (oryginały + archiwa + manifest, odtwarzalny bez
  dumpa SQL) → `/opt/homelab/data/paperless/export`, kopia poza hosta przez
  rsync/borg → SOLARIA (2 TB, ta sama LAN). Retencja: 7 dziennych +
  4 tygodniowe + 6 miesięcznych. Offsite (np. restic → chmura) zostaje jako
  future-note, poza zakresem tego etapu. Cron/skrypt deployowy powstaje przy
  deployu modułu 2, nie teraz. Szczegóły: `services/paperless/README.md`.

- **4. Redis brokera: `requirepass`.** Broker (6380) dostaje hasło —
  `PAPERLESS_REDIS_PASSWORD` w `.env` po obu stronach (paperless@PIHA,
  paperless-worker@SOLARIA), placeholder `CHANGEME` w `env.example`, realne
  hasło tylko w `.env` (gitignored). Healthchecki obu stron zaktualizowane
  o auth.

- **5. Fallback-worker na PIHA a indeks Whoosh po NFS: zaakceptować
  i obserwować.** Ryzyko wyścigu na plikowym indeksie Whoosh (PIHA lokalnie
  + SOLARIA po NFS) świadomie zaakceptowane — indeks jest odtwarzalny
  (`document_index reindex`), oryginałom nic nie grozi. Bez zmian w
  configu; fallback-worker na PIHA zostaje. Szczegóły:
  `services/paperless-worker/README.md`.

- **6. Domeny: `kapala.org` (mesh, prywatne).** `paper.kapala.org`
  (Paperless), `cloud.kapala.org` (Nextcloud) — potwierdzone, `*.okit.pl`
  odrzucone. DNS i vhosty NIE utworzone w tym etapie — tylko
  udokumentowane w READMY serwisów (wzorzec: rekord A w Cloudflare →
  `100.108.208.3`, Tailscale PIHA, DNS Only, ten sam co
  `ha.kapala.org`/`immich.kapala.org` — `docs/sessions/2026-06-30-kapala-cloudflare-wildcard-mesh.md`;
  wildcard `*.kapala.org` już pokrywa obie subdomeny, nowe certy
  niepotrzebne). OAuth redirect URIs w Forgejo apps zapisane w READMY obu
  serwisów.

- **8. Pin wersji Nextclouda: `34-apache`.** Zweryfikowany aktualny stable
  na 2026-07-09 (wydany 2026-06-09, endoflife.date/nextcloud). Zamiast
  ruchomego `stable-apache`. Nextcloud wydaje nowy major co ~4 miesiące
  i nie wspiera przeskakiwania wersji przy upgrade — TODO przy deployu:
  potwierdzić bieżący stable tuż przed `docker compose up`, podbić tag
  jeśli wyszła nowsza wersja.

- **Split-host OCR-worker przez NFS: WYKONALNY** — wzorzec potwierdzony przez
  maintainerów paperless-ngx (nieoficjalnie wspierany): ten sam obraz,
  `command: celery --app paperless worker`, wspólny Redis+Postgres+storage,
  identyczne ścieżki kontenerowe i numeryczny UID po obu stronach. Pełny
  wynik badania + ryzyka: `services/paperless-worker/README.md`.
- Storage dokumentów na PIHA; NFS export → SOLARIA po LAN
  (192.168.31.5 → 192.168.31.70), nie Tailscale.
- AOF w Redis brokera (kolejka przeżywa restart — zero utraty zadań).
- OIDC: Paperless przez `django-allauth openid_connect` (env),
  Nextcloud przez appkę `user_oidc` (kroki `occ` w README).
- Limity RAM na PIHA: `hosts/piha/runtime/paperless/docker-compose.override.yml`
  (stack ≤ ~1.9 Gi worst-case).