A Helm chart is the supported way to run Contextator on Kubernetes. Sources for everything on this page:
the chart itself, at charts/contextator/ in the repository, and its own longer
charts/contextator/README.md.
Installing
helm repo add contextator https://contextator.github.io/Contextator
helm repo update
helm install contextator contextator/contextator \
--set database.url="postgres://user:pass@host:5432/contextator" \
--set-string image.tag="<version>-slim"
database.url (or database.existingSecret, for a Secret you already manage) and image.tag are both
required and have no default — the chart fails helm install/helm template immediately, before
rendering anything, if either is missing. image.tag must point at a -slim build; the tags without
that suffix are the full image with an embedded PostgreSQL, the wrong topology for this chart. Or
install straight from a checked-out copy of the chart directory with
helm install contextator ./charts/contextator -f my-values.yaml — the same two values are still
required, in the values file or on the command line.
One replica, by design
replicaCount is not a supported value — the chart rejects it outright
(additional properties 'replicaCount' not allowed), and this is intentional, not a gap: Contextator
runs a single writer against its own indexing queue, and clustering it would need a coordination layer
the product does not have yet. Scale the pod’s own resources instead of its count; see
Resource sizing below.
Database
Either give the chart a connection string directly (database.url) or point it at a Secret you already
manage (database.existingSecret) — the same choice Configuration describes
for DATABASE_URL outside Kubernetes. PostgreSQL itself is not part of this chart; run it separately, or
point at a managed instance.
SECRET_KEY: generated once, held stable
SECRET_KEY encrypts source credentials at rest — git, Notion, Confluence and GitHub tokens, S3 key pairs, Google Drive keys and webhook
secrets — so losing it does not just log everyone out, it makes those stored credentials unrecoverable.
Left unset, the chart generates one on first install and — because it reads the running
cluster’s Secret with Helm’s lookup function before deciding whether to generate a new one — keeps that
same value across every subsequent helm upgrade, without you doing anything.
The lookup function only works against a real, reachable cluster. Rendering the chart offline —
helm template, or a GitOps controller reconciling from a rendered manifest without a live lookup — sees
no existing Secret every time and would generate a new key on every render, which is precisely the value
you cannot have change under a running instance. In that setup, generate the key yourself once and hand it
to the chart as an existing Secret instead of letting it generate one:
kubectl create secret generic contextator-secret-key \
--from-literal=SECRET_KEY=$(openssl rand -hex 32)
secretKey:
existingSecret: contextator-secret-key
existingSecretKey: SECRET_KEY
Rotating it is a two-step move, not a value swap. First, save the current value under a new name —
contextator-secret-key is about to be overwritten with the new key, so copy the old one out before
generating anything:
kubectl -n <namespace> create secret generic contextator-secret-key-previous \
--from-literal=SECRET_KEY="$(kubectl -n <namespace> get secret contextator-secret-key -o jsonpath='{.data.SECRET_KEY}' | base64 -d)"
Then generate the new key and write it into contextator-secret-key in place (kubectl create alone
would fail on a Secret that already exists):
kubectl -n <namespace> create secret generic contextator-secret-key \
--from-literal=SECRET_KEY="$(openssl rand -hex 32)" \
--dry-run=client -o yaml | kubectl -n <namespace> apply -f -
With the new key pinned the same way as above (secretKey.existingSecret/secretKey.existingSecretKey),
give the process the old one as SECRET_KEY_PREVIOUS through envSecret, whose entries are always
NAME: {secretName, secretKey}:
envSecret:
SECRET_KEY_PREVIOUS:
secretName: contextator-secret-key-previous
secretKey: SECRET_KEY
With both present and the Pod restarted, find the Deployment name (<release>-contextator, unless the
release name already contains contextator or fullnameOverride is set) and run the rotation inside it:
kubectl -n <namespace> get deploy -l app.kubernetes.io/instance=<release>
kubectl -n <namespace> exec deploy/<deployment-name> -- npm run rotate-secret
It decrypts what the old key encrypted and re-encrypts it under the new one. Once it reports nothing
left to convert, remove SECRET_KEY_PREVIOUS (the envSecret entry) and let the Pod restart again — that
removal is what retires the old key. If the key is gone entirely and there is no
SECRET_KEY_PREVIOUS to recover with, source credentials stored under it cannot be decrypted — re-adding
those sources is the only way back.
Ingress and the reverse-proxy triple
An Ingress in front of the chart is a reverse proxy like any other, and the same triple from
Configuration applies: config.trustProxy,
config.publicBaseUrl and env.AUTH_COOKIE_SECURE move together, or the per-IP sign-in limit, MCP
connector authorization and the session cookie each break silently in their own way.
A hop count (2, 3, …) is refused, and so are "1" and "true". That is the same guardrail
Configuration describes outside Kubernetes: chart
2.0.0’s values schema rejects config.trustProxy set to either of them (any letter case, surrounding
whitespace ignored), so helm upgrade stops before anything changes, and the application itself has refused
the same value at startup since 0.5.0. Name the proxy instead, the narrowest range that actually covers it:
config:
publicBaseUrl: "https://contextator.example.com"
trustProxy: "<ingress-controller-pod-ip-or-cidr>"
env:
AUTH_COOKIE_SECURE: "1"
The value is matched against every hop, not just the socket’s peer, so pasting the whole pod CIDR trusts every other pod that can reach this Service too — safe only behind a NetworkPolicy that lets nothing but the ingress controller reach this pod’s port.
Upgrading to chart 2.0.0
Chart 2.0.0 is a major version because its values schema newly rejects a value: config.trustProxy set to
"1" or "true", which told the application to believe the left-most X-Forwarded-For whoever wrote it.
Application 0.5.0 refuses the same value at startup, so a release that kept accepting it would have gone into a
CrashLoop; the schema stops helm upgrade instead, before anything changes.
Before upgrading, if your values file or --set flags set it:
- the proxy is on another host or in another Pod: set
config.trustProxyto its address or CIDR block, for example"172.18.0.0/16"— the narrowest range that holds the proxy, not the network your clients are on; - the proxy runs on the same host as the application:
"loopback"; - nothing sits in front of the Pod:
"0", or leave it empty.
helm template t charts/contextator --set-string config.trustProxy=1 shows the refusal. --set turns 1 and
true into a number and a boolean, which the schema already rejected as a type error, so --set-string is the
form that tests this rule. A TRUST_PROXY set through the free-form env map is not seen by the schema, but
the application refuses it the same way when the Pod starts.
Persistence
Two ReadWriteOnce PersistentVolumeClaims: /data (uploaded files, git checkouts, and Notion, Confluence, web, S3, Google Drive and GitHub pulls) and
/app/.cache/models (the downloaded embedding model, so a pod restart does not re-download it). /data
is verified, on a live cluster, to survive a pod restart intact.
Probes
Liveness is a bare TCP check on the port — enough to catch a wedged process without depending on the
database. Readiness and startup are both a real GET /api/health call, so a pod is not marked ready
until the application can actually answer, not merely accept a connection. Verified on a live cluster
against a database outage: the pod reports READY 0/1 for the duration, takes zero restarts because
liveness never depended on the database, and recovers to ready automatically the moment the database
comes back — no manual pod restart needed.
Security context
The container must start as uid 0 — not optional, and a hardened securityContext that forbids it
fails at startup with “the container must start as root”. This is a brief, structural requirement, not
a lingering one: the entrypoint uses that first moment as root to fix ownership on the two mounted
volumes above (a fresh PVC is root-owned by default), then immediately hands off to an unprivileged
node user via gosu before any application code runs. The process that actually serves traffic never
runs as root.
The image also carries no wget or curl — its own healthcheck and chart tests use node -e with
Node’s built-in fetch() instead, confirmed by a real helm test run rather than assumed from the
Dockerfile.
Resource sizing
Numbers below are measured against a running instance, not estimated:
| State | CPU | Memory |
|---|---|---|
| Idle | low | ~770–820 MiB RSS |
| Indexing burst | ~10 cores for 2–3 seconds | — |
| Cold start | first model load (download + init) ~72.4s | — |
Set resources.requests/resources.limits with headroom over the idle figure and enough burst capacity
for indexing spikes; a tight CPU limit during a burst slows a single indexing run rather than affecting
other pods, since there is only ever the one replica.
A git source adds its own peak: the git library holds a pack in memory and copies it twice, so one fetch can use
about twice config.gitMaxPackBytes (512 MiB at the default of 256 MiB) on top of the idle figure, and parsing
adds more. If you raise config.gitMaxPackBytes for a large repository, raise resources.limits.memory with it and
keep the limit well above twice the new value plus the idle footprint (see
Git Repository Source). Available from 0.3.2.
Uninstalling
helm uninstall leaves the two PersistentVolumeClaims behind by default — they carry a
helm.sh/resource-policy: keep annotation, so uploaded files, checkouts and the cached model survive an accidental
uninstall (persistence.retainOnUninstall: false turns that off). The index itself lives in your external PostgreSQL, which helm uninstall never touches. The SECRET_KEY Secret carries no such policy and is deleted with the release; if you
plan to reinstall against the same data, save the key first (see
SECRET_KEY: generated once, held stable above) or you will not
be able to decrypt the source credentials the surviving PVCs still reference.
Metrics and the ServiceMonitor
GET /metrics is served on the application port and is not public. With the Prometheus Operator’s CRDs
in the cluster, set metrics.serviceMonitor.enabled: true to have the chart render a ServiceMonitor;
interval (default 30s), scrapeTimeout (default 10s, never above interval — the chart refuses
to render otherwise) and labels (typically what your Prometheus serviceMonitorSelector matches,
e.g. release: kube-prometheus-stack) sit beside it.
The scrape needs a credential. Put it in envSecret.METRICS_TOKEN — the same Secret entry that sets
METRICS_TOKEN in the Pod, at least 16 characters — or set env.METRICS_PUBLIC: "1" on a network you
trust. With neither, every scrape is answered 401. See Configuration.
Strict values schema
The chart validates its values against a strict JSON Schema — an unrecognized key fails
helm install/helm upgrade immediately rather than being silently ignored. One key worth knowing by
name because it is easy to reach for under the wrong path: config.mcpStructuredOutput is a typed, top-level
config.* key, not a freeform value nested somewhere else. The same goes for config.webAllowedHosts and config.gitAllowedHosts, the allowlists
of the web and git sources: each is a list of host names, and a source that reads an internal host needs
its host listed there (see Documentation Site Source and
Git Repository Source).
config.mcpReportGapPerHour is a typed key of the same kind: an integer of at least 0, set as
MCP_REPORT_GAP_PER_HOUR, the number of report_gap reports one MCP credential may have accepted per hour (see
MCP Tools). Left unset, the application default of 20 applies; 0 turns
the limit off.
Chart 2.1.0, which ships with application 0.6.0, adds typed config.* keys for the settings of the new sources:
config.sourceAllowedHosts (SOURCE_ALLOWED_HOSTS, the allowlist for Confluence, S3 and GitHub Enterprise Server hosts),
config.s3MaxObjects, config.gdriveMaxFiles, config.githubMaxIssues and config.githubMaxDiscussions (integers from
1 to 100 000; null, the default, leaves the application default of 5 000), and config.oidcGroupsClaim
(OIDC_GROUPS_CLAIM, see Single Sign-On). Chart 2.2.0, which ships with application 0.7.0, adds config.piiScan (PII_SCAN; true, the default, leaves it unset
and the scan on, false turns new scanning off), config.confluenceMaxPages and config.notionMaxPages
(CONFLUENCE_MAX_PAGES, NOTION_MAX_PAGES; integers from 1 to 100 000, null leaves the application default of 5 000)
and the Notion OAuth keys config.notionOauthClientId, config.notionOauthRedirectUri and config.notionOauthClientSecret.
The secret is not a value but a reference, { secretName, secretKey }, to a Secret you manage; the schema refuses one of
the two alone. Alternatively pass NOTION_OAUTH_CLIENT_SECRET through envSecret, but not both. See
Notion.
Upgrading to chart 3.0.0
Chart 3.0.0, which ships with application 1.0.0, is a major version because the schema now rejects a key it used to
accept: config.confluenceAllowedHosts, deprecated since 0.6.0 and removed together with the application’s
CONFLUENCE_ALLOWED_HOSTS. helm upgrade stops on the old key before anything changes. If your values set it, move
its hosts to config.sourceAllowedHosts — which Confluence, S3 and GitHub Enterprise Server sources share — and delete
the old key; the chart’s own README has the full upgrade notes. The compatibility policy that governs chart values is
in docs/compatibility.md.
Publishing
Chart releases follow the repository’s own release workflow and are published to a gh-pages-hosted Helm
repository, versioned independently of the application’s own version — see the chart’s own
charts/contextator/README.md in the repository for the exact release and versioning rules.