Skip to content

installation-setup.md

Latest commit

 

History

History
244 lines (176 loc) · 6.27 KB

installation-setup.md

File metadata and controls

244 lines (176 loc) · 6.27 KB

Installation & Setup Guide

This guide covers the prerequisites, installation, and configuration of CodeRAG.

Prerequisites

  • Node.js: Version 18 or higher
  • Neo4J Database: Version 5.11 or higher (required for vector indexes and semantic search)
  • Git: For cloning the repository

Installation

1. Clone and Install

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

# Install dependencies
npm install

# Build the project
npm run build

2. Environment Configuration

Create a .env file in the project root:

# Neo4j Database Configuration
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_neo4j_password

# Project Configuration
PROJECT_ISOLATION_STRATEGY=shared_db
DEFAULT_PROJECT_ID=default
CROSS_PROJECT_ANALYSIS=false
MAX_PROJECTS_SHARED_DB=100

# Semantic Search Configuration (Optional)
# Options: openai, local, disabled
SEMANTIC_SEARCH_PROVIDER=disabled

# OpenAI Configuration (required if SEMANTIC_SEARCH_PROVIDER=openai)
# OPENAI_API_KEY=sk-your-openai-api-key-here

# Embedding Model Configuration
# EMBEDDING_MODEL=text-embedding-3-small
# EMBEDDING_MAX_TOKENS=8000
# EMBEDDING_BATCH_SIZE=100
# SIMILARITY_THRESHOLD=0.7

# Remote Repository Authentication (Optional)
# GitHub
# GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxx

# GitLab
# GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxx
# GITLAB_HOST=gitlab.company.com  # Optional, for self-hosted GitLab

# Bitbucket
# BITBUCKET_USERNAME=your_username
# BITBUCKET_APP_PASSWORD=your_app_password

# Optional: Server configuration
SERVER_PORT=3000
LOG_LEVEL=info

Semantic Search Setup (Optional)

To enable semantic code search with natural language queries:

  1. Get an OpenAI API key from OpenAI Platform

  2. Update your .env file:

    SEMANTIC_SEARCH_PROVIDER=openai
OPENAI_API_KEY=sk-your-openai-api-key-here
EMBEDDING_MODEL=text-embedding-3-small

  3. Ensure Neo4j 5.11+ for vector index support (required for semantic search)

  4. Initialize semantic search after first project scan:

    npm run build
node build/index.js --tool initialize_semantic_search

For detailed semantic search configuration, see the Semantic Search Guide.

Remote Repository Authentication Setup (Optional)

CodeRAG can directly analyze remote repositories from GitHub, GitLab, and Bitbucket without requiring local cloning. To access private repositories, configure authentication tokens:

GitHub Authentication

  1. Create a Personal Access Token:

  2. Configure in .env:

    GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxx

GitLab Authentication

  1. Create a Personal Access Token:

    • Go to GitLab Settings > Access Tokens
    • Create token with read_repository scope
    • Copy the generated token

  2. Configure in .env:

    GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxx
# For self-hosted GitLab:
GITLAB_HOST=gitlab.company.com

Bitbucket Authentication

  1. Create an App Password:

    • Go to Bitbucket Settings > Personal Bitbucket settings > App passwords
    • Create password with Repositories: Read permission
    • Copy the generated password

  2. Configure in .env:

    BITBUCKET_USERNAME=your_username
BITBUCKET_APP_PASSWORD=your_app_password

Usage Examples

Once authentication is configured, you can scan remote repositories directly:

# Public repositories (no authentication needed)
npm run scan https://github.com/owner/repo.git

# Private repositories (uses configured tokens)
npm run scan https://github.com/private/repo.git
npm run scan https://gitlab.com/private/repo.git
npm run scan https://bitbucket.org/private/repo.git

# Specific branches
npm run scan https://github.com/owner/repo.git -- --branch develop

Neo4J Database Setup

CodeRAG requires a running Neo4J instance. Here are several setup options:

Option 1: Neo4J Desktop (Recommended for Development)

  1. Download Neo4J Desktop
  2. Install and create a new project
  3. Create a new database with:
    • Name: coderag (or your preference)
    • Password: Set a secure password
    • Version: 5.11+
  4. Start the database
  5. Note the connection details (usually bolt://localhost:7687)

Option 2: Docker

# Run Neo4J in Docker
docker run \
    --name neo4j-coderag \
    -p 7474:7474 -p 7687:7687 \
    -d \
    -v $HOME/neo4j/data:/data \
    -v $HOME/neo4j/logs:/logs \
    -v $HOME/neo4j/import:/var/lib/neo4j/import \
    -v $HOME/neo4j/plugins:/plugins \
    --env NEO4J_AUTH=neo4j/your_password \
    neo4j:5.12

Option 3: Neo4J AuraDB (Cloud)

  1. Sign up at Neo4J Aura
  2. Create a free instance
  3. Note the connection URI and credentials
  4. Update your .env file with the cloud connection details

Running CodeRAG

CodeRAG supports two modes of operation:

STDIO Mode (Default - for MCP Clients)

This mode is used when integrating with MCP-compatible AI tools:

# Start in STDIO mode
npm start

# Or use the built version
npm run start:built

HTTP/SSE Mode (for HTTP API access)

This mode provides an HTTP endpoint for web-based access:

# Start HTTP server on port 3000
npm start -- --sse --port 3000

# Or specify a different port
npm start -- --sse --port 8080

Development Mode

For development with auto-reload:

npm run dev

Verification

To verify your installation:

  1. Test Neo4J Connection: Ensure your Neo4J instance is running and accessible
  2. Build Success: Run npm run build without errors
  3. STDIO Mode: Run npm start and verify it starts without connection errors
  4. HTTP Mode: Run npm start -- --sse --port 3000 and visit http://localhost:3000/health

Next Steps