getting-started-docker.md

Getting Started (Docker)

This guide covers running CodePrism using Docker containers. For native installation, see the Getting Started Guide.

Table of Contents

1. Prerequisites
2. Start Qdrant
3. Build or Pull CodePrism Image
4. Run Initial Indexing
5. Start MCP Server
6. VS Code Integration

1. Prerequisites

• Docker installed and running
• Your code repository accessible from the host machine

2. Start Qdrant

CodePrism requires Qdrant for semantic search:

docker run -d --name qdrant \
  -p 6333:6333 -p 6334:6334 \
  -v qdrant_storage:/qdrant/storage \
  qdrant/qdrant:latest

3. Build or Pull CodePrism Image

Build from Source

git clone https://github.com/codeprysm/codeprysm.git
cd codeprysm
docker build -f docker/Dockerfile -t codeprysm:local .

Or using just:

just docker-build

4. Run Initial Indexing

Add .codeprysm/ to your repository's .gitignore:

echo ".codeprysm/" >> /path/to/your/repo/.gitignore

Run the initial indexing:

docker run -it --rm \
  --network host \
  -v /path/to/your/repo:/data \
  codeprysm:local init --root /data --qdrant-url http://localhost:6334

This creates a .codeprysm/ directory in your repository containing the code graph and semantic index.

Exclude Unwanted Files

Use glob patterns to exclude specific files or directories:

docker run -it --rm \
  --network host \
  -v /path/to/your/repo:/data \
  codeprysm:local init --root /data --exclude "**/node_modules/**" "**/vendor/**"

Files matching .gitignore patterns are automatically excluded.

5. Start MCP Server

Interactive Mode

docker run -it --rm \
  --network host \
  -v /path/to/your/repo:/data \
  codeprysm:local mcp --root /data --qdrant-url http://localhost:6334

Background Mode

docker run -d --name codeprysm-mcp \
  --network host \
  -v /path/to/your/repo:/data \
  codeprysm:local mcp --root /data --qdrant-url http://localhost:6334

6. VS Code Integration

Create .vscode/mcp.json in your repository:

{
    "servers": {
        "codeprysm": {
            "type": "stdio",
            "command": "docker",
            "args": [
                "run", "--rm", "-i",
                "--network", "host",
                "-v", "${workspaceFolder}:/data",
                "codeprysm:local",
                "mcp", "--root", "/data", "--qdrant-url", "http://localhost:6334"
            ]
        }
    }
}

Note for Dev Containers: The ${workspaceFolder} variable may not work correctly in devcontainers. Use the absolute host path to your repository instead.

Docker Compose

For a complete setup with Qdrant, create docker-compose.yml:

version: '3.8'

services:
  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - qdrant_storage:/qdrant/storage

  codeprysm:
    build:
      context: .
      dockerfile: docker/Dockerfile
    depends_on:
      - qdrant
    volumes:
      - /path/to/your/repo:/data
    command: ["mcp", "--root", "/data", "--qdrant-url", "http://qdrant:6334"]
    stdin_open: true
    tty: true

volumes:
  qdrant_storage:

Run with:

docker compose up -d

Verification

Check Container Status

docker ps | grep -E "(qdrant|codeprysm)"

View Statistics

docker run --rm \
  -v /path/to/your/repo:/data \
  codeprysm:local stats --prism-dir /data/.codeprysm

Test Search

docker run --rm \
  --network host \
  -v /path/to/your/repo:/data \
  codeprysm:local search "authentication handler" --qdrant-url http://localhost:6334

Troubleshooting

Network Issues

If the container can't connect to Qdrant, ensure you're using --network host or that both containers are on the same Docker network.

Permission Issues

The CodePrism container runs as a non-root user. Ensure the mounted volume has appropriate permissions:

chmod -R 755 /path/to/your/repo

Volume Mount Issues

On macOS and Windows, ensure Docker has access to the directory you're mounting. Check Docker Desktop settings under Resources > File Sharing.