Self-hosting Paperless-ngx on k3s with GitOps

Описание и применение

Самостоятельный хостинг Paperless‑ngx на k3s с GitOps: документы сканируются с телефона, сохраняются на внешнем 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.

Источник