> ## Documentation Index
> Fetch the complete documentation index at: https://context7-ctx7-1846-helm-manifests.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/enterprise/on-premise) 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](/enterprise/deployment/kubernetes#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.

```bash theme={null}
helm install context7 ./context7-enterprise \
  --namespace context7 --create-namespace \
  --set license=ctx7sk-... \
  --set 'imagePullSecrets[0].name=context7-registry'
```

Reach the UI to finish setup:

```bash theme={null}
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](/enterprise/deployment/scaling) for the architecture and how to provision pgvector.

```bash theme={null}
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)
```

<Note>
  `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.
</Note>

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:

```bash theme={null}
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.

<Steps>
  <Step title="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.

    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Turn the Job off after it completes">
    Once the Job reports success, disable it so it does not run again on the next upgrade.

    ```bash theme={null}
    helm upgrade context7 ./context7-enterprise --namespace context7 --reuse-values \
      --set migration.enabled=false
    ```
  </Step>
</Steps>

See [Migrating an existing deployment](/enterprise/deployment/scaling#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.