Skip to main content

Deploy Context7 On-Premise with Docker Compose. This guide assumes you have completed the On-Premise setup and have a valid license key.

Prerequisites#

  • Docker and Docker Compose installed
  • Context7 license key

Registry Authentication#

Context7 Enterprise images are hosted on ghcr.io and require authentication. Log in using your license key:

Docker stores these credentials locally. docker compose will use them automatically when pulling the image. You can also pull manually:

Docker Compose#

Create a docker-compose.yml:

Warning

The context7-data volume is critical. It stores your SQLite database (configuration, credentials, indexed libraries) and all vector embeddings. Without a persistent volume, all data is lost when the container restarts or is recreated. Never run without a volume mount in production.

Create a .env file in the same directory:

Start the service:

Once the container is running, open http://localhost:3000 in your browser to complete the setup wizard.

Operations#

Updating#

If your registry login has expired, re-authenticate first:

Then pull the latest image and restart the container:

Data persists in the named Docker volume across updates.

Health Check#

Example response:

Each connectivity value is "configured" or "missing". github_method is "PAT", "GitHub App", or null.

/api/health is a liveness check. It still returns "healthy" when the database is down; repos_parsed and connectivity are then null.

To check that the instance can serve traffic, use GET /api/ready. It returns 200 when the database answers and the MCP bridge is up. Otherwise it returns 503.

Recover admin access#

If you lose the admin password, or a broken SSO setup locks you out, reset a local admin account from inside the container:

The command:

  • Sets the password of the local account, and creates the account if it does not exist.
  • Makes the account an enabled admin.
  • Signs the account out of its sessions.
  • Turns password sign-in back on.

Without --password <new>, it prints a generated password once. Passwords need at least 8 characters. The command does not work for a username that signs in with SSO.

Network Access#

Context7 needs outbound HTTPS to these destinations:

DestinationPurpose
ghcr.ioImage pulls
context7.comOnline license only: license check, daily usage report, and public library search. See Network and data flow
Your LLM and embedding providerAI inference and embeddings
Your Git hosts and documentation sourcesRepository cloning and website, Confluence, Notion, or Google Drive indexing

An offline license (ctx7off. prefix) is checked locally and makes no calls to context7.com. Per-user usage always stays on the instance.

To send these calls through an egress mirror, set CONTEXT7_API_URL (default https://context7.com/api).

The server does not use HTTP_PROXY or HTTPS_PROXY for its own calls. Allow this egress directly or through a transparent proxy.

If your network uses a private certificate authority:

  1. Mount its PEM file.
  2. Set NODE_EXTRA_CA_CERTS to the file’s path.

The whole server then trusts it, for every outbound call: AI providers, Bedrock, Confluence, Notion, Google, SSO identity providers, the license server, and Git.

GIT_TLS_INSECURE=true turns off TLS checks for all outbound HTTPS and Git calls. Use it only for testing.

Running as non-root#

The container runs as root by default. To run it unprivileged, pass --user. If the volume already holds files written by a root container, or the UID you choose cannot write /data, chown the volume to that UID first:

Any UID works. Everything Context7 writes lives under /data, including source clones (/data/repos) and documentation-agent state (/data/home). The only other path it writes is /tmp.

A new volume starts with /data owned by UID 10001 and group 0 and group-writable, so UID 10001 or any UID in group 0 needs no chown. If the UID cannot write /data, the server exits at startup with the path it could not write. This requires image 1.3.2 or later. On Kubernetes, use fsGroup instead and the kubelet handles the ownership: see Kubernetes.

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 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 for client-specific instructions.