Context7 Platform -- Up-to-date docs for AI agents
docs: document running on-premise as a non-root user (#3005)
Fahreddin Özcan895c5c399752
diff --git a/docs/enterprise/deployment/docker.mdx b/docs/enterprise/deployment/docker.mdxindex 0cd7aa3c..d1f352c9 100644--- a/docs/enterprise/deployment/docker.mdx+++ b/docs/enterprise/deployment/docker.mdx@@ -126,6 +126,25 @@ Example response:}```+## Running as non-root++The container runs as root by default. To run it unprivileged, chown the volume to the UID you want and pass `--user`:++```bash+docker run --rm -v context7-data:/data alpine chown -R 10001:10001 /data++docker run -d --name context7 \+ --user 10001:10001 \+ -v context7-data:/data \+ -e LICENSE_KEY="$LICENSE_KEY" \+ -p 3000:3000 \+ ghcr.io/context7/enterprise:latest+```++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`.++Skip the `chown` and the server exits at startup with the path it could not write. This requires image 1.4.0 or later. On Kubernetes, use `fsGroup` instead and the kubelet handles the ownership: see [Kubernetes](/enterprise/deployment/kubernetes#running-as-non-root).+## ScalingThe 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.diff --git a/docs/enterprise/deployment/kubernetes.mdx b/docs/enterprise/deployment/kubernetes.mdxindex cd048510..be627777 100644--- a/docs/enterprise/deployment/kubernetes.mdx+++ b/docs/enterprise/deployment/kubernetes.mdx@@ -68,10 +68,21 @@ spec:imagePullSecrets:- name: context7-registryterminationGracePeriodSeconds: 60+ # Runs unprivileged. runAsUser can be any UID; fsGroup makes the volume+ # writable by it. See Running as non-root below.+ securityContext:+ runAsNonRoot: true+ runAsUser: 10001+ runAsGroup: 10001+ fsGroup: 10001containers:- name: context7image: ghcr.io/context7/enterprise:latestimagePullPolicy: Always+ securityContext:+ allowPrivilegeEscalation: false+ capabilities:+ drop: ["ALL"]ports:- containerPort: 3000name: http@@ -204,6 +215,40 @@ kubectl logs -n context7 context7-0Once the pod is ready, open your Ingress hostname in a browser to complete the setup wizard.+## Running as non-root++The container runs as root by default, so existing deployments are unaffected. Set a `securityContext` to run it unprivileged, as the manifest above does. This satisfies a `runAsNonRoot` admission policy.++`runAsUser` can be **any** UID. Everything Context7 writes lives under `/data`:++| Path | Contents |+|---|---|+| `/data` | SQLite database, vector index, logs |+| `/data/repos` | source clones for the repositories you index |+| `/data/home` | state for the documentation agent |++`fsGroup` makes that volume writable by whichever UID the pod runs as, so keep it set if you change `runAsUser`. The only other path the container writes is `/tmp`, which is world-writable: it holds Git SSH key material, backup and restore staging, and support bundles.++<Warning>+ **Changing `runAsUser` on an existing volume.** Files already on the volume belong to the previous UID. Most CSI drivers re-apply ownership from `fsGroup` when the volume mounts, so the change is transparent. Volumes that do not support ownership management — `hostPath`, and some NFS setups — ignore `fsGroup`, and the new UID cannot write the existing files. Chown the volume once, or keep the original UID. The server detects this at startup and names the files it cannot write.+</Warning>++<Note>+ This requires image version 1.4.0 or later. Earlier images keep source clones on a root-owned layer inside the image, so a non-root UID starts normally but fails on the first parse.+</Note>++If the volume is not writable by the UID you choose, the server exits at startup naming the offending paths rather than failing later:++```+[config] Not writable by uid 12345: /data/context7.db, /data/logs, /data/vectors.+[config] Set fsGroup on the volume so Kubernetes re-owns it for this uid, or chown+it: chown -R 12345: /data. Note that hostPath-backed volumes ignore fsGroup.+```++Upgrading an existing deployment needs no manual `chown`. The kubelet re-chowns the volume on mount when `fsGroup` is set.++To also set `readOnlyRootFilesystem: true`, mount an `emptyDir` at `/tmp`. Nothing else outside `/data` needs to be writable.+## Networking RequirementsContext7 requires outbound connectivity to the following: