# Sesja 2026-07-10 — Deploy 1 Paperless (DZIALA) + swap PIHA + npm-API tool w akcji

## Glowne osiagniecie: Paperless serwis LIVE
paper.kapala.org dziala end-to-end. Pierwszy filar dokumentow KB stoi i przetwarza.
Zweryfikowane: 1 dokument (polisa PDF) przetworzony, OCR wyciagnal 23607 znakow.

## Narzedzie npm-API (zbudowane + uzyte w boju)
- scripts/npm/npm_api.py (Python stdlib, zero-dep): token, list-hosts, list-certs,
  set-cert, create-host. Dry-run domyslny, --apply dla realnej zmiany.
- Zweryfikowane na zywo (list-certs PIHA dzialalo). UZYTE do utworzenia vhostu
  paper.kapala.org (proxy host #33) — API samo regeneruje conf+reload, koniec z
  bulk-SQL+sed z 2026-07-07.
- .env npm musi byc w GLOWNYM repo (nie worktree — usuwany przy merge). Gitignored.
- Backlog: npm@VPS admin :81 publicznie osiagalny (0.0.0.0) — ograniczyc do mesh.

## Swap PIHA 4->8Gi (bufor RAM pod KB)
- RAM ciasny (avail 3.3Gi, immich 1Gi 24/7, prom lokalny 595Mi, npm 300Mi).
- Prometheus: SA DWA i to OK — fleet na VPS (mesh: piha/lustro/vps), lokalny na PIHA
  (dom: HA/zigbee/security). Nie duplikat, nie ruszac.
- Swap: ext4 /swapfile, powiekszony fallocate 8G (dphys 200MB nieistotny). W fstab
  (reboot-safe, usunieto duplikat wpisu).
- Kierunek dlugoterminowy (backlog): wymiana RPi na maszyne jak CHELSTY -> Proxmox.

## Deploy 1 kroki (dla powtorzenia przy kolejnych serwisach)
1. Pull repo na PIHA (deploy-only master). 2. .env sekrety (openssl rand haslad,
   OAuth z Forgejo) — przez nano (heredok rozjezdza dluga linie JSON OIDC!).
3. OAuth app Forgejo (redirect .../accounts/oidc/forgejo/login/callback/).
4. mkdir /opt/homelab/data/paperless/{data,media,consume,export} + chown 1004:1004
   (uid oskara=1004, NIE 1000! config zakladal 1000 — rozjazd, naprawione chownem).
5. docker compose up -d (web+db+broker, redis requirepass dziala).
6. vhost przez npm_api.py create-host --cert-id 49 (*.kapala.org).
7. A-record paper.kapala.org -> 100.108.208.3 (Cloudflare DNS-only, mesh).

## LEKCJE (wazne)
- Bootstrap admin (PAPERLESS_ADMIN_USER/PASS) tworzy sie TYLKO przy pierwszym starcie
  z pusta baza. Po restartach nie dziala. RESET: docker exec paperless python3
  manage.py shell -c "User.objects.get(username='oskar').set_password('...')".
- OIDC pierwszy login: domyslnie Paperless NIE auto-tworzy kont. Dodano do .env:
  PAPERLESS_ACCOUNT_ALLOW_SIGNUPS=true, SOCIALACCOUNT_ALLOW_SIGNUPS=true,
  SOCIAL_AUTO_SIGNUP=true, ACCOUNT_EMAIL_VERIFICATION=none.
- Username collision: lokalny admin oskar vs OIDC oskar -> "user exists". FIX: zaloguj
  lokalnym adminem, potem POLACZ konto przez profil (Edytuj profil -> Podlacz Forgejo,
  URL /accounts/oidc/forgejo/login/?process=connect). Connect laczy z istniejacym userem.
- Paperless leci jako root wewnatrz kontenera (USERMAP mapuje zapis na host UID) — OK.

## Stan koncowy
Paperless: 3 kontenery healthy, OCR dziala, OIDC login (haslo LUB Forgejo) dziala.
Config w repo, sekrety w .env gitignored. Storage /opt/homelab/data/paperless.

## TODO nastepne sesje
- Deploy 2: NFS (apt install nfs-kernel-server na PIHA — BRAK teraz) + OCR-worker na
  SOLARIA. WAZNE: zrobic PRZED masowym importem (wbudowany worker concurrency=1 wolny).
- Google Takeout: zamowic selektywnie (Drive/dokumenty, nie cale konto), rozpakowac ->
  consume. DOPIERO po Deploy 2 (masowy OCR na workerze SOLARIA).
- Deploy 3: Nextcloud (PIHA, always-on). Deploy 4: Gokapi (VPS).
- Drobne: email oskara root@localhost -> prawdziwy; PAPERLESS_DISABLE_REGULAR_LOGIN
  po pewnym OIDC.