Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/backtest-kit/backtest-monorepo-parallel/llms.txt

Use this file to discover all available pages before exploring further.

This guide takes you from a fresh clone to a running 9-symbol parallel backtest. The entire flow — infrastructure, build, and first run — typically completes in under ten minutes on a machine with a working Docker daemon and Node.js installation.

​
Prerequisites

Before you begin, make sure the following tools are available on your machine:
  • Node.js 20 or later (node --version)
  • Docker with the Compose plugin (docker compose version) or standalone docker-compose
  • Git (git --version)
Windows users need the build:win script (see Step 6). All other steps are identical across platforms.
1

Clone the repository

Clone the template and enter the project root:
git clone https://github.com/tripolskypetr/backtest-kit.git
cd backtest-kit/backtest-monorepo-parallel
Alternatively, use the directory as a template by copying it into your own repository — no monorepo changes are required to add new strategies later.
2

Configure environment variables

Copy the example env file and edit the values for your local setup:
cp .env.example .env
The variables and their defaults are:
VariableDefaultPurpose
CC_MONGO_CONNECTION_STRINGmongodb://localhost:27017/backtest-pro?wtimeoutMS=15000Mongo connection used by all DbServices
CC_REDIS_HOST127.0.0.1Redis host for BaseMap O(1) lookups
CC_REDIS_PORT6379Redis port
CC_REDIS_USERdefaultRedis ACL username
CC_REDIS_PASSWORDmysecurepasswordRedis ACL password
CC_SYMBOL_LISTBTCUSDT,POLUSDT,ZECUSDT,HYPEUSDT,XAUTUSDT,DOGEUSDT,SOLUSDT,PENGUUSDT,HBARUSDTComma-separated symbols for Mode A parallel runner
The docker-compose files in docker/mongodb/ and docker/redis/ are pre-configured to match the defaults above, so no edits are needed for a local first run.
3

Start MongoDB

Bring up the MongoDB container in detached mode:
docker-compose -f docker/mongodb/docker-compose.yaml up -d
Wait for the container to report healthy before proceeding (docker ps).
4

Start Redis

Bring up the Redis container in detached mode:
docker-compose -f docker/redis/docker-compose.yaml up -d
Both containers must be running before you attempt a backtest run.
5

Install root dependencies

Install the root-level dependencies (rollup, TypeScript, dev tools):
npm install
npm workspaces will also hoist shared dependencies visible to both packages/core and packages/main.
6

Build workspace packages

Build both workspace packages (@pro/core and @pro/main). The build script walks every directory under ./packages/*, runs npm install and npm run build inside each, and emits two artifacts per package:
  • packages/<pkg>/build/index.cjs — CommonJS bundle consumed at runtime via config/alias.config.ts
  • packages/<pkg>/types.d.ts — rolled-up declaration bundle consumed at compile time via tsconfig.json paths
npm run build
The underlying shell script (scripts/linux/build.sh) is straightforward:
#!/bin/bash
cd packages
for D in `find . -maxdepth 1 -not -path "." -not -path "./.*" -type d`
do
    cd $D
    echo $D
    npm install
    npm run build
    cd ..
done
cd ..
A successful build prints the package directory names and exits with code 0. If either package fails, fix the TypeScript error before proceeding — the runtime will fail to resolve alias.config.ts entries otherwise.
7

Run the parallel backtest (Mode A)

Launch a full 9-symbol parallel backtest using the sample strategy:
npm run start -- --backtest --entry --ui --cache \
  ./content/apr_2026.strategy/apr_2026.strategy.ts
Flag breakdown:
FlagEffect
--backtestActivates backtest mode in @pro/main
--entryGates backtest.ts to iterate CC_SYMBOL_LIST and call Backtest.background(symbol, …) for each symbol
--uiStarts the @backtest-kit/ui web interface on port 60050
--cachePre-warms candle data into MongoDB before the runners start
(path argument)Strategy file loaded by @backtest-kit/cli at runtime
Use --cache on the first run for every strategy. It pre-warms every symbol’s candles from ccxt into MongoDB so the inner replay loop never blocks on HTTP — this is the primary reason the hot path reaches ~6 300× real-time speed. Subsequent runs can omit --cache if the candles are already present.
8

Observe the output

Each tick printed to stdout follows this pattern from apr_2026.strategy.ts:
active BTCUSDT backtest=1775003640000 now=1779292949309
active SOLUSDT backtest=1775003660000 now=1779292949441
active DOGEUSDT backtest=1775003640000 now=1779292949512
...
  • backtest=<historicalMs> — the simulated timestamp inside the replay window
  • now=<wallClockMs> — the actual wall-clock time when the event fired
The gap between consecutive now= values tells you your effective throughput. On a warm cache, expect ≈ 103 events/sec across 9 symbols on mid-range hardware.

​
Optional: open the web UI

If you passed --ui, the @backtest-kit/ui dashboard is available at: 
http://localhost:60050
The UI displays equity curves, open positions, and per-symbol metrics updated in real time as the backtest progresses.
Simpler single-symbol runs with Mode B: Drop the --entry flag (and optionally add --noCache) to hand control to the @backtest-kit/cli built-in runner. It evaluates the strategy file directly, picks up whichever symbol the strategy dispatches internally, and skips the CC_SYMBOL_LIST iteration entirely — useful for iterating on a single strategy without spinning up all 9 contexts.
npm run start -- --backtest --ui --noCache \
  ./content/apr_2026.strategy/apr_2026.strategy.ts

​
What’s next

Architecture

Learn how the monorepo, DI container, config layer, and build pipeline fit together.

Mode A Parallel Guide

Configure symbol lists, tune caching, and add new parallel contexts.

Build docs developers (and LLMs) love

Get started for freeTalk to us