From 07a0fe097b471021f67285449443e7cee2327251 Mon Sep 17 00:00:00 2001
From: oskar <oskar@kapalla.org>
Date: Fri, 10 Jul 2026 18:29:10 +0200
Subject: [PATCH] docs(sesja): 2026-07-10 Deploy 1 Paperless LIVE (OCR+OIDC
 dziala) + swap PIHA 8Gi + npm-API w akcji + lekcje

---
 docs/sessions/2026-07-10-paperless-deploy.md | 57 ++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 docs/sessions/2026-07-10-paperless-deploy.md

diff --git a/docs/sessions/2026-07-10-paperless-deploy.md b/docs/sessions/2026-07-10-paperless-deploy.md
new file mode 100644
index 0000000..de0ed23
--- /dev/null
+++ b/docs/sessions/2026-07-10-paperless-deploy.md
@@ -0,0 +1,57 @@
+# 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.