Skip to main content

Docker Deployment

Docker Compose is the recommended way to run Quant Flow in production. It handles process supervision, log management, and automatic restarts.

Prerequisites​

  • Docker 24+ and Docker Compose v2
  • A funded Hyperliquid account
  • API keys for at least one LLM provider (OpenAI, DeepSeek, NVIDIA NIM, etc.)

Setup​

1. Clone the Repository​

git clone https://github.com/web3spreads/quant-flow
cd quant-flow

2. Initialize Deployment​

Run the initialization script to create required directories and set proper permissions:

bash init-deployment.sh

This creates logs/, data/, and backtest_results/ with correct permissions.

tip

If you later see PermissionError: Permission denied: '/app/logs/...', re-run bash init-deployment.sh.

3. Configure Environment​

cp .env.example .env

Edit .env with your credentials:

# LLM Provider
OPENAI_API_KEY=sk-...
# OR for NVIDIA NIM
NVIDIA_API_KEY=nvapi-...

# Hyperliquid
HYPERLIQUID_PRIVATE_KEY=0x...
HYPERLIQUID_TESTNET=true   # set to false for mainnet

4. Configure Trading Parameters​

cp config.yaml.example config.yaml

Set at minimum:

llm:
  client_type: openai       # or langchain_nvidia, google, etc.
  model: gpt-4o-mini

trading:
  symbols: [BTC]            # start with one symbol
  max_trade_amount: 50      # USD per trade
  max_leverage: 3           # conservative leverage

See config.yaml Reference for all options.

5. Choose Run Mode​

Set RUN_MODE in docker-compose.yml or as an environment variable:

RUN_MODEWhat Runs
main (default)Perpetual futures agent only
gridGrid trading only
allBoth strategies simultaneously
# docker-compose.yml
environment:
  - RUN_MODE=main

For grid mode, also configure config.grid.yaml:

cp config.grid.yaml.example config.grid.yaml

Running​

# Start in background
docker compose up -d

# View logs
docker compose logs -f

# View strategy-specific logs
tail -f logs/main.log
tail -f logs/grid.log

# Stop
docker compose down

Health Checks​

# Check container status
docker compose ps

# Check recent logs
docker compose logs --tail=50

# Restart a single service
docker compose restart quant-flow

Updating​

git pull
docker compose build
docker compose up -d

File Structure After Deployment​

quant-flow/
├── logs/
│   ├── main.log        # perpetual agent logs
│   └── grid.log        # grid trading logs
├── data/
│   └── *.json          # market data cache
├── backtest_results/   # backtest output
├── grid_state.json     # grid manager state (persisted)
└── .env                # credentials (never commit this)
Keep Your Private Key Safe

Never commit .env to version control. The repository's .gitignore excludes it, but double-check before pushing to any remote.

Docker Compose Reference​

The docker-compose.yml uses supervisord internally to manage multiple processes when RUN_MODE=all. Log output from each strategy is tee'd to the respective log file under logs/.

Next Steps​