---
okf: "0.1"
type: decision
visibility: private
status: active
updated: 2026-07-09
links:
  - ../services/paperless.md
  - ../runbooks/paperless-cutover.md
---

# Paperless — decyzja: split OCR serwis@PIHA + worker@SOLARIA

## Split OCR: serwis@PIHA + worker@SOLARIA (wynik badania)

Rozproszony worker **nie jest oficjalnie wspierany** przez Paperless-ngx, ale
jest wykonalny i potwierdzony przez maintainerów (GH discussion #3900): drugi
host odpala ten sam obraz z `command: celery --app paperless worker` i musi
widzieć **ten sam Redis, tego samego Postgresa i te same pliki**. Stąd:

- storage dokumentów leży na PIHA (bind mounty `/opt/homelab/data/paperless/*`)
  i jest eksportowany przez **NFS po LAN** (nie Tailscale) do SOLARII;
- ścieżki w kontenerze (`/usr/src/paperless/{data,media,consume}`) muszą być
  **identyczne** po obu stronach — payloady zadań i DB niosą ścieżki absolutne;
- pliki mają właściciela **numerycznego UID 1000** (`USERMAP_UID/GID=1000`
  po obu stronach) — NFS przenosi numeryczne ID, nie nazwy;
- wbudowany worker na PIHA (nie da się go wyłączyć w stockowym obrazie) działa
  jako wolny fallback, gdy SOLARIA śpi; zadania czekają w Redis (AOF włączone,
  restart brokera nie gubi kolejki).

Szczegóły NFS (export na PIHA, mount na SOLARIA, ryzyko indeksu Whoosh) —
`services/paperless-worker/README.md`.