Scaling

​

Architecture

​

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.
• A load balancer in front of the replicas.

​

Configuration

​

Enable it

CREATE EXTENSION vector;

CREATE EXTENSION vector;

CREATE EXTENSION vector;

docker run -d --name postgres \
  -e POSTGRES_PASSWORD=... -e POSTGRES_DB=context7 \
  -p 5432:5432 --shm-size=1g \
  pgvector/pgvector:pg16

SELECT extversion FROM pg_extension WHERE extname = 'vector';

openssl rand -hex 32   # ENCRYPTION_KEY

​

Docker Compose

LICENSE_KEY=ctx7sk-...
POSTGRES_PASSWORD=change-me
# openssl rand -hex 32
ENCRYPTION_KEY=

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

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:

docker compose up -d

​

Kubernetes

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

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: {}

kubectl apply -f secret.yaml
kubectl apply -f deployment.yaml

​

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.

​

Migrating an existing deployment

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

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

kubectl apply -f migrate-job.yaml
kubectl logs -n context7 job/context7-migrate

​

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.