Contextator
ENTR

Operating

Running on Kubernetes

Installing the Helm chart — database and SECRET_KEY handling, ingress, persistence, probes, security context, resource sizing and uninstalling.

Updated:

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.trustProxy to 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.

Arrow keys to move, Enter to open.