feat(paperless): upgrade to v3.1.2 (image policy 2.x -> 3.x)

paperless-ngx released 3.0.0 on 2026-07-22; the ImagePolicy was deliberately gated at semver 2.x, so the deployment stayed on 2.20.15 while upstream moved to 3.1.2. No 2.x release has appeared since 3.0.0, so the gate now holds the deployment on a branch that receives no patches. Preflight for the major bump, against docs/migration-v3.md: - 2.20.15 is the only valid source version, and it is enforced rather than advised: src/paperless/checks.py raises paperless.E002 unless the documents app has 1075_workflowaction_order applied, and init-migrations runs `manage.py check --tag compatibility` before migrate. We are on 2.20.15 exactly, so there is no intermediate hop. - CONSUMER_POLLING is renamed to CONSUMER_POLLING_INTERVAL. Renamed here; the 10s value and the CephFS-inotify reason for it are unchanged. - CONSUMER_BARCODE_SCANNER is removed — pyzbar is gone and zxing-cpp is the only backend. We set ZXING, which is what remains, so dropping the variable keeps current behaviour. - SECRET_KEY becomes mandatory. Already set from the paperless-secrets Secret. - DBENGINE becomes required rather than inferred, and must read `postgresql`, not `postgres` — a distinction 3.0.1 shipped a fix for. Already `postgresql`. - v3 stops rejecting duplicates by default; CONSUMER_DELETE_DUPLICATES=true preserves the current behaviour and is already set. - Nothing else in the removed set applies: no encrypted documents, no pre- or post-consume scripts, no OCR_MODE or OCR_SKIP_ARCHIVE_FILE, no CONSUMER_IGNORE_PATTERNS relying on fnmatch, no CONSUMER_INOTIFY_DELAY. Tika and Gotenberg settings are unchanged in 3.x, as are the remote-user auth variables Authentik depends on. - API v1 is gone and the minimum is version 9. No consumer in this repo uses the API: docs.renner.uno is a Traefik redirect to paperless.renner.uno, Gatus probes the URL root, and Authentik holds only proxy-provider config. - PostgreSQL 16 clears the documented minimum of 14. Redis has no documented minimum; 8.10.1 is current. A startupProbe is added because the first 3.x boot is long. s6 makes svc-webserver depend on init-migrations and init-search-index, so nothing is served until both finish, and on this boot they are the SHA256 checksum backfill — which opens and reads every original and every archive file — and a full Tantivy index build, because the Whoosh index cannot be converted. Against the existing probes alone the pod would be killed 210s in, part-way through a migration, and the next boot would start over. This upgrade is one way. The 3.x tree squashes the entire pre-3.0 migration history into 0001_squashed and deletes the individual files, the checksum migration's reverse is RunPython.noop so the SHA256 values would survive a schema reversal that 2.x cannot read, and task history is dropped outright. Upstream states none of this as policy, but rollback should be treated as restore-from-backup and redeploy 2.20.15, not a tag revert against a migrated database. Policy gate moves to 3.x; a 4.x cutover needs manual review again. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-02 06:49:52 +02:00
2 changed files with 26 additions and 5 deletions
@@ -31,12 +31,14 @@ data:
  PAPERLESS_CONSUMER_DELETE_DUPLICATES: "true"
  PAPERLESS_CONSUMER_ENABLE_BARCODES: "true"
  PAPERLESS_CONSUMER_ENABLE_ASN_BARCODE: "true"
-  PAPERLESS_CONSUMER_BARCODE_SCANNER: "ZXING"
+  # No CONSUMER_BARCODE_SCANNER: zxing-cpp is the only backend, so the
+  # setting no longer exists. pyzbar and libzbar are gone from the image.
+  #
  # CephFS does not propagate inotify across nodes — files written
  # via the RWX consume PVC from a pod on a different node than
  # paperless never fire IN_CREATE in paperless's kernel. Polling
  # is the reliable backstop. See wiki: cephfs-inotify-no-cross-node-propagation.
-  PAPERLESS_CONSUMER_POLLING: "10"
+  PAPERLESS_CONSUMER_POLLING_INTERVAL: "10"
  PAPERLESS_REDIS: "redis://redis:6379"
  PAPERLESS_DBENGINE: "postgresql"
  PAPERLESS_DBHOST: "pprl-pg-rw"
@@ -120,7 +122,7 @@ spec:
              drop: ["ALL"]
      containers:
        - name: paperless
-          image: ghcr.io/paperless-ngx/paperless-ngx:2.20.15 # {"$imagepolicy": "flux-system:paperless-ngx"}
+          image: ghcr.io/paperless-ngx/paperless-ngx:3.1.2 # {"$imagepolicy": "flux-system:paperless-ngx"}
          ports:
            - name: http
              containerPort: 8000
@@ -172,6 +174,25 @@ spec:
          # Safe against ALLOWED_HOSTS: the kubelet sends the pod IP as Host,
          # and PAPERLESS_ALLOWED_HOSTS is "*". Narrowing that value later
          # means giving these probes an explicit Host header.
+
+          # The container does not serve until its init sequence finishes:
+          # s6 makes svc-webserver depend on init-migrations and
+          # init-search-index. On the first 3.x start those are the SHA256
+          # checksum backfill, which opens and reads every original and every
+          # archive file, and a full Tantivy index build, since the Whoosh
+          # index cannot be converted. Both scale with the corpus.
+          #
+          # startupProbe holds liveness and readiness off until the webserver
+          # answers, giving that boot 30 * 20s = 10 minutes. Without it the
+          # 120s liveness delay plus three 30s periods kills the pod 210s in,
+          # part-way through a migration, and the next boot starts over.
+          startupProbe:
+            httpGet:
+              path: /accounts/login/
+              port: http
+            periodSeconds: 20
+            timeoutSeconds: 5
+            failureThreshold: 30
          livenessProbe:
            httpGet:
              path: /accounts/login/
@@ -7,7 +7,7 @@ spec:
  image: ghcr.io/paperless-ngx/paperless-ngx
  interval: 1h
 ---
-# Allow only patch + minor bumps within the 2.x line. A 3.0 release
+# Allow only patch + minor bumps within the 3.x line. A 4.0 release
 # requires manual policy widening — major upgrades typically need a
 # migration plan and shouldn't land via auto-merge.
 apiVersion: image.toolkit.fluxcd.io/v1
@@ -20,4 +20,4 @@ spec:
    name: paperless-ngx
  policy:
    semver:
-      range: "2.x"
+      range: "3.x"