helm-charts/paperless-ngx/Chart.yaml

apiVersion: v2
name: paperless-ngx
description: A Helm chart to deploy Paperless-NGX on Kubernetes
icon: https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/dev/src-ui/src/apple-touch-icon.png

type: application

version: 15.0.0+up3.3.1

appVersion: 3.3.1

maintainers:
  - name: jklein

# The third chart in this repo with a dependency (after ytdlp-web-player and
# stalwart). README, "Chart dependencies", holds the bar a dependency has to
# clear and the full price list; what is repeated here is only what is specific
# to THIS chart, because the generic half is already written down twice.
#
# WHY ONE HERE. paperless-ngx cannot run without a Redis: PAPERLESS_REDIS is
# the Celery broker, and without it the web UI comes up looking healthy while
# consumption, OCR, the scheduled tasks and the index updates never run. So
# every installation needs one, and before this block the only way to have one
# was a second Helm release whose address lived in a 1Password item and in
# neither chart.
#
# WHY IT IS OFF BY DEFAULT: an installation that already has a Redis (or wants
# a shared one, which is what secrets.redisSecretRef' key-prefix field exists
# for) points redis-connection-url at it, and this dependency renders nothing.
# The subchart is the path for an installation that has none.
#
# THE SUBCHART IS OUR OWN valkey CHART, resolved from the published index - not
# upstream's. So README guideline 14.2 ("we consume their chart as it comes")
# does not apply and there are no third-party defaults to leave unpatched: the
# subchart follows this repo's conventions because it IS this repo's chart.
# What does apply in full is the subchart being invisible to everything
# downstream that watches Helm release versions, and the PR-ordering hazard
# below.
dependencies:
  - name: valkey
    # KEEP THIS VERSION MOVING - it is the only path a Valkey update has into a
    # cluster through this chart. The version declared here is baked into our
    # packaged .tgz, so anything watching Helm release versions (Fleet
    # included) sees only "paperless-ngx": a new valkey chart, a security fix
    # included, arrives ONLY when this line is raised and a new paperless-ngx
    # version is published. Nothing reports the gap.
    #
    # Renovate's BUILT-IN helmv3 manager reads this block and opens the PR, and
    # ci/renovate-bump-chart.sh bumps this chart's patch version, which is what
    # actually ships it. No customManagers entry exists or would help - that
    # manager is for exactly this case, where repository and version sit
    # together in one file. Measured for Gitea #65 against our self-hosted
    # index (Renovate 44.132.2, dry run with the dependency pinned low:
    # newVersion "1.0.0+up9.1.2.alpine", versioning "helm"), so the chain is
    # proven for this registry and this build-metadata suffix and was not
    # re-measured here.
    #
    # Independent of appVersion: raising it is a patch or minor bump of this
    # chart and is never tied to the paperless-ngx image.
    version: "2.0.0+up9.1.2.alpine"
    # Our own published index, and the READ path only - anonymously readable
    # (measured), so ci/helm-dependencies.sh needs no credential and was not
    # touched. The publish target and its credentials still live in 1Password
    # and appear nowhere in this repository; see README, "CI/CD".
    repository: "https://git.jk-dev.de/api/packages/jlab-cluster/helm"
    # Off by default, so a plain install renders none of its objects.
    #
    # NOT "valkey.enabled", AND THAT IS NOT A STYLE CHOICE. Everything under
    # the "valkey:" key is handed to the subchart as ITS values and validated
    # against ITS schema, and our valkey chart ships additionalProperties:
    # false with no "enabled" property:
    #   Error: values don't meet the specifications of the schema(s) in the
    #   following chart(s): valkey: - at '': additional properties 'enabled'
    #   not allowed
    # Worse, Helm skips a DISABLED subchart's schema validation, so with the
    # default of false that error would stay invisible through lint, render and
    # install-test and surface only for whoever first switched it on - the one
    # case the value exists for. The condition is therefore a key of OUR OWN,
    # outside the subchart's value subtree.
    condition: valkeySubchart.enabled
#
# !!! NEVER CHANGE valkey/ AND THIS CHART IN THE SAME PULL REQUEST !!!
#
# The dependency resolves out of the PUBLISHED index, not out of the working
# tree, and valkey/ is published only by a push to main that touches it. A
# single PR carrying both therefore runs lint, package, render AND the
# install-test against the OLD valkey .tgz and goes green about an artifact
# that is not the one in the diff. Two consecutive pull requests: change
# valkey/, merge, let it publish, then raise the version here. README, "Chart
# dependencies", and the wiki's valkey page carry the long form.