From a573b7e3949d75ef3244155dedd4f3f3b573e38d Mon Sep 17 00:00:00 2001 From: oskar Date: Tue, 4 Aug 2026 15:06:40 +0200 Subject: [PATCH] feat(kb): SPLIT paperless -> service + decision + runbook kb/services/paperless.md (Stack, OIDC, Storage i backup, RAM na PIHA) kb/decisions/paperless-split-ocr.md (split OCR serwis@PIHA + worker@SOLARIA) kb/runbooks/paperless-cutover.md (cutover checklist) Tresc sekcji nietknieta; kontrola multizbioru linii == oryginal. Co-Authored-By: Claude Opus 5 (1M context) --- kb/decisions/paperless-split-ocr.md | 33 +++++++++++++ kb/runbooks/paperless-cutover.md | 29 ++++++++++++ .../README.md => kb/services/paperless.md | 47 +++++-------------- 3 files changed, 73 insertions(+), 36 deletions(-) create mode 100644 kb/decisions/paperless-split-ocr.md create mode 100644 kb/runbooks/paperless-cutover.md rename services/paperless/README.md => kb/services/paperless.md (66%) diff --git a/kb/decisions/paperless-split-ocr.md b/kb/decisions/paperless-split-ocr.md new file mode 100644 index 0000000..f59a893 --- /dev/null +++ b/kb/decisions/paperless-split-ocr.md @@ -0,0 +1,33 @@ +--- +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`. + diff --git a/kb/runbooks/paperless-cutover.md b/kb/runbooks/paperless-cutover.md new file mode 100644 index 0000000..2352d26 --- /dev/null +++ b/kb/runbooks/paperless-cutover.md @@ -0,0 +1,29 @@ +--- +okf: "0.1" +type: runbook +visibility: private +status: active +updated: 2026-07-09 +links: + - ../services/paperless.md + - ../decisions/paperless-split-ocr.md +--- + +# Paperless — cutover checklist + +## Cutover checklist (przy deployu — NIE teraz) + +1. Moduł 0 (piha-slim) domknięty; `free -g` na PIHA potwierdza zapas. +2. Porty wolne na żywym hoście: `ss -tlnp | grep -E '8210|5434|6380'`. +3. `mkdir -p /opt/homelab/data/paperless/{data,media,consume,export}` na PIHA. +4. `.env` z `env.example` (sekrety + rejestracja OAuth2 w Forgejo). +5. DNS: rekord A `paper.kapala.org` w Cloudflare → `100.108.208.3` + (Tailscale PIHA, DNS Only) — ten sam wzorzec co `ha.kapala.org` / + `immich.kapala.org` (`docs/sessions/2026-06-30-kapala-cloudflare-wildcard-mesh.md`); + wildcard `*.kapala.org` już pokrywa tę subdomenę, nowy cert niepotrzebny. + Plus vhost w npm@PIHA (HTTPS → `192.168.31.5:8210`, Advanced puste). +6. `docker compose up -d` + `./healthcheck.sh` + testowy login OIDC. +7. Export NFS dla workera (patrz `services/paperless-worker/README.md`) — + dopiero przy module 3. +8. Wpis w `hosts/piha/services.yaml` (dopiero przy deployu — wcześniej + supervisor widziałby drift dla nieistniejącego serwisu). diff --git a/services/paperless/README.md b/kb/services/paperless.md similarity index 66% rename from services/paperless/README.md rename to kb/services/paperless.md index 6b97672..7a467a3 100644 --- a/services/paperless/README.md +++ b/kb/services/paperless.md @@ -1,3 +1,14 @@ +--- +okf: "0.1" +type: service +visibility: private +status: active +updated: 2026-07-09 +links: + - ../decisions/paperless-split-ocr.md + - ../runbooks/paperless-cutover.md +--- + # Paperless-ngx (serwis, PIHA) Serwis dokumentów filaru KB #2 (moduł 2, `docs/kb/modules/02-paperless-service.md`): @@ -26,26 +37,6 @@ Wszystkie porty bindowane na `LAN_BIND_IP` (192.168.31.5), nigdy 0.0.0.0: Obraz jest multi-arch (arm64 natywnie na Pi 5). Tag `2.14` MUSI być identyczny z `services/paperless-worker/docker-compose.yml` — podbijać oba naraz. -## 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`. - ## OIDC przez Forgejo Mechanizm: `django-allauth` z providerem `openid_connect` @@ -105,19 +96,3 @@ Oczekiwany spoczynek: paperless ~400–600 Mi (gunicorn + consumer + beat + `hosts/piha/runtime/paperless/docker-compose.override.yml`. Warunek: moduł 0 (odchudzenie PIHA) wykonany — po nim ~3.8 Gi available. -## Cutover checklist (przy deployu — NIE teraz) - -1. Moduł 0 (piha-slim) domknięty; `free -g` na PIHA potwierdza zapas. -2. Porty wolne na żywym hoście: `ss -tlnp | grep -E '8210|5434|6380'`. -3. `mkdir -p /opt/homelab/data/paperless/{data,media,consume,export}` na PIHA. -4. `.env` z `env.example` (sekrety + rejestracja OAuth2 w Forgejo). -5. DNS: rekord A `paper.kapala.org` w Cloudflare → `100.108.208.3` - (Tailscale PIHA, DNS Only) — ten sam wzorzec co `ha.kapala.org` / - `immich.kapala.org` (`docs/sessions/2026-06-30-kapala-cloudflare-wildcard-mesh.md`); - wildcard `*.kapala.org` już pokrywa tę subdomenę, nowy cert niepotrzebny. - Plus vhost w npm@PIHA (HTTPS → `192.168.31.5:8210`, Advanced puste). -6. `docker compose up -d` + `./healthcheck.sh` + testowy login OIDC. -7. Export NFS dla workera (patrz `services/paperless-worker/README.md`) — - dopiero przy module 3. -8. Wpis w `hosts/piha/services.yaml` (dopiero przy deployu — wcześniej - supervisor widziałby drift dla nieistniejącego serwisu).