homelab-gitops/apps/paperless/README.md

Paperless namespace ownership

Paperless, ScanservJS, and Stirling PDF use three independently published charts and three Argo Applications. Paperless's chart owns only the Paperless Deployment, Service, and Ingress; the scanner chart owns the ScanservJS Deployment, ConfigMap action, Service, and Ingress; the Stirling chart owns the PDF editor Deployment, Service, and Ingress. This repository supplies hostnames, Secret names, the scanner's eSCL endpoint and shared claim, resource sizing, and Paperless's soft preference for the arschrock node.

The paperless-storage Application owns the pre-existing paperless-data and paperless-runtime PVC declarations with pruning disabled. Neither chart recreates them. The scanner action copies scans to the consume subdirectory of paperless-data; it does not use email or a recipient address.

PostgreSQL is the dedicated CloudNativePG cluster paperless-cnpg, reached through the existing postgresql Service alias. Preserve its PVC and the retired postgres-data-postgresql-0 rollback claim.

paperless-valkey now owns the upstream Valkey chart and retains the valkey Service address. Its AOF is stored in paperless-data/valkey with every-second fsync. Paperless stages uploads and PDF edits in paperless-data/scratch, not an ephemeral container filesystem. Both paths belong to the existing CephFS backup selection. The scheduled file mirror is not an atomic queue snapshot; for queue recovery, quiesce Paperless and capture a consistent Valkey RDB as well as the staged files, database and application Secret. Do not call an unmounted /mnt/backup a successful backup destination.

Paperless has no hostPath or dependency on /mnt or /komposthaufen. Its preference for arschrock is soft; a cordon permits scheduling on another node. Four import workers limit database connection bursts. Drain active/reserved Celery tasks before replacements: durable storage does not replay every task that was already acknowledged by a worker.

Stale task history (2026-10-28)

Seventy old in-progress imports already had real documents. Original SHA-256, OCR content and thumbnail checks were used before reconciling their results; do not blindly mark pending tasks successful or re-upload duplicates. Historical failures were retained and acknowledged only after verifying successful retries or complete replacement splits. Two old bulk metadata jobs lacked their broker payloads and were cancelled, not falsely reported successful.

For a future incident, compare task records with Celery active/reserved work, broker queues, staged files and existing documents before retrying. Back up the database and task records first; never delete the task list to hide errors.

paperless-secret-key, paperless-postgres, and paperless-oidc remain cluster-managed Secrets referenced by name. They are not copied into this public repository. The old deployment repository's Authentik/OIDC setup scripts remain a recovery reference until their ownership is settled.