Self-hosting Paperless-ngx on k3s with GitOps

Description and use

Self-hosted Paperless-ngx on k3s with GitOps: local document storage on an external HDD, OCR and tagging, phone access, automated deployment via Flux.

Problem

Need a local document archive that can OCR, tag, and be accessed from a phone without relying on cloud storage.

Outcome

A fully self-hosted, GitOps-managed Paperless-ngx instance on a single-node k3s cluster, with documents stored on an external HDD and accessible from a phone via OCR-enabled scanning.

Workflow

• Format external HDD as ext4 and mount it by UUID
• Create directories and set ownership for Paperless
• Configure k3s to wait for mount via systemd unit
• Define StorageClass and PersistentVolume for HDD media
• Bind PVC to PV
• Deploy Paperless-ngx stack via Kubernetes manifests
• Resolve k3s errors (port conflict, IP registration, missing folders, service link env var, CSRF origins)
• Set up Flux bootstrap and GitOps repo layout
• Encrypt secrets with SOPS + age and configure Flux decryption
• Annotate resources to prevent prune deletion
• Push configuration changes to GitHub to trigger deployments

Evidence

I ended up with Paperless-ngx running on k3s on a Beelink mini PC.

Source

enableServiceLinks: false

Source

PAPERLESS_CSRF_TRUSTED_ORIGINS=http://paperless.192.168.1.50.nip.io,https://paperless.192.168.1.50.nip.io

Source