From 6295f4b9c1cfe170ed37a2c398ff7af425bc02b7 Mon Sep 17 00:00:00 2001
From: jklein <github@justin-klein.de>
Date: Sun, 23 Aug 2026 20:44:02 +0200
Subject: [PATCH] Add NOTES.txt to the apache-tika chart

Tika has no Ingress, so the notes lead with the cluster-internal URL, the
Service-port-80 to container-port-9998 mismatch a consumer has to get right,
and /parsers as the direct answer to "why did this file come back empty".

Two warnings come from measuring the running container rather than from
reading the values file:

- The image tag has to keep its "-full" suffix. That variant is where
  Tesseract 5.5.0 and the extra parsers live; the plain image carries no
  tesseract binary at all, so dropping the suffix does not fail loudly, it
  just stops OCR and returns empty text for scans.
- The JVM never sees the container limit. It starts without -Xmx and derives
  its heap from the limit at MaxRAMPercentage=25, so the number worth sizing
  against is a quarter of it.

The heap figure is computed from the effective limit through the chart's own
null-safe effectiveResources helper, so an erased resources: block still
prints the defaults the container actually receives instead of dropping the
paragraph. Refs #43.
---
 apache-tika/Chart.yaml          |  2 +-
 apache-tika/templates/NOTES.txt | 56 +++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100644 apache-tika/templates/NOTES.txt

diff --git a/apache-tika/Chart.yaml b/apache-tika/Chart.yaml
index 6fa1682..2842272 100644
--- a/apache-tika/Chart.yaml
+++ b/apache-tika/Chart.yaml
@@ -5,5 +5,5 @@ icon: https://www.apache.org/logos/res/tika/default.png
 
 type: application
 
-version: 9.0.0+up3.3.1.0.full
+version: 9.1.0+up3.3.1.0.full
 appVersion: "3.3.1.0-full"
diff --git a/apache-tika/templates/NOTES.txt b/apache-tika/templates/NOTES.txt
new file mode 100644
index 0000000..5867f4e
--- /dev/null
+++ b/apache-tika/templates/NOTES.txt
@@ -0,0 +1,56 @@
+{{- $replicas := include "apache-tika.replicas" (dict "scaleDown" .Values.scaleDown "replicas" .Values.tika.replicas) -}}
+{{- $limits := (include "apache-tika.effectiveResources" .Values.tika.resources | fromYaml).limits | default dict -}}
+{{- $memLimit := index $limits "memory" -}}
+{{- $svc := printf "%s-%s-service" .Release.Name .Chart.Name -}}
+Apache Tika {{ .Chart.AppVersion }} — release {{ .Release.Name }} in namespace {{ .Release.Namespace }}.
+
+ACCESS
+  This chart creates no Ingress. The server is cluster-internal:
+
+    http://{{ $svc }}.{{ .Release.Namespace }}.svc.cluster.local
+
+  Mind the port. The Service listens on 80 and forwards to the container's
+  9998, so consumers are configured without a port — e.g. paperless-ngx:
+
+    PAPERLESS_TIKA_ENDPOINT: http://{{ $svc }}.{{ .Release.Namespace }}.svc.cluster.local
+
+  To reach it from your machine:
+
+    kubectl -n {{ .Release.Namespace }} port-forward svc/{{ $svc }} 9998:80
+    curl http://localhost:9998/version
+    curl http://localhost:9998/parsers
+
+  /parsers lists every parser the running server actually has — the honest
+  answer to "why did this file come back empty". This chart has no secrets
+  and no volumes.
+{{ if eq $replicas "0" }}
+SCALED TO ZERO
+  {{ if .Values.scaleDown }}scaleDown: true{{ else }}tika.replicas: 0{{ end }} — the deployment runs with replicas: 0. The Service
+  keeps its ClusterIP but has no endpoints, so callers fail with "connection
+  refused" rather than a timeout. Set it back and upgrade to return.
+{{ end }}
+NO AUTHENTICATION — AND IT PARSES WHATEVER IT IS SENT
+  Tika has no authentication, and this chart adds none. It is a parser for
+  untrusted input by nature, and its parsers have a long history of being the
+  soft spot. Anything that can reach the Service can make this pod open a
+  file. Keep it cluster-internal; do not put an Ingress in front of it.
+
+THE IMAGE TAG HAS TO KEEP ITS -full SUFFIX
+  appVersion is pinned to {{ .Chart.AppVersion }}. The "-full" variant is the one that
+  ships Tesseract OCR (5.5.0, with the languages deu, eng, fra, ita, jpn, osd
+  and spa) plus the extra parsers; the plain apache/tika:<version> image has
+  no tesseract binary at all. Overriding the tag without "-full" does not fail
+  loudly — OCR simply stops happening and scanned documents come back with
+  empty text.
+{{- if $memLimit }}
+
+THE JVM ONLY GETS A QUARTER OF THE MEMORY LIMIT
+  The server starts without -Xmx, so the JVM derives its maximum heap from the
+  container limit at MaxRAMPercentage=25. With this release's limit of
+  {{ $memLimit }} that is roughly {{ include "apache-tika.multiplyQuantity" (dict "quantity" $memLimit "factor" 0.25) }} of usable heap — the number to reason about when
+  sizing, not the limit itself. Raising tika.resources.requests.memory raises
+  the limit (limitFactor x request) and the heap along with it.
+  Text extraction streams rather than buffering, so ordinary documents stay
+  cheap regardless; the heap is what matters for parsers that have to build a
+  whole document in memory, and for OCR.
+{{- end }}