Skip to content

Development Setup

This guide will help you set up a local development environment for Quantbot.

Prerequisites

Before getting started, ensure you have the following installed on your system:

Required Software

  • Docker & Docker Compose: For containerized development
  • Install Docker Desktop
  • Verify: docker --version and docker compose version
  • Node.js 18+: For frontend development
  • Install Node.js
  • Verify: node --version
  • Python 3.12+: For backend development
  • Install Python
  • Verify: python --version
  • UV Package Manager: Fast Python package management
  • Install: curl -LsSf https://astral.sh/uv/install.sh | sh
  • Verify: uv --version

System Requirements

  • RAM: 8GB minimum, 16GB recommended
  • Storage: 10GB free space
  • Network: Internet connection for downloading dependencies and API access

Quick Start

The fastest way to get Quantbot running locally:

# Clone the repository
git clone https://github.com/bakr-UCB/Quantbot.git
cd Quantbot

# Start all services with hot reload
docker compose up --watch

This will start: - Frontend: http://localhost:5173 - Backend API: http://localhost:8000 - API Documentation: http://localhost:8000/docs - PostgreSQL: localhost:5432 - Neo4j Browser: http://localhost:7474

Detailed Setup

1. Environment Configuration

Backend Environment Variables

Copy the example environment file and configure it:

cd Quantbot-BE
cp .env.example .env

Edit .env and configure the following required variables:

# API Keys (Required for full functionality)
GOOGLE_API_KEY=your-google-api-key-here
OPENAI_API_KEY=your-openai-api-key-here
NEWS_API_KEY=your-news-api-key-here

# Additional API Keys (Optional but recommended)
FINNHUB_API_KEY=your-finnhub-api-key-here
FMP_API_KEY=your-fmp-api-key-here

# Optional API Keys (for enhanced features)
FMP_API_KEY=your-financial-modeling-prep-key

# Opik Observability (Optional)
OPIK_API_KEY=your-opik-api-key
OPIK_WORKSPACE=your-workspace
OPIK_PROJECT_NAME=quantbot-dev
OPIK_OBSERVE=true

# JWT Secret (Change in production)
JWT_SECRET_KEY=your-super-secret-jwt-key-change-this-in-production

# Database (Already configured for Docker)
DATABASE_URL=postgresql+asyncpg://quantbot_admin:quantbot_password@postgres:5432/quantbot

# Neo4j (Already configured for Docker)
NEO4J_URI=bolt://neo4j:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=quantbot_neo4j_password

Frontend Environment Variables

Configure the frontend environment:

cd ../Quantbot-FE
cp .env.example .env.development

The default configuration should work for local development:

VITE_ENVIRONMENT=development
VITE_API_BASE_URL=http://localhost:8000/api/v1

Root Environment Variables

Create a .env file in the project root for Docker Compose:

# Return to project root
cd ..

# Create root .env file
cat > .env << EOF
# Environment
NODE_ENV=development
VITE_ENVIRONMENT=development
VITE_API_BASE_URL=http://localhost:8000/api/v1

# Neo4j Configuration
NEO4J_URI=bolt://neo4j:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=quantbot_neo4j_password

# API Keys (copy from Quantbot-BE/.env)
GOOGLE_API_KEY=your-google-api-key-here
OPENAI_API_KEY=your-openai-api-key-here
NEWS_API_KEY=your-news-api-key-here
FINNHUB_API_KEY=your-finnhub-api-key-here
FMP_API_KEY=your-fmp-api-key-here

# Opik (Optional)
OPIK_API_KEY=your-opik-api-key
OPIK_WORKSPACE=your-workspace
OPIK_PROJECT_NAME=quantbot-dev
OPIK_OBSERVE=true

# Memory Configuration
DISABLE_MEMORY=false
EOF

2. Development Modes

Start all services with hot reload enabled:

# Start in foreground with logs
docker compose up --watch

# Or start in background
docker compose up -d --watch

# View logs
docker compose logs -f

Benefits: - Consistent environment across all developers - All dependencies pre-configured - Database services included - Hot reload for both frontend and backend

Option B: Hybrid Development

Run databases in Docker, frontend/backend locally:

# Start only databases
docker compose up postgres neo4j -d

# Terminal 1: Backend
cd Quantbot-BE
make create_environment
source .venv/bin/activate  # On macOS/Linux
# OR .venv\Scripts\activate  # On Windows
make requirements
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Terminal 2: Frontend
cd Quantbot-FE
npm install
npm run dev

Benefits: - Direct code editing without container sync - Faster iteration for frontend/backend changes - Full IDE support and debugging

3. Database Setup

Initial Migration

When running for the first time, you may need to set up the database:

# If running with Docker
docker compose exec backend alembic upgrade head

# If running locally
cd Quantbot-BE
source .venv/bin/activate
alembic upgrade head

Database Access

  • PostgreSQL:
  • Host: localhost:5432
  • User: quantbot_admin
  • Password: quantbot_password

  • Database: quantbot

  • Neo4j Browser:

  • URL: http://localhost:7474
  • User: neo4j
  • Password: quantbot_neo4j_password

4. Development Commands

Backend Commands

cd Quantbot-BE

# Create virtual environment
make create_environment

# Install dependencies
make requirements

# Code formatting and linting
make format          # Auto-format code
make lint           # Check code style

# Run development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Database migrations
alembic upgrade head                               # Apply migrations
alembic revision --autogenerate -m "description"  # Create migration

# Testing
uv run pytest --cov=app --cov-report=term-missing tests/
uv run pytest tests/unit/ -v                      # Unit tests only
uv run pytest tests/integration/ -v               # Integration tests only
uv run pytest evals/eval_tests/ -v                # AI evaluation tests

Frontend Commands

cd Quantbot-FE

# Install dependencies
npm install

# Development server
npm run dev              # Start dev server (http://localhost:5173)

# Building
npm run build:prod       # Production build
npm run preview          # Preview production build

# Code quality
npm run lint             # Code linting

Docker Commands

# Start all services
docker compose up --watch

# Start specific services
docker compose up postgres neo4j -d

# View logs
docker compose logs -f backend
docker compose logs -f frontend

# Execute commands in containers
docker compose exec backend alembic upgrade head
docker compose exec backend uv run pytest
docker compose exec frontend npm run lint

# Rebuild containers
docker compose build
docker compose up --build

# Clean up
docker compose down -v    # Stop and remove volumes
docker system prune -f    # Clean up Docker resources

API Keys Setup

Required APIs

  1. Google AI Studio: Get API key from Google AI Studio
  2. Used for: Gemini AI agent integration

  3. Environment variable: GOOGLE_API_KEY

  4. OpenAI: Get API key from OpenAI Platform

  5. Used for: Memory system (graphiti-core)

  6. Environment variable: OPENAI_API_KEY

  7. News API: Get API key from NewsAPI

  8. Used for: Financial news integration
  9. Environment variable: NEWS_API_KEY
  1. Finnhub: Get API key from Finnhub
  2. Used for: Social sentiment analysis and alternative data

  3. Environment variable: FINNHUB_API_KEY

  4. Financial Modeling Prep: Get API key from FMP

  5. Used for: Enhanced market data

  6. Environment variable: FMP_API_KEY

  7. Opik: Get API key from Opik

  8. Used for: AI agent observability and evaluation
  9. Environment variables: OPIK_API_KEY, OPIK_WORKSPACE, OPIK_PROJECT_NAME

Troubleshooting

Common Issues

Port Conflicts

If ports 5173, 8000, 5432, or 7474 are already in use: 

# Check what's using the port
lsof -i :8000  # On macOS/Linux
netstat -ano | findstr :8000  # On Windows

# Kill the process or change ports in docker-compose.yaml

Database Connection Issues

# Check if containers are running
docker compose ps

# Restart database services
docker compose restart postgres neo4j

# Check database logs
docker compose logs postgres
docker compose logs neo4j

Memory/Performance Issues

# Increase Docker memory allocation to 8GB+
# Check Docker Desktop settings

# If using local development, ensure enough system resources

API Rate Limiting

# If you hit API rate limits, you can:
# 1. Get higher-tier API keys
# 2. Enable caching in the backend
# 3. Use mock data for development (set DISABLE_MEMORY=true)

Hot Reload Not Working

# Ensure watch mode is enabled
docker compose up --watch

# Check file permissions (especially on Windows with WSL)
# Try rebuilding containers
docker compose build --no-cache

Getting Help

  • API Documentation: http://localhost:8000/docs
  • GitHub Issues: Report Issues
  • Docker Logs: docker compose logs -f [service]
  • Health Checks: Check service health at startup

Advanced Configuration

Memory System Configuration

Adjust memory behavior by setting these environment variables:

# Memory limits
MEMORY_MAX_EPISODES_PER_USER=10000
MEMORY_RETENTION_DAYS=365
MEMORY_SEARCH_LIMIT=50
MEMORY_SIMILARITY_THRESHOLD=0.7

# Memory features
MEMORY_ENABLE_ENCRYPTION=true
MEMORY_ISOLATION_STRICT=true
DISABLE_MEMORY=false

Development Workflows

Configure AI agent workflow for development:

# Set specific workflow for testing
QUANTBOT_WORKFLOW=development

# Available workflows: development, production, evaluation

Security Configuration

For development, you can use relaxed security settings:

# JWT token expiration (longer for development)
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=480  # 8 hours
JWT_REFRESH_TOKEN_EXPIRE_DAYS=30

# CORS (automatically configured for localhost)

Next Steps

Once your development environment is running:

  1. Explore the API: Visit http://localhost:8000/docs
  2. Test the Frontend: Open http://localhost:5173
  3. Create an Account: Register a new user account
  4. Set API Keys: Configure your personal API keys in the settings
  5. Start Developing: See Contributing Guide for development workflows

For more detailed information, see: