homelab/paperless

Paperless-ngx

Paperless-ngx runs in the paperless namespace. It uses the shared PostgreSQL service in the database namespace and Valkey for its task queue. The document library, exports, and consume folder are stored on the local-path-retain volume. The PVC size is fixed at 50 GiB because this storage class does not support volume expansion.

The local route is https://papers.workstation.internal; the public route is https://papers.forust.xyz. Both use TLS. Paperless keeps its own login and password authentication. OCR is configured for Russian and English documents.

Prepare the secret

Create k8s/secrets.yaml on the workstation from k8s/secrets.yaml.example. Set a unique random PAPERLESS_SECRET_KEY, a long PAPERLESS_ADMIN_PASSWORD, and PAPERLESS_DB_PASSWORD.

Add the same PAPERLESS_DB_PASSWORD value to the local postgres/k8s/secrets.yaml file. Keep both secret files out of Git. The database bootstrap Job creates the paperless role and database from the shared PostgreSQL secret. The job runs in the database namespace and needs that namespace's existing postgres-shared-secrets Secret.

For example, generate a key with:

python3 -c 'import secrets; print(secrets.token_urlsafe(64))'

Then apply the secret before enabling the service:

kubectl apply -f paperless/k8s/namespace.yaml
kubectl apply -f postgres/k8s/secrets.yaml
kubectl apply -f paperless/k8s/secrets.yaml

The normal deploy workflow applies the remaining manifests when paperless/k8s/active is present. Verify the rollout and ingress after deploy:

kubectl -n paperless rollout status deployment/paperless
kubectl -n paperless get pods,pvc,services

Back up the paperless-data PVC and the shared PostgreSQL database. The PVC contains the originals, archived PDFs, and export/consume folders. Valkey has no persistent volume; queued tasks are recreated after a restart.