Self-hosting Paperless-ngx on k3s with GitOps

Description and use

Self-hosting Paperless‑ngx on k3s with GitOps: documents are scanned from a phone, stored on an external HDD, OCRed, and configuration is managed via Flux.

Problem

Need a local document archive that can be scanned from a phone, OCRed, and stored on a large external HDD without relying on cloud services.

Outcome

Paperless-ngx is fully operational on a single-node k3s cluster, documents are stored on an external HDD, and all configuration changes are applied automatically via GitOps.

Workflow

• Format external HDD as ext4 and mount it by UUID
• Create directories and set ownership for Paperless
• Configure k3s to wait for the mount
• Define a local StorageClass and PersistentVolumes for media and export folders
• Deploy Paperless-ngx with PostgreSQL, Redis, Tika, Gotenberg via kustomize
• Fix k3s port conflicts and IP registration issues
• EnableServiceLinks: false to avoid Paperless reading Kubernetes service URLs
• Set PAPERLESS_CSRF_TRUSTED_ORIGINS for phone access
• Set up Flux GitOps with SOPS-encrypted secrets and prune annotations
• Push configuration changes to GitHub to trigger automatic rollouts

Evidence

I ended up with Paperless-ngx running on k3s on a Beelink mini PC. Documents live on an external HDD, and Flux deploys every config change I push to GitHub.

Source

enableServiceLinks: false fixes the crash-looping error where Paperless reads PAPERLESS_PORT from a Kubernetes service URL.

Source

PAPERLESS_CSRF_TRUSTED_ORIGINS=http://paperless.192.168.1.50.nip.io,https://paperless.192.168.1.50.nip.io allows phone access after CSRF failure.

Source