paperless-ngx-helm

Helm chart to deploy Paperless-NGX on Kubernetes, always tracking the latest release.

Note: This repo is kept up to date automatically. I am not your developper, so I will not implement changes for you. If you need something I will happily check your code and merge it! Issues are there to discuss changes before creating a PR, not to ask for something to be done.

Components

Component	Default image	Purpose
Paperless-NGX	ghcr.io/paperless-ngx/paperless-ngx	Main application
PostgreSQL	ghcr.io/cloudnative-pg/postgresql:18	Database (via CloudNativePG operator)
Redis	redis:7-alpine	Task queue / caching
Gotenberg	gotenberg/gotenberg:8	Office-document → PDF conversion
Tika	ghcr.io/paperless-ngx/tika:2.9.1-minimal	Document text extraction

Prerequisites

• Kubernetes 1.25+
• Helm 3.10+
• CloudNativePG operator installed in the cluster
• A default or named StorageClass available

Installing the chart

From the Helm repository (recommended)

The chart is published via GitHub Pages.
Enable the repository once and install from there:

helm repo add paperless-ngx https://kernelb00t.github.io/paperless-ngx-helm
helm repo update

helm install my-paperless paperless-ngx/paperless-ngx \
  --set paperless.secrets.PAPERLESS_SECRET_KEY="$(openssl rand -hex 32)" \
  --set paperless.secrets.PAPERLESS_ADMIN_PASSWORD="strongpassword" \
  --namespace paperless \
  --create-namespace

From OCI (GHCR)

The chart is also published as an OCI artifact to the GitHub Container Registry:

helm install my-paperless \
  oci://ghcr.io/kernelb00t/paperless-ngx \
  --version <version> \
  --set paperless.secrets.PAPERLESS_SECRET_KEY="$(openssl rand -hex 32)" \
  --set paperless.secrets.PAPERLESS_ADMIN_PASSWORD="strongpassword" \
  --namespace paperless \
  --create-namespace

From a local clone (development)

helm install my-paperless ./paperless-ngx \
  --set paperless.secrets.PAPERLESS_SECRET_KEY="$(openssl rand -hex 32)" \
  --set paperless.secrets.PAPERLESS_ADMIN_PASSWORD="strongpassword" \
  --namespace paperless \
  --create-namespace

Quick start with custom values

# my-values.yaml
paperless:
  config:
    PAPERLESS_URL: "https://paperless.mycompany.com"
    PAPERLESS_TIME_ZONE: "Europe/Paris"
    PAPERLESS_OCR_LANGUAGE: "fra+eng"
  secrets:
    PAPERLESS_SECRET_KEY: "a-very-long-random-string"
    PAPERLESS_ADMIN_USER: "admin"
    PAPERLESS_ADMIN_PASSWORD: "changeme"
    PAPERLESS_ADMIN_MAIL: "admin@mycompany.com"

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: paperless.mycompany.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: paperless-tls
      hosts:
        - paperless.mycompany.com

postgresql:
  instances: 1
  storage:
    size: 20Gi

persistence:
  data:
    size: 10Gi
  media:
    size: 100Gi

helm install my-paperless paperless-ngx/paperless-ngx -f my-values.yaml -n paperless --create-namespace

Values

See paperless-ngx/values.yaml for the full, annotated list of parameters.

Key parameters

Parameter	Description	Default
paperless.image.tag	Paperless-NGX image tag (empty = Chart appVersion)	""
paperless.config	Non-secret env vars passed to the app	see values.yaml
paperless.secrets.*	Secret credentials (secret key, admin user/password) — required unless existingSecret is set	see values.yaml
paperless.existingSecret	Name of a pre-existing K8s Secret to use instead of chart-managed secrets. The secret must contain PAPERLESS_SECRET_KEY, PAPERLESS_ADMIN_USER, PAPERLESS_ADMIN_PASSWORD, PAPERLESS_ADMIN_MAIL	""
paperless.strategy	Deployment update strategy (Recreate avoids Multi-Attach errors with RWO PVCs)	{type: Recreate}
ingress.enabled	Expose Paperless via an Ingress	false
persistence.*.size	PVC sizes for data / media / export / consume	various
persistence.*.existingClaim	Use an existing PVC instead of creating one	""
cnpg.instances	Number of CloudNativePG instances	1
cnpg.storage.size	Storage size for the Postgres cluster	10Gi
cnpg.postgresVersion	PostgreSQL major version (image tag unless cnpg.image.tag is set)	18
cnpg.appSecret	Existing basic-auth secret for the app user (empty = CNPG generates <cluster>-app)	""
cnpg.plugins	CNPG-I plugins for the Cluster (e.g. Barman Cloud for backups / WAL archiving). Requires CNPG >= 1.26 and the plugin deployed separately — see the CNPG-I docs	[]
redis.enabled	Deploy Redis sidecar	true
redis.strategy	Redis Deployment update strategy (Recreate avoids Multi-Attach errors with RWO PVCs)	{type: Recreate}
gotenberg.enabled	Deploy Gotenberg	true
tika.enabled	Deploy Tika	true

PostgreSQL (CloudNativePG)

Only CloudNativePG is currently supported as the database backend. If you need MySQL/MariaDB support, contributions are welcome — please open a PR.

The chart creates a Cluster custom resource (CRD provided by the CloudNativePG operator). The operator automatically:

• creates a secret <clusterName>-app containing username and password
• exposes a read-write service at <clusterName>-rw

These are automatically wired into the Paperless deployment.

Note: The CloudNativePG operator must be installed before running helm install. See: https://cloudnative-pg.io/docs/current/installation_upgrade/

Upgrading PostgreSQL major version

Bumping cnpg.postgresVersion triggers a major-version upgrade (it is used as the image tag unless cnpg.image.tag is set). CloudNativePG supports this via its built-in pg_upgrade method — see the CNPG upgrade docs before proceeding.

Security

All pods run as non-root and drop all Linux capabilities by default. Adjust securityContext in values if your environment requires different settings.

Upgrading

# From the Helm repo
helm repo update
helm upgrade my-paperless paperless-ngx/paperless-ngx -n paperless -f my-values.yaml

# From OCI
helm upgrade my-paperless oci://ghcr.io/kernelb00t/paperless-ngx \
  --version <new-version> -n paperless -f my-values.yaml

Development

helm lint paperless-ngx -f paperless-ngx/ci/ct-values.yaml
helm plugin install https://github.com/helm-unittest/helm-unittest.git   # add --verify=false on Helm 4
helm unittest paperless-ngx

CI also installs the chart on a KinD cluster, and upgrades from the latest published release to check that existing installations keep working.

Releases & Changelog

Every release is published in three places:

Distribution	URL
GitHub Releases	https://github.com/kernelb00t/paperless-ngx-helm/releases
Helm repo (gh-pages)	https://kernelb00t.github.io/paperless-ngx-helm
OCI (GHCR)	ghcr.io/kernelb00t/paperless-ngx

The full CHANGELOG.md is automatically generated from conventional commits by git-cliff on each release.

Releasing a new version

Releases are triggered manually via the Release Chart GitHub Actions workflow (Actions → Release Chart → Run workflow).

Chart versioning policy:

• appVersion follows upstream Paperless-NGX versions.
• version is independent and strict SemVer (x.y.z), starting at 1.0.0.
• Automated upstream appVersion bumps increment chart minor.
• Other chart updates increment chart patch.

Note (GitHub Pages): For the Helm repository to work, GitHub Pages must be enabled in the repository settings and configured to deploy from the gh-pages branch: Settings → Pages → Source → Deploy from branch → Branch: gh-pages / root