Skip to content

Latest commit

 

History

History
252 lines (184 loc) · 4.5 KB

QUICK_START.md

File metadata and controls

252 lines (184 loc) · 4.5 KB

🚀 Quick Start Guide

Get RuvScan running in 5 minutes.

Prerequisites

You've already set up .env.local with:

  • GITHUB_TOKEN - Your GitHub Personal Access Token
  • OPENAI_API_KEY - Your OpenAI API key

✅ Environment verified!

Option 1: Docker (Recommended)

Start All Services

# Start services with Docker Compose V2
docker compose up -d

This starts:

  • MCP Server (Python/FastAPI) on port 8000
  • Rust Engine (gRPC) on port 50051
  • Go Scanner (Workers) in background

Verify Services

# Check health
curl http://localhost:8000/health

# Should return:
# {"status":"healthy","version":"0.5.0"}

💡 Already have data! The repo includes data/ruvscan.db preloaded with the public ruvnet catalog, so you can jump straight to querying. Only run a scan if you want to refresh that data or add another GitHub org/user.

Your First Scan

# Scan an organization's repositories
curl -X POST http://localhost:8000/scan \
  -H 'Content-Type: application/json' \
  -d '{
    "source_type": "org",
    "name": "ruvnet",
    "limit": 10
  }'

Your First Query

# Ask RuvScan for leverage
curl -X POST http://localhost:8000/query \
  -H 'Content-Type: application/json' \
  -d '{
    "intent": "How can I optimize my AI application performance?",
    "max_results": 5,
    "min_score": 0.7
  }'

Option 2: Manual (Development)

1. Install Dependencies

Python:

cd src/ruvscan_mcp
pip install -r requirements.txt

Rust:

cd src/rust
cargo build --release

Go:

cd src/go/scanner
go mod download

2. Start Services

Terminal 1 - Rust Engine:

cd src/rust
cargo run --release
# Runs on localhost:50051

Terminal 2 - Python MCP Server:

cd src/ruvscan_mcp
uvicorn server:app --host 0.0.0.0 --port 8000 --reload
# Runs on localhost:8000

Terminal 3 - Go Scanner (optional):

cd src/go/scanner
go run main.go

3. Test It

# Health check
curl http://localhost:8000/health

# Scan repos
curl -X POST http://localhost:8000/scan \
  -H 'Content-Type: application/json' \
  -d '{"source_type":"user","name":"ruvnet","limit":5}'

# Query leverage
curl -X POST http://localhost:8000/query \
  -H 'Content-Type: application/json' \
  -d '{"intent":"Speed up vector database","max_results":3}'

Option 3: Using Helper Scripts

# Make scripts executable
chmod +x scripts/*.sh

# Scan a user's repositories
./scripts/ruvscan scan user ruvnet --limit 10

# Query for leverage
./scripts/ruvscan query "How to build real-time collaboration features?"

# Compare two solutions
./scripts/ruvscan compare "vector-db-v1" "vector-db-v2"

Common Operations

View Scanned Repositories

# List all scanned repos
curl http://localhost:8000/repos

Get Specific Leverage Card

# Get leverage card by ID
curl http://localhost:8000/leverage/{card_id}

Check FACT Cache

# View cached reasoning
curl http://localhost:8000/cache/stats

Monitoring

View Logs

Docker:

# All services
docker compose logs -f

# Specific service
docker compose logs -f mcp-server
docker compose logs -f rust-engine
docker compose logs -f scanner

Manual: Check terminal outputs for each service.

Check Service Health

# MCP Server health
curl http://localhost:8000/health

# Rust Engine health (if exposed)
curl http://localhost:50051/health

Troubleshooting

Port Already in Use

# Find and kill process on port 8000
lsof -ti:8000 | xargs kill -9

# Or change port in docker-compose.yml or .env

Services Won't Start

# View detailed logs
docker compose logs

# Restart services
docker compose restart

# Rebuild if needed
docker compose build --no-cache
docker compose up -d

API Key Issues

# Verify .env.local
cat .env.local

# Should contain:
# GITHUB_TOKEN=ghp_...
# OPENAI_API_KEY=sk-...

Database Issues

# Reset database
rm -f data/ruvscan.db
docker compose restart mcp-server

Next Steps

  1. Read the Full README - README.md
  2. Explore User Experience - USER_EXPERIENCE.md
  3. Contribute - CONTRIBUTING.md
  4. Check Examples - examples/

Getting Help

Ready to discover leverage? 🚀