Skip to content

Context7 Platform -- Up-to-date docs for AI agents

docs(enterprise): multi-container scaling guide (#2917)

Fahreddin Özcan305dd3ca1034
diff --git a/docs/docs.json b/docs/docs.json
index b87f0049..0aba9113 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -93,7 +93,9 @@
"group": "Deployment",
"pages": [
"enterprise/deployment/docker",
- "enterprise/deployment/kubernetes"
+ "enterprise/deployment/kubernetes",
+ "enterprise/deployment/scaling",
+ "enterprise/deployment/vector-stores"
]
},
{
diff --git a/docs/enterprise/deployment/docker.mdx b/docs/enterprise/deployment/docker.mdx
index 376dcc57..0cd7aa3c 100644
--- a/docs/enterprise/deployment/docker.mdx
+++ b/docs/enterprise/deployment/docker.mdx
@@ -126,6 +126,12 @@ Example response:
}
```
+## Scaling
+
+The setup above runs a single container with a local volume, which suits most deployments. To run multiple replicas behind a load balancer, move state to an external PostgreSQL (embeddings included, via the `pgvector` extension), so every replica is stateless and interchangeable. A turnkey multi-replica Compose file (app replicas + Nginx load balancer) ships in the deployment bundle.
+
+See [Scaling](/enterprise/deployment/scaling) for the full setup, which also covers migrating an existing single-container deployment.
+
## Connecting AI Clients
Once deployed, point your MCP clients to your deployment URL. See [Connecting Your AI Client](/enterprise/on-premise#connecting-your-ai-client) for client-specific instructions.
diff --git a/docs/enterprise/deployment/kubernetes.mdx b/docs/enterprise/deployment/kubernetes.mdx
index 4643dc75..cd048510 100644
--- a/docs/enterprise/deployment/kubernetes.mdx
+++ b/docs/enterprise/deployment/kubernetes.mdx
@@ -46,7 +46,7 @@ Context7 Enterprise runs as a single-replica StatefulSet with persistent storage
### StatefulSet
-Context7 uses SQLite and LanceDB for local storage, which require a persistent volume. This means it must run as a **StatefulSet with a single replica** since SQLite does not support concurrent writers.
+Context7 uses SQLite and LanceDB for local storage, which require a persistent volume. This means it must run as a **StatefulSet with a single replica** since SQLite does not support concurrent writers. To run multiple replicas, move state to PostgreSQL (with the `pgvector` extension for embeddings) as described in [Scaling](/enterprise/deployment/scaling).
```yaml statefulset.yaml
apiVersion: apps/v1
@@ -132,7 +132,7 @@ spec:
</Note>
<Warning>
- Do not set `replicas` higher than 1. Context7 uses SQLite which only supports a single writer. Running multiple replicas will cause database lock errors.
+ Do not set `replicas` higher than 1 in this configuration. Context7 uses SQLite which only supports a single writer, so running multiple replicas causes database lock errors. To scale out, see [Scaling](/enterprise/deployment/scaling).
</Warning>
### Service
@@ -336,6 +336,18 @@ Look for `[license]` messages in the first few lines. Common causes:
The startup probe only comes into play after the license is validated. If the pod is crash-looping, the issue is always upstream of the probe. Check logs, not probe events.
</Note>
+## Scaling
+
+The manifests above run a single replica: a StatefulSet with a `ReadWriteOnce` volume holding the embedded SQLite database and LanceDB index. This suits most deployments.
+
+To run multiple replicas behind the Service, move that state to an external PostgreSQL with the `pgvector` extension. Relational data and embeddings both live in Postgres, so every pod becomes stateless and interchangeable: swap the StatefulSet for a `Deployment` with `replicas` greater than one, mount `/data` as scratch (`emptyDir`), and gate readiness on `/api/ready` so a pod only receives traffic once it has connected to Postgres.
+
+<Note>
+A Helm chart renders all of this from a few values: the single-replica StatefulSet by default, or a multi-replica Deployment with `scaling.enabled=true`. It ships with the enterprise distribution.
+</Note>
+
+See [Scaling](/enterprise/deployment/scaling) for the full setup, PostgreSQL and pgvector provisioning, and migrating an existing single-container deployment.
+
## Connecting AI Clients
Once deployed, point your MCP clients to your Ingress URL. See [Connecting Your AI Client](/enterprise/on-premise#connecting-your-ai-client) for client-specific instructions. Replace `localhost:3000` with your Kubernetes Ingress hostname.
diff --git a/docs/enterprise/deployment/scaling.mdx b/docs/enterprise/deployment/scaling.mdx
new file mode 100644
index 00000000..556b6adf
--- /dev/null
+++ b/docs/enterprise/deployment/scaling.mdx
@@ -0,0 +1,433 @@
+---
+title: "Scaling"
+sidebarTitle: "Scaling"
+description: "Run Context7 On-Premise as multiple replicas behind a load balancer"
+---
+
+By default Context7 On-Premise runs as a single container. It stores everything on a local volume: a SQLite database for configuration and metadata, and a LanceDB index for embeddings. This is simple to operate but limits you to one instance, since SQLite does not support concurrent writers across containers.
+
+To run multiple replicas behind a load balancer, move that state to PostgreSQL. Relational data goes to Postgres, and vectors go to Postgres too via the `pgvector` extension. Once state is external, every replica is stateless and interchangeable, and you can scale horizontally. Postgres is the only external dependency, there is no separate vector database or object storage to run.
+
+If you already run Milvus or Zilliz Cloud, you can send vectors there instead of pgvector. See [Vector stores](/enterprise/deployment/vector-stores) for all the options; this page uses the default pgvector setup throughout.
+
+<Note>
+You only need this if a single container can no longer handle your query or indexing load. Most deployments run fine on one container with a persistent volume. See [Docker](/enterprise/deployment/docker) and [Kubernetes](/enterprise/deployment/kubernetes) for the standard single-container setup.
+</Note>
+
+## Architecture
+
+Every replica runs the full application (REST API, MCP endpoint, and parser) and is interchangeable. All shared state lives in PostgreSQL, so a load balancer can spread traffic across any number of replicas.
+
+```mermaid
+flowchart TB
+ clients["MCP clients<br/>and browsers"] --> lb["Load balancer"]
+ lb --> r1["Replica 1"]
+ lb --> r2["Replica 2"]
+ lb --> r3["Replica 3"]
+ r1 --> pg[("PostgreSQL<br/>+ pgvector")]
+ r2 --> pg
+ r3 --> pg
+
+ classDef client fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a;
+ classDef replica fill:#ede9fe,stroke:#8b5cf6,color:#5b21b6;
+ classDef db fill:#dcfce7,stroke:#16a34a,color:#166534;
+ class clients,lb client;
+ class r1,r2,r3 replica;
+ class pg db;
+```
+
+Replicas coordinate through Postgres: they pull indexing jobs from a shared queue, run jobs that must happen once (backups, usage reporting, GitOps sync) on a single replica using a Postgres lock, and validate each other's signed session tokens. See [How it behaves](#how-it-behaves) for the details.
+
+## What you need
+
+- A **PostgreSQL** database (managed or self-hosted) with the **pgvector** extension, reachable from every replica. Managed Postgres such as RDS, Cloud SQL, and Azure support pgvector; for self-hosted use the `pgvector/pgvector` image. To keep vectors in Milvus or Zilliz Cloud instead, see [Vector stores](/enterprise/deployment/vector-stores).
+- A **load balancer** in front of the replicas.
+
+The embedded SQLite and LanceDB are not used once `DATABASE_URL` is set.
+
+## Configuration
+
+Set the same values on every replica. Presence of `DATABASE_URL` is what switches the store from SQLite to Postgres and vectors to pgvector.
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `DATABASE_URL` | Yes | PostgreSQL connection string, for example `postgres://user:pass@host:5432/context7`. Enables multi-replica mode; vectors go to pgvector in this database. |
+| `ENCRYPTION_KEY` | Yes | 64 hex characters, shared by all replicas so they can decrypt the same stored credentials and validate each other's session tokens. Generate with `openssl rand -hex 32`. |
+| `PG_POOL_MAX` | No | PostgreSQL connections per replica. Defaults to `10`. |
+
+<Warning>
+`ENCRYPTION_KEY` must be identical on every replica and must stay stable. If it changes, stored credentials can no longer be decrypted and all sessions are invalidated. Store it in your secret manager.
+</Warning>
+
+## Enable it
+
+<Steps>
+
+<Step title="Provision PostgreSQL with pgvector">
+
+Context7 stores vectors with [pgvector](https://github.com/pgvector/pgvector). You need PostgreSQL 13 or newer with pgvector **0.5.0 or newer** (0.5.0 added the HNSW index used for similarity search).
+
+On first boot Context7 runs `CREATE EXTENSION IF NOT EXISTS vector` and creates its tables and indexes automatically. You just provide a database whose user is allowed to create the extension. On managed Postgres that usually means enabling pgvector for the instance first, then connecting with a privileged role.
+
+<Tabs>
+
+<Tab title="AWS RDS / Aurora">
+
+pgvector ships with RDS and Aurora PostgreSQL. Connect as the master user (or a member of `rds_superuser`) and enable it:
+
+```sql
+CREATE EXTENSION vector;
+```
+
+No parameter group changes are required. See [pgvector on Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_PostgreSQL.html).
+
+</Tab>
+
+<Tab title="Google Cloud SQL">
+
+pgvector is supported on Cloud SQL for PostgreSQL. Connect as a user with the `cloudsqlsuperuser` role and enable it:
+
+```sql
+CREATE EXTENSION vector;
+```
+
+See [Cloud SQL extensions](https://cloud.google.com/sql/docs/postgres/extensions).
+
+</Tab>
+
+<Tab title="Azure Flexible Server">
+
+Allowlist the extension first: add `VECTOR` to the `azure.extensions` server parameter, then connect and enable it:
+
+```sql
+CREATE EXTENSION vector;
+```
+
+See [pgvector on Azure Database for PostgreSQL](https://learn.microsoft.com/azure/postgresql/flexible-server/how-to-use-pgvector).
+
+</Tab>
+
+<Tab title="Self-hosted / Docker">
+
+Use the official image, which bundles pgvector:
+
+```bash
+docker run -d --name postgres \
+ -e POSTGRES_PASSWORD=... -e POSTGRES_DB=context7 \
+ -p 5432:5432 --shm-size=1g \
+ pgvector/pgvector:pg16
+```
+
+For an existing server, install the extension package (`apt-get install postgresql-16-pgvector` on Debian/Ubuntu) or build from source, then run `CREATE EXTENSION vector;`. See [pgvector installation](https://github.com/pgvector/pgvector#installation). Set `--shm-size` at least as large as `maintenance_work_mem` so parallel HNSW index builds do not run out of shared memory.
+
+</Tab>
+
+</Tabs>
+
+Verify the installed version (must be `0.5.0` or newer):
+
+```sql
+SELECT extversion FROM pg_extension WHERE extname = 'vector';
+```
+
+<Note>
+If the application's database user cannot run `CREATE EXTENSION` (common on locked-down managed instances), have a DBA run it once as a privileged role before you start Context7. Once the extension exists, the app user only needs normal table privileges.
+</Note>
+
+</Step>
+
+<Step title="Generate the shared secrets">
+
+```bash
+openssl rand -hex 32 # ENCRYPTION_KEY
+```
+
+</Step>
+
+<Step title="Set the environment on every replica">
+
+Add `DATABASE_URL` and `ENCRYPTION_KEY` to each replica, alongside the usual `LICENSE_KEY` and model settings.
+
+</Step>
+
+<Step title="Point health checks at /api/ready">
+
+Configure your load balancer or orchestrator readiness check to use `GET /api/ready`. It returns `200` only when the replica can reach the database and its MCP bridge is up, so traffic is routed only to replicas that are ready.
+
+</Step>
+
+<Step title="Scale out">
+
+Start as many replicas as you need behind the load balancer. Every replica is identical: it serves API, MCP, and search traffic **and** pulls parse jobs from the shared queue, so adding replicas grows both query capacity and indexing throughput at once. Work is distributed automatically and no replica is special.
+
+If a large re-index competes with query latency on a replica, lower **Max concurrent parses** (Settings > Indexing) so each replica runs fewer parses at a time, or give replicas more CPU and memory.
+
+</Step>
+
+</Steps>
+
+## Docker Compose
+
+For evaluation and small deployments, this stack brings up Postgres (with pgvector), three app replicas, and an nginx load balancer with one command. There is no object storage to run.
+
+Create a `.env`:
+
+```bash
+LICENSE_KEY=ctx7sk-...
+POSTGRES_PASSWORD=change-me
+# openssl rand -hex 32
+ENCRYPTION_KEY=
+```
+
+Create `nginx.conf` (round-robins across the replicas):
+
+```nginx
+events {}
+http {
+ resolver 127.0.0.11 valid=10s ipv6=off;
+ server {
+ listen 80;
+ location / {
+ set $backend http://app:3000;
+ proxy_pass $backend;
+ proxy_http_version 1.1;
+ proxy_set_header Host $host;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ }
+ }
+}
+```
+
+Create `docker-compose.yml`:
+
+```yaml
+services:
+ postgres:
+ image: pgvector/pgvector:pg16
+ environment:
+ POSTGRES_USER: context7
+ POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+ POSTGRES_DB: context7
+ volumes: [pgdata:/var/lib/postgresql/data]
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U context7"]
+ interval: 5s
+ timeout: 5s
+ retries: 10
+
+ app:
+ image: ghcr.io/context7/enterprise:latest
+ depends_on:
+ postgres: { condition: service_healthy }
+ environment:
+ LICENSE_KEY: ${LICENSE_KEY}
+ DATABASE_URL: postgres://context7:${POSTGRES_PASSWORD}@postgres:5432/context7
+ ENCRYPTION_KEY: ${ENCRYPTION_KEY}
+ deploy: { replicas: 3 }
+
+ lb:
+ image: nginx:alpine
+ depends_on: [app]
+ ports: ["3000:80"]
+ volumes: ["./nginx.conf:/etc/nginx/nginx.conf:ro"]
+
+volumes:
+ pgdata:
+```
+
+Then start it and open `http://localhost:3000` to complete the setup wizard:
+
+```bash
+docker compose up -d
+```
+
+For production, point `DATABASE_URL` at an external managed Postgres (with pgvector) and drop the `postgres` service.
+
+## Kubernetes
+
+This assumes you created the namespace and image pull secret in the [Kubernetes guide](/enterprise/deployment/kubernetes). Put the shared configuration in a Secret:
+
+```yaml secret.yaml
+apiVersion: v1
+kind: Secret
+metadata:
+ name: context7-env
+ namespace: context7
+type: Opaque
+stringData:
+ LICENSE_KEY: "ctx7sk-..."
+ DATABASE_URL: "postgres://user:pass@host:5432/context7"
+ ENCRYPTION_KEY: "<64 hex, openssl rand -hex 32>"
+```
+
+Run the app as a `Deployment` instead of the single-replica StatefulSet. State is external, so `/data` is per-pod scratch and readiness gates on `/api/ready`:
+
+```yaml deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: context7
+ namespace: context7
+spec:
+ replicas: 3
+ selector: { matchLabels: { app: context7 } }
+ template:
+ metadata: { labels: { app: context7 } }
+ spec:
+ imagePullSecrets:
+ - name: context7-registry
+ containers:
+ - name: context7
+ image: ghcr.io/context7/enterprise:latest
+ ports:
+ - { containerPort: 3000, name: http }
+ env:
+ - { name: DATA_DIR, value: /data }
+ envFrom:
+ - secretRef: { name: context7-env }
+ volumeMounts:
+ - { name: data, mountPath: /data }
+ readinessProbe:
+ httpGet: { path: /api/ready, port: http }
+ periodSeconds: 10
+ livenessProbe:
+ httpGet: { path: /api/health, port: http }
+ periodSeconds: 30
+ volumes:
+ - name: data
+ emptyDir: {}
+```
+
+Reuse the `Service` and `Ingress` from the [Kubernetes guide](/enterprise/deployment/kubernetes), then apply:
+
+```bash
+kubectl apply -f secret.yaml
+kubectl apply -f deployment.yaml
+```
+
+<Note>
+A Helm chart renders all of this from a few values (single replica by default, `scaling.enabled=true` to scale out) and ships with the enterprise distribution.
+</Note>
+
+## How it behaves
+
+- **Shared work queue.** All replicas pull parse jobs from the same queue in PostgreSQL, so indexing throughput scales with replica count.
+- **Single execution for scheduled jobs.** Jobs that must run once across the fleet, such as the usage report, scheduled backups, and GitOps sync, take a short Postgres advisory lock when they fire, so exactly one replica runs each. No replica is special, and there is nothing to fail over.
+- **Stateless sessions.** Sessions are signed tokens, so any replica accepts a login issued by another, and logins survive restarts.
+- **Vectors in Postgres.** Embeddings are stored with pgvector, indexed with HNSW using cosine distance. The vector dimension is taken from your embedding model on first write, so there is no manual schema setup and switching embedding models is a re-index, not a migration. To store vectors in Milvus or Zilliz Cloud instead, see [Vector stores](/enterprise/deployment/vector-stores).
+
+## Migrating an existing deployment
+
+If you already run a single container, a built-in command copies your existing SQLite data and LanceDB vectors into PostgreSQL, so you do not have to re-index your libraries or re-embed anything. It reads the data directory from your single container and writes to the target PostgreSQL.
+
+The admin UI shows your current storage mode and the exact migration command under **Settings > Scaling**:
+
+<Frame>
+ ![Migration helper under Settings, Scaling](/images/scaling-settings.png)
+</Frame>
+
+<Warning>
+Run the migration during a maintenance window. Stop indexing and let in-flight parses finish first, then run the migration against a quiet database. In-flight parse jobs are not migrated.
+</Warning>
+
+<Steps>
+
+<Step title="Provision PostgreSQL with pgvector">
+
+Create the target PostgreSQL database with pgvector, the same way as in [Enable it](#enable-it) above. The schema, extension, and vector tables are created automatically.
+
+</Step>
+
+<Step title="Run the migration">
+
+Run the one-shot `migrate` command with access to your existing data directory and the target database. It creates the schema and copies your projects, pages, users, API keys, per-library access rules, SSO group memberships, settings, usage counters, and the vector index into pgvector.
+
+<Tabs>
+
+<Tab title="Docker">
+
+```bash
+docker run --rm \
+ -v context7-data:/data \
+ -e DATA_DIR=/data \
+ -e DATABASE_URL="postgres://user:pass@host:5432/context7" \
+ ghcr.io/context7/enterprise:latest \
+ node dist/enterprise/migrate.mjs
+```
+
+Use the same volume (`context7-data`) your single container uses, so the command reads your existing database and vectors.
+
+</Tab>
+
+<Tab title="Kubernetes">
+
+Run it as a `Job` that mounts the existing data volume:
+
+```yaml migrate-job.yaml
+apiVersion: batch/v1
+kind: Job
+metadata:
+ name: context7-migrate
+ namespace: context7
+spec:
+ template:
+ spec:
+ restartPolicy: Never
+ imagePullSecrets:
+ - name: context7-registry
+ containers:
+ - name: migrate
+ image: ghcr.io/context7/enterprise:latest
+ command: ["node", "dist/enterprise/migrate.mjs"]
+ env:
+ - name: DATA_DIR
+ value: /data
+ - name: DATABASE_URL
+ value: postgres://user:pass@host:5432/context7
+ volumeMounts:
+ - name: data
+ mountPath: /data
+ volumes:
+ - name: data
+ persistentVolumeClaim:
+ claimName: data-context7-0
+```
+
+```bash
+kubectl apply -f migrate-job.yaml
+kubectl logs -n context7 job/context7-migrate
+```
+
+</Tab>
+
+</Tabs>
+
+The command prints the rows and vectors copied, and the `ENCRYPTION_KEY` your new deployment must use.
+
+</Step>
+
+<Step title="Reuse the encryption key">
+
+Your stored credentials are encrypted with the key from the single container. Set `ENCRYPTION_KEY` on the new deployment to the value the migration command printed, so credentials stay readable.
+
+</Step>
+
+<Step title="Redeploy in multi-replica mode">
+
+Redeploy with `DATABASE_URL` and `ENCRYPTION_KEY` set on every replica, following the steps above. Verify at `/api/health` that your libraries are present, then scale up.
+
+</Step>
+
+</Steps>
+
+After redeploying, **Settings > Scaling** confirms the deployment is running in multi-replica mode:
+
+<Frame>
+ ![Multi-replica mode confirmed](/images/scaling-multi-replica.png)
+</Frame>
+
+## Limitations
+
+- With pgvector, vector search runs in Postgres. For typical on-prem workloads this is well within reach; for a very large index, size Postgres accordingly.
+- Database backups are handled by PostgreSQL in this mode. Use your provider's managed backups or `pg_dump` rather than the built-in backup, which targets the embedded SQLite file. See [Backup and Restore](/enterprise/backup-restore).
diff --git a/docs/enterprise/deployment/vector-stores.mdx b/docs/enterprise/deployment/vector-stores.mdx
new file mode 100644
index 00000000..b515ce48
--- /dev/null
+++ b/docs/enterprise/deployment/vector-stores.mdx
@@ -0,0 +1,108 @@
+---
+title: "Vector Stores"
+sidebarTitle: "Vector Stores"
+description: "Choose where Context7 On-Premise stores embeddings: embedded LanceDB, pgvector, or Milvus"
+---
+
+Context7 stores every library's embeddings in a vector store and searches it on each query. The store is chosen independently of the relational database, so you can keep configuration and metadata in one place and send vectors somewhere else ("bring your own store"). This page covers the three backends and how to configure each.
+
+<Note>
+Most single-container deployments need nothing here. The default embedded store works out of the box. You only need to change the vector store to run multiple replicas or to reuse a vector database you already operate.
+</Note>
+
+## Options
+
+| Store | Best for | Runs where | Configuration |
+| --- | --- | --- | --- |
+| **LanceDB** (default) | Single container | Embedded in the container's data volume | None |
+| **pgvector** | Multiple replicas, already running PostgreSQL | Your PostgreSQL, the same database as the relational data or a separate one | `DATABASE_URL` or `VECTOR_DATABASE_URL` |
+| **Milvus** | Multiple replicas with an existing Milvus / Zilliz Cloud, or very large indexes | An external Milvus cluster or Zilliz Cloud | `MILVUS_*` |
+
+The embedded LanceDB index is local to one container, so it cannot back multiple replicas. To [scale out](/enterprise/deployment/scaling) you need a shared store: pgvector or Milvus.
+
+## Selecting a store
+
+`VECTOR_STORE` picks the backend:
+
+| Value | Behavior |
+| --- | --- |
+| `auto` (default) | pgvector when a PostgreSQL URL is available for vectors, otherwise embedded LanceDB. |
+| `lancedb` | Embedded local index. |
+| `pgvector` | pgvector in PostgreSQL. Requires a Postgres `VECTOR_DATABASE_URL` (or `DATABASE_URL`). |
+| `milvus` | External Milvus or Zilliz Cloud. Requires `MILVUS_ADDRESS`. |
+
+With `auto`, setting `DATABASE_URL` to a Postgres connection (the multi-replica setup) automatically stores vectors in pgvector in that same database. You only set `VECTOR_STORE` explicitly to override that, for example to keep vectors in Milvus while the relational data lives in Postgres.
+
+Whatever the store, the collection or table is created on first write, the vector dimension is taken from your embedding model, and search uses an HNSW index with cosine similarity. There is no manual schema setup, and switching embedding models is a re-index rather than a migration.
+
+## pgvector
+
+pgvector stores embeddings in PostgreSQL alongside (or beside) your relational data. In the standard multi-replica setup vectors share the relational database, so there is nothing extra to configure. See [Scaling](/enterprise/deployment/scaling#enable-it) for the full provisioning guide, including managed Postgres (RDS, Cloud SQL, Azure) and self-hosted.
+
+| Variable | Description |
+| --- | --- |
+| `VECTOR_DATABASE_URL` | PostgreSQL DSN for vectors. Defaults to `DATABASE_URL`, so vectors share the relational database. Set it to point vectors at a **separate** pgvector service. The target needs the `pgvector` extension. |
+
+<Note>
+Use `VECTOR_DATABASE_URL` when you want vectors in a dedicated pgvector instance, for example to size and scale vector storage independently of the relational database.
+</Note>
+
+## Milvus
+
+Set `VECTOR_STORE=milvus` to store embeddings in an external [Milvus](https://milvus.io/) cluster or [Zilliz Cloud](https://zilliz.com/cloud). Context7 creates its collections (HNSW, cosine) on first write. Milvus **2.4 or newer** is required.
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `MILVUS_ADDRESS` | Yes | Cluster endpoint, for example `milvus:19530` or `https://your-cluster.zillizcloud.com`. |
+| `MILVUS_TOKEN` | | API-key authentication, used by Zilliz Cloud and token-secured clusters. |
+| `MILVUS_USERNAME` | | Username for a self-hosted cluster with user/password auth. |
+| `MILVUS_PASSWORD` | | Password to go with `MILVUS_USERNAME`. |
+| `MILVUS_DATABASE` | | Milvus database name. Defaults to the server default. |
+
+Use `MILVUS_TOKEN` for Zilliz Cloud and API-key clusters, or `MILVUS_USERNAME` + `MILVUS_PASSWORD` for a self-hosted cluster with username/password auth.
+
+<Tabs>
+
+<Tab title="Zilliz Cloud">
+
+Take the public endpoint and API key from your Zilliz Cloud cluster, then set:
+
+```bash
+VECTOR_STORE=milvus
+MILVUS_ADDRESS=https://your-cluster.zillizcloud.com
+MILVUS_TOKEN=<api-key>
+```
+
+</Tab>
+
+<Tab title="Self-hosted">
+
+For evaluation, bring up a standalone Milvus with the official script:
+
+```bash
+curl -sfL https://raw.githubusercontent.com/milvus-io/milvus/master/scripts/standalone_embed.sh -o standalone_embed.sh
+bash standalone_embed.sh start
+```
+
+Then point Context7 at it:
+
+```bash
+VECTOR_STORE=milvus
+MILVUS_ADDRESS=localhost:19530
+```
+
+If the cluster has authentication enabled, add `MILVUS_TOKEN`, or `MILVUS_USERNAME` and `MILVUS_PASSWORD`. For production, follow the [Milvus install guide](https://milvus.io/docs/install_standalone-docker.md) or run it on Kubernetes with the Milvus Operator.
+
+</Tab>
+
+</Tabs>
+
+<Warning>
+Milvus stores `text` and `metadata` as `VARCHAR`, capped at 65,535 characters. This is well above normal chunk sizes, but an unusually large single chunk will be rejected on insert.
+</Warning>
+
+## Which one to use
+
+- **Single container:** keep the default (LanceDB). No configuration, no external service.
+- **Multiple replicas, no existing vector database:** use pgvector. Vectors share the PostgreSQL you already need for [scaling](/enterprise/deployment/scaling), so there is nothing extra to run.
+- **You already run Milvus or Zilliz Cloud,** or you need a very large index managed separately from Postgres: use Milvus.
diff --git a/docs/images/scaling-multi-replica.png b/docs/images/scaling-multi-replica.png
new file mode 100644
index 00000000..bf6eea0f
Binary files /dev/null and b/docs/images/scaling-multi-replica.png differ
diff --git a/docs/images/scaling-settings.png b/docs/images/scaling-settings.png
new file mode 100644
index 00000000..a49c0af2
Binary files /dev/null and b/docs/images/scaling-settings.png differ