# Running on Kubernetes

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

- Updated: 2026-11-04
- Source: https://contextator.com/en/docs/kubernetes/
- Language: en-US
- Author: Muhammet Şafak

---
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

```bash
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](#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](/en/docs/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:

```bash
kubectl create secret generic contextator-secret-key \
  --from-literal=SECRET_KEY=$(openssl rand -hex 32)
```

```yaml
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:

```bash
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):

```bash
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}`:

```yaml
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:

```sh
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](/en/docs/configuration/#running-behind-a-reverse-proxy) 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](/en/docs/configuration/#running-behind-a-reverse-proxy) 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:

```yaml
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](/en/docs/git-repository-source/#how-large-a-response-may-be)). 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](#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](/en/docs/configuration/#observability).

## 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](/en/docs/documentation-site-source/) and
[Git Repository Source](/en/docs/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](/en/docs/mcp-tools/#report_gap)). 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](/en/docs/sso/)). 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](/en/docs/notion/#connect-with-notion-oauth).

### 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`](https://github.com/Contextator/Contextator/blob/main/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.
