Helm Deployment

Deploy Context7 On-Premise on Kubernetes with the Helm chart

The Context7 Helm chart is the turnkey way to run Context7 On-Premise on Kubernetes. It renders a single-replica StatefulSet by default and switches to a multi-replica Deployment when you enable scaling, so the same chart covers both the standard install and horizontal scaling. The chart ships with the enterprise distribution.

This guide assumes you have completed the On-Premise setup and have a valid license key.

Prerequisites

• A Kubernetes cluster (v1.24+) and helm (v3+).
• A Context7 license key.
• An image pull secret for ghcr.io. Create it with the steps in Registry Authentication, which produces a context7-registry secret in the context7 namespace.

Single container (default)

Runs one replica with the embedded database on a persistent volume. Nothing external is required.

helm install context7 ./context7-enterprise \
  --namespace context7 --create-namespace \
  --set license=ctx7sk-... \
  --set 'imagePullSecrets[0].name=context7-registry'

Reach the UI to finish setup:

kubectl -n context7 port-forward svc/context7-context7-enterprise 3000:3000

Then open http://localhost:3000.

Multiple replicas

Provision an external PostgreSQL with the pgvector extension first (relational data and embeddings both live there, no object storage needed). See Scaling for the architecture and how to provision pgvector.

helm install context7 ./context7-enterprise \
  --namespace context7 --create-namespace \
  --set license=ctx7sk-... \
  --set 'imagePullSecrets[0].name=context7-registry' \
  --set scaling.enabled=true \
  --set scaling.replicas=3 \
  --set scaling.databaseUrl='postgres://user:pass@host:5432/context7' \
  --set scaling.encryptionKey=$(openssl rand -hex 32)

encryptionKey is the one shared secret every replica needs. It decrypts stored credentials and signs session tokens, so keep it identical across replicas and stable over time. If it changes, stored credentials can no longer be decrypted and all sessions are invalidated.

With scaling.enabled=true the chart runs a Deployment of stateless replicas whose readiness gates on /api/ready, so a pod only receives traffic once it has connected to Postgres.

Ingress

Expose the service through an Ingress instead of port-forwarding:

helm upgrade context7 ./context7-enterprise --namespace context7 --reuse-values \
  --set ingress.enabled=true \
  --set ingress.className=nginx \
  --set ingress.host=context7.internal.example.com \
  --set ingress.tls.enabled=true \
  --set ingress.tls.secretName=context7-tls

Migrating an existing single-container install

To move an existing single-container deployment onto Postgres, the chart runs a one-shot migration Job that copies your SQLite data (and the LanceDB index into pgvector) from the volume your container used.

1. Point the Job at your existing data

   Set migration.enabled=true and migration.dataPvcName to the PVC that holds your existing /data, and set scaling.encryptionKey to the key your single container used.

   helm upgrade context7 ./context7-enterprise --namespace context7 --reuse-values \
     --set scaling.enabled=true \
     --set scaling.databaseUrl='postgres://user:pass@host:5432/context7' \
     --set scaling.encryptionKey='<your-existing-key>' \
     --set migration.enabled=true \
     --set migration.dataPvcName=context7-data
   
2. Turn the Job off after it completes

   Once the Job reports success, disable it so it does not run again on the next upgrade.

   helm upgrade context7 ./context7-enterprise --namespace context7 --reuse-values \
     --set migration.enabled=false
   

See Migrating an existing deployment for what the migration copies and how to verify it.

Values

Value	Default	Description
license	""	Context7 license key. Required.
imagePullSecrets	[]	Pull secrets for ghcr.io, for example context7-registry.
scaling.enabled	false	false runs a single-replica StatefulSet; true runs a multi-replica Deployment.
scaling.replicas	3	Replica count when scaling is enabled.
scaling.databaseUrl	""	External Postgres (with pgvector). Required when scaling is enabled.
scaling.encryptionKey	""	Shared secret, identical across replicas. Required when scaling is enabled.
persistence.storage	10Gi	Volume size for the single-replica default.
persistence.storageClass	""	StorageClass for the single-replica volume.
ingress.enabled	false	Create an Ingress for the service.
resources	1-4 CPU / 2-8Gi	Pod resource requests and limits.
env	[]	Extra environment (LLM, embedding, and git credentials, or advanced overrides).
migration.enabled	false	Run the one-shot SQLite to Postgres migration Job.
migration.dataPvcName	""	PVC holding the existing /data to migrate from.

Any credential can also be configured in the UI after first boot, so env is only needed when you prefer to set them declaratively.