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:
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:
| Destination | Purpose |
|---|---|
ghcr.io | Image pulls |
context7.com | Online license only: license check, daily usage report, and public library search. See Network and data flow |
| Your LLM and embedding provider | AI inference and embeddings |
| Your Git hosts and documentation sources | Repository 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:
- Mount its PEM file.
- Set
NODE_EXTRA_CA_CERTSto 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.