Self-hosting Paperless-ngx on k3s with GitOps

说明与用途

在 k3s 上使用 GitOps 自托管 Paperless‑ngx：通过手机扫描文档，存储在外部 HDD 上，进行 OCR，并通过 Flux 管理配置。

问题

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.

结果

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.

工作流

• 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

证据

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.

来源

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

来源

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.

来源