Installation

This guide will help you get Quantum Trader up and running on your local machine using Docker.

Prerequisites

Before you begin, ensure you have the following installed:

• Docker (20.10+) and Docker Compose (2.0+)
• Git for cloning the repository
• Node.js (18+) if you want to run the frontend in development mode

Tip

On macOS, we recommend Docker Desktop. On Linux, install Docker Engine and Docker Compose separately.

Quick Start

1. Clone the repository

   git clone https://github.com/your-org/quantum-trader.git
   cd quantum-trader

2. Copy the environment file

   cp .env.example .env

3. Configure environment variables

   Edit .env and add your API keys:

   # Required: At least one data provider
   POLYGON_API_KEY=your_polygon_api_key
   
   # Optional: Additional providers
   ALPHA_VANTAGE_API_KEY=your_av_key
   
   # Database (defaults work for local development)
   DB_PASSWORD=your_secure_password

4. Start all services

   docker compose up -d

5. Verify installation

   Check that all containers are running:

   docker compose ps

   You should see:

   Service	Port	Status
   frontend	8500	Running
   api	8501	Running
   timescaledb	8502	Running
   pgadmin	8503	Running

6. Access the dashboard

   Open http://localhost:8500 in your browser.

Port Configuration

All ports are configurable via environment variables:

Service	Default Port	Environment Variable
Frontend (Dashboard)	8500	FRONTEND_PORT
API (FastAPI)	8501	API_PORT
TimescaleDB	8502	DB_PORT
pgAdmin	8503	PGADMIN_PORT
Adminer	8504	ADMINER_PORT

Data Provider Setup

Quantum Trader supports multiple data providers. You need at least one configured.

Polygon.io (Recommended)

1. Sign up at polygon.io
2. Get your free API key from the dashboard
3. Add to .env:

   POLYGON_API_KEY=your_key_here

Note

Free tier: 5 calls/minute, 2 years of historical data. Sufficient for personal use and backtesting.

Alpha Vantage (Backup)

1. Get a free key at alphavantage.co
2. Add to .env:

   ALPHA_VANTAGE_API_KEY=your_key_here

Caution

Free tier is limited to 25 calls/day. Use primarily as a fallback for historical data.

Database Initialization

The database schema is automatically created on first run. To verify:

# Check API health
curl http://localhost:8501/health

# Should return: {"status": "healthy", "database": "connected"}

Development Mode

For frontend development with hot reload:

Frontend Only

# Keep backend running in Docker
docker compose up -d api timescaledb

# Run frontend in dev mode
cd frontend
npm install
npm run dev

Full Stack

# Run everything except frontend in Docker
docker compose up -d api timescaledb pgadmin

# Frontend with hot reload
cd frontend
npm install
npm run dev

# Backend with auto-reload (optional)
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8501

Troubleshooting

Container won’t start

Check logs for the failing service:

docker compose logs api
docker compose logs timescaledb

Database connection errors

Ensure TimescaleDB is fully initialized before the API starts:

# Restart with fresh containers
docker compose down
docker compose up -d timescaledb
sleep 10  # Wait for DB to initialize
docker compose up -d

Port conflicts

If ports are already in use, modify .env:

FRONTEND_PORT=3000
API_PORT=3001
DB_PORT=5433

Then restart:

docker compose down
docker compose up -d

Next Steps

• Quick Start - Add your first ticker and run a backtest
• Configuration - All environment variables explained