Skip to content

DOCKER.md

Latest commit

 

History

History
178 lines (129 loc) · 4.74 KB

DOCKER.md

File metadata and controls

178 lines (129 loc) · 4.74 KB
Raw

CodeGraphContext Docker Guide 🐳

Running CodeGraphContext via Docker is the easiest way to use the tool without setting up a Python environment. This guide covers everything from quick start commands to advanced database configurations.

1. Quick Start

Pull the latest image from Docker Hub:

docker pull codegraphcontext/codegraphcontext:latest

Index your current directory:

docker run --rm \
  -v "$(pwd):/workspace" \
  -v cgc-data:/home/cgc/.codegraphcontext \
  codegraphcontext/codegraphcontext cgc index .

Note: The -v cgc-data:/home/cgc/.codegraphcontext volume is crucial as it persists the graph database across runs.

2. Helper Script

For convenience, a helper script is included in the repository.

# Clone the repository
git clone https://github.com/CodeGraphContext/CodeGraphContext.git
cd CodeGraphContext

# Index a repo
./scripts/docker-run.sh index /path/to/my-repo

# Run an interactive shell
./scripts/docker-run.sh shell

# Start the visualization server
./scripts/docker-run.sh viz

3. Docker Compose Profiles

The repository includes a production-ready docker-compose.yml with several profiles depending on your needs.

Default Profile (Embedded Database)

Runs CGC using the embedded FalkorDB Lite or KuzuDB backend.

# Index current directory
docker compose run --rm cgc index .

# Analyze callers
docker compose run --rm cgc analyze callers my_function

falkordb Profile

Runs CGC alongside a dedicated FalkorDB container. Recommended for large projects or ARM64 architectures where FalkorDB Lite might not be fully supported.

# Start FalkorDB in the background
docker compose --profile falkordb up -d

# Now run CGC commands (it will auto-detect the separate database container)
docker compose run --rm cgc index .

viz Profile

Starts the Visualization UI server, allowing you to explore the graph in your browser.

# Start the viz server
docker compose --profile viz up -d

# Visit http://localhost:8080 in your browser

neo4j Profile

If you prefer Neo4j, this profile starts a local Neo4j 5.x container.

# Start Neo4j
docker compose --profile neo4j up -d

# The docker-compose.yml already configures CGC to connect to this Neo4j container.
docker compose run --rm cgc index .

4. MCP Server Mode

You can run CodeGraphContext as an MCP (Model Context Protocol) server inside Docker to connect it to AI assistants like Claude Desktop, Cursor, or Windsurf.

docker run -i --rm \
  -v "/path/to/your/codebase:/workspace" \
  -v cgc-data:/home/cgc/.codegraphcontext \
  -e CGC_MODE=mcp \
  codegraphcontext/codegraphcontext

Important Notes for MCP in Docker:

  1. You MUST use the -i (interactive) flag to keep stdin open for the JSON-RPC protocol.
  2. Do NOT use the -t (tty) flag, as it will corrupt the JSON output.
  3. You must mount your local codebase to /workspace inside the container so the MCP server can read the files.

Client Configuration Example (e.g., Claude Desktop)

{
  "mcpServers": {
    "CodeGraphContext": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/Users/myname/projects:/workspace",
        "-v",
        "cgc-data:/home/cgc/.codegraphcontext",
        "-e",
        "CGC_MODE=mcp",
        "codegraphcontext/codegraphcontext:latest"
      ]
    }
  }
}

5. Volume Mounts

Volume Mount Description
-v "$(pwd):/workspace" Mounts your local code into the container so CGC can index it.
-v cgc-data:/home/cgc/.codegraphcontext Persists the databases, configuration, and index state.

Permissions: The Docker image runs as a non-root user cgc (UID 1000). Ensure the mounted cgc-data volume has correct permissions.

6. Image Variants & Architecture

The codegraphcontext/codegraphcontext image is multi-architecture, supporting:

  • linux/amd64 (Standard Intel/AMD x86_64 PCs & Servers)
  • linux/arm64 (Apple Silicon M1/M2/M3, AWS Graviton, Raspberry Pi)

Docker will automatically pull the correct variant for your architecture.

Available Tags

Tag Usage
latest The most recent stable release. Recommended for most users.
edge Built automatically from the main branch. Contains the latest features but may be unstable.
0.4.19 Specific semantic version.

7. Kubernetes Deployment

Manifests are provided in the k8s/ directory for deploying to a Kubernetes cluster.

kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/pvc.yaml
kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml

Note: You may need to adjust the PersistentVolumeClaim (pvc.yaml) storage class to match your cluster environment.