---
okf: "0.1"
type: phase
visibility: private
status: active
updated: 2026-07-01
links: []
---

# Modul 2 — Paperless-ngx serwis (na PIHA)

> Serwis dokumentow: UI+API+Postgres+Redis. Always-on na PIHA. OCR-worker OSOBNO
> (modul 3). Zalezy od: 0 (odchudzic PIHA), 1 (SSO).

## Cel
Postawic Paperless-ngx jako serwis GitOps na PIHA — bez ciezkiego OCR (ten na SOLARIA,
modul 3). Serwis dostepny 24/7 dla zapytan KB + UI do przegladania.

## Wymogi
- `services/paperless/` — docker-compose.yml + service.yaml (owner_node=piha).
- Komponenty: paperless-webserver (UI+API), postgres, redis (broker kolejki OCR).
- **OIDC** przez Forgejo (wzorzec z modulu 1). Login = konto Forgejo.
- **Ingress LAN-only** przez npm@PIHA (NIE public/VPS). Subdomena np. paper.kapala.org
  lub paper.okit.pl -> A record na Tailscale/LAN, DNS Only.
- **Storage**: media + oryginaly na PIHA NVMe (/home/docker lub dedykowany volume).
- **Backup** (WARUNEK BRZEGOWY hybrydy — Paperless=referencja): storage backupowany.
  Zaprojektowac: gdzie (offsite? SOLARIA? drugi dysk?), retencja, jak (paperless
  document-exporter / rsync volume / borg?).
- OCR w tym module WYLACZONY lub minimalny — ciezki batch idzie na worker (modul 3).
  Redis wystawiony tak, by worker na SOLARIA mogl sie podpiac (Tailscale).

## Do zweryfikowania przez CC
- Realne zuzycie RAM Paperless-serwis bez OCR na arm64 (czy miesci sie po odchudzeniu PIHA).
- Porty — kolizje na PIHA (juz 40 kontenerow, sprawdzic wolne).
- Paperless env: PAPERLESS_REDIS, PAPERLESS_DBHOST, PAPERLESS_OCR_* , PAPERLESS_URL,
  PAPERLESS_TASK_WORKERS / PAPERLESS_THREADS_PER_WORKER (pod split OCR).
- OIDC w Paperless: PAPERLESS_APPS / python-social-auth / mozilla-django-oidc — ktory
  mechanizm, jak skonfigurowac przeciw Forgejo.
- arm64 image dostepny (ghcr.io/paperless-ngx/paperless-ngx).
- Jak Redis ma byc osiagalny dla worker@SOLARIA (bind Tailscale IP, nie tylko localhost).

## Kryteria ukonczenia
- Paperless UI dziala na PIHA, login przez Forgejo-OIDC.
- Dostepny LAN/Tailscale, NIE z publicznego internetu.
- Redis broker osiagalny dla zewnetrznego workera (modul 3).
- Backup storage zaprojektowany i dzialajacy (nie "TODO").
- W GitOps: services/paperless/ + wpis w hosts/piha/services.yaml + topology.
- Deploy przez normalny flow (nie manualnie na hoscie).