Installation & Setup

🚀 Quick Installation Guide

Get Quantbot up and running in less than 5 minutes with our streamlined Docker-based installation process.

System Requirements

Minimum Requirements

• Docker: Docker Desktop 4.0+ or Docker Engine 20.0+
• Docker Compose: v2.0+
• Memory: 8GB RAM
• Storage: 10GB free space
• Network: Stable internet connection for real-time data

Recommended Requirements

• Docker: Latest Docker Desktop
• Memory: 16GB RAM or more
• Storage: 20GB free space (for database volumes)
• Network: High-speed broadband connection

Installation Methods

Docker (Recommended)Development SetupProduction Deploy

Prerequisites: Install Docker Desktop

# 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

For contributors and advanced users:

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

# Start databases only
docker compose up postgres neo4j -d

# Backend setup
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

# Frontend setup (new terminal)
cd Quantbot-FE
npm install
npm run dev

For production environments:

# Clone and configure
git clone https://github.com/bakr-UCB/Quantbot.git
cd Quantbot

# Set production environment
export NODE_ENV=production
export VITE_ENVIRONMENT=production

# Start in production mode
docker compose -f docker-compose.prod.yml up -d

Required Configuration

1. Environment Variables

Create environment files for your setup:

Backend Configuration (Quantbot-BE/.env)

Quantbot-BE/.env

# Database Configuration
DATABASE_URL=postgresql+asyncpg://quantbot_admin:quantbot_password@postgres:5432/quantbot

# JWT Configuration
JWT_SECRET_KEY=your-super-secret-jwt-key-change-this-in-production
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30
JWT_REFRESH_TOKEN_EXPIRE_DAYS=7

# 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
FMP_API_KEY=your-financial-modeling-prep-key

# Neo4j Configuration (Memory System)
NEO4J_URI=bolt://neo4j:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=quantbot_neo4j_password
DEFAULT_DATABASE=neo4j

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

# Memory Configuration
MEMORY_MAX_EPISODES_PER_USER=10000
MEMORY_RETENTION_DAYS=365
MEMORY_SIMILARITY_THRESHOLD=0.7
DISABLE_MEMORY=false

# Environment
ENVIRONMENT=develop

Frontend Configuration (Quantbot-FE/.env.development)

Quantbot-FE/.env.development

# Environment
VITE_ENVIRONMENT=development

# Backend API URL
VITE_API_BASE_URL=http://localhost:8000/api/v1

Docker Compose Configuration (.env)

.env

# 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 backend .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 Configuration
OPIK_API_KEY=your-opik-api-key
OPIK_WORKSPACE=your-workspace
OPIK_PROJECT_NAME=quantbot
OPIK_OBSERVE=true

# Memory Configuration
DISABLE_MEMORY=false

2. API Keys Setup

Required API Keys

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

3. Environment variable: GOOGLE_API_KEY

4. OpenAI - Get API key

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

6. Environment variable: OPENAI_API_KEY

7. News API - Get API key

8. Used for: Financial news integration
9. Environment variable: NEWS_API_KEY

Optional but Recommended API Keys

1. Finnhub - Get API key
2. Used for: Social sentiment analysis and alternative data

3. Environment variable: FINNHUB_API_KEY

4. Financial Modeling Prep (FMP) - Get API key

5. Used for: Enhanced market data

6. Environment variable: FMP_API_KEY

7. Opik - Get API key

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

3. Database Initialization

# Initialize database (first run)
docker compose exec backend alembic upgrade head

# Check database status
docker compose exec postgres psql -U quantbot_admin -d quantbot -c "\dt"

# Check Neo4j status
# Visit http://localhost:7474 in browser
# Username: neo4j, Password: quantbot_neo4j_password

Verification

Quick Health Check

# Check all services are running
docker compose ps

# Test backend API
curl http://localhost:8000/api/v1/system/health

# Test frontend
curl http://localhost:5173

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

Complete System Test

# Test API documentation
open http://localhost:8000/docs

# Test frontend application
open http://localhost:5173

# Test Neo4j browser
open http://localhost:7474

# Run backend tests
docker compose exec backend uv run pytest tests/ -v

# Check database connection
docker compose exec backend alembic current

API Health Endpoints

GET /api/v1/system/health

Basic health check - returns system status

Health Check Response

{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00Z",
  "services": {
    "database": "connected",
    "neo4j": "connected",
    "market_data": "active",
    "ai_service": "ready"
  },
  "version": "1.0.0"
}

Troubleshooting

Common Issues

Port Conflicts

# Check what's using the ports
lsof -i :5173  # Frontend
lsof -i :8000  # Backend
lsof -i :5432  # PostgreSQL
lsof -i :7474  # Neo4j

# Kill conflicting processes or change ports in docker-compose.yaml

Database Connection Issues

# Check container status
docker compose ps

# Restart database services
docker compose restart postgres neo4j

# View database logs
docker compose logs postgres
docker compose logs neo4j

# Reset database (WARNING: deletes all data)
docker compose down -v
docker compose up postgres neo4j -d

Memory/Performance Issues

# Check Docker resource allocation
docker system df
docker stats

# Increase Docker memory limit in Docker Desktop settings
# Recommended: 8GB+ memory allocation

# Clean up Docker resources
docker system prune -f

API Key Configuration

# Verify environment variables are loaded
docker compose exec backend printenv | grep API

# Test individual APIs
docker compose exec backend python -c "
import os
print('Google API Key:', 'GOOGLE_API_KEY' in os.environ)
print('OpenAI API Key:', 'OPENAI_API_KEY' in os.environ)
"

# Restart services after updating .env files
docker compose restart

Hot Reload Not Working

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

# On Windows with WSL, check file permissions
# Try rebuilding containers
docker compose build --no-cache
docker compose up --watch

Advanced Troubleshooting

Container Debugging

# Access backend container shell
docker compose exec backend bash

# Access database
docker compose exec postgres psql -U quantbot_admin -d quantbot

# View all logs
docker compose logs -f

# Check container resource usage
docker compose top

Network Issues

# Check Docker network
docker network ls
docker network inspect quantbot_default

# Test inter-container connectivity
docker compose exec frontend curl http://backend:80/api/v1/system/health

Getting Help

• Documentation: Development Setup Guide
• API Reference: Authentication API
• GitHub Issues: Report Problems
• Testing Guide: Testing Documentation

Next Steps

After successful installation:

1. Quick Start Guide - Your first steps with Quantbot
2. Development Setup - Detailed development environment setup
3. API Authentication - Secure API access setup
4. Feature Overview - Explore all capabilities
5. Portfolio Setup - Configure investment tracking

Production Deployment

For production deployments, see:

• Deployment Guide - Production deployment strategies
• Architecture Overview - System architecture details
• Security Configuration - Security best practices

---

Installation Complete! 🎉

Ready to start making smarter investment decisions with AI?

Continue to Quick Start