Skip to main content

Development Setup

Run Rephole locally for development and testing.

Prerequisites​

  • Node.js 20+
  • Docker & Docker Compose
  • Git
  • pnpm (recommended) or npm

Option 1: Full Docker (Easiest)​

Run everything in containers:

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

# Configure environment
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

# Start all services
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f

Run infrastructure in Docker, services locally:

Start Infrastructure​

# Start only databases and queue
docker-compose up -d redis postgres chromadb

Install Dependencies​

pnpm install

Start Services​

# Terminal 1: API Server
pnpm start:api:dev

# Terminal 2: Background Worker
pnpm start:worker:dev

Verify Installation​

Health Check​

curl http://localhost:3000/health
# Expected: {"status":"ok"}

Test Ingestion​

curl -X POST http://localhost:3000/ingestions/repository \
  -H "Content-Type: application/json" \
  -d '{"repoUrl": "https://github.com/twodHQ/rephole.git"}'

Development Tools​

View Logs​

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f api
docker-compose logs -f worker

Database Access​

# PostgreSQL
docker exec -it rephole-postgres psql -U rephole

# Redis CLI
docker exec -it rephole-redis redis-cli

Reset Data​

# Stop services and remove volumes
docker-compose down -v

# Restart fresh
docker-compose up -d

Environment Variables​

For development, create .env:

PORT=3000
NODE_ENV=development

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=rephole
POSTGRES_PASSWORD=devpassword
POSTGRES_DB=rephole

REDIS_HOST=localhost
REDIS_PORT=6379

CHROMA_HOST=localhost
CHROMA_PORT=8000

OPENAI_API_KEY=sk-your-key-here

LOG_LEVEL=debug

Troubleshooting​

Port Already in Use​

# Find process using port 3000
lsof -i :3000

# Kill it
kill -9 <PID>

Docker Issues​

# Restart Docker daemon
sudo systemctl restart docker

# Clean up
docker system prune -af

Database Connection Failed​

# Check if PostgreSQL is running
docker-compose ps postgres

# View logs
docker-compose logs postgres