Configuring Backtest, Paper, and Live Execution Modes

backtest-kit-redis-mongo-docker supports three execution modes — backtest, paper, and live — each targeting a different phase of the strategy development lifecycle. Mode selection is controlled by CLI flags passed to the Node.js process, combined with a mandatory --entry guard that prevents accidental execution. Understanding how each mode initialises the MongoDB and Redis connections, handles candle data, and dispatches orders is essential before deploying a strategy.

The `--entry` Guard

Every entry point (backtest.ts, live.ts, and paper.ts) begins with the same two-line guard:

const { values } = getArgs();
if (!values.entry) return;

If the --entry flag (or its Docker equivalent ENTRY=1) is not present, the function returns immediately without connecting to MongoDB or Redis and without starting any strategy loop. This design prevents a strategy bundle from executing unintentionally when it is loaded as a library or inspected in a REPL.

Always pass --entry (or set ENTRY=1) explicitly. Omitting it means the application starts, logs nothing unexpected, and exits cleanly — which can be confusing during initial setup.

Backtest Mode

Backtest mode replays a fixed historical window of OHLCV candles stored in MongoDB, running the strategy against past data to evaluate performance.

const main = async () => {
  const { values } = getArgs();
  if (!values.entry) return;
  if (!values.backtest) return;
  await ioc.mongoService.waitForInit();
  await ioc.redisService.waitForInit();
  await waitForReady(true); // true = backtest mode
  await warmCandles({
    exchangeName: ExchangeName.CCXT,
    from: new Date("2026-01-01T00:00:00Z"),
    to: new Date("2026-01-31T23:59:59Z"),
    interval: "1m",
    symbol: "TRXUSDT",
  });
  Backtest.background("TRXUSDT", {
    exchangeName: ExchangeName.CCXT,
    frameName: FrameName.Jan2026Frame,
    strategyName: StrategyName.Jan2026Strategy,
  });
};

Guard checks

Both --entry and --backtest must be set. The entry point returns immediately if either is missing.

Service initialisation

ioc.mongoService.waitForInit() and ioc.redisService.waitForInit() establish confirmed connections to MongoDB and Redis before any data access occurs.

waitForReady(true)

Passing true signals backtest mode to the readiness layer, which may apply different pre-conditions (e.g. skipping live feed subscriptions).

warmCandles()

Fetches the full historical OHLCV dataset from the exchange for the specified symbol, date range, and interval, then persists it to MongoDB. Subsequent runs reuse the cached data — set NO_FLUSH=1 to skip the Redis flush and speed up repeated backtests.

Backtest.background()

Starts the backtest loop in the background. The frameName identifies the time window (start date, end date, interval), and strategyName identifies the signal logic to apply over that window.

Running Backtest Locally

npm run start -- --entry --backtest

Running Backtest in Docker

npm run start:docker
# Equivalent to: MODE=backtest ENTRY=1 UI=1 STRATEGY_FILE=./build/index.cjs docker-compose up -d

Live Mode

Live mode connects to a real exchange and processes incoming market data in real time, executing actual orders according to the strategy logic.

const main = async () => {
  const { values } = getArgs();
  if (!values.entry) return;
  if (!values.live) return;
  await ioc.mongoService.waitForInit();
  await ioc.redisService.waitForInit();
  await waitForReady(false); // false = live mode
  Live.background("TRXUSDT", {
    exchangeName: ExchangeName.CCXT,
    strategyName: StrategyName.Jan2026Strategy,
  });
};

Live mode intentionally omits warmCandles(). Historical candle data is not needed because the exchange provides a real-time feed. MongoDB and Redis are still initialised to persist trade records and cache active order IDs.

Guard checks

Both --entry and --live must be present.

Service initialisation

Same MongoDB and Redis initialisation as backtest mode.

waitForReady(false)

Passing false signals live mode. The readiness layer may perform additional checks such as confirming exchange connectivity and API key validity.

Live.background()

Starts the live trading loop. Unlike Backtest.background(), there is no frameName parameter because the time window is open-ended (now → indefinite).

Running Live Locally

npm run start -- --entry --live

Live mode places real orders on a real exchange. Always validate strategy logic thoroughly in backtest and paper modes before switching to --live.

Paper Mode

Paper mode mirrors live mode in every technical respect — real-time market data, full MongoDB and Redis initialisation, and the same waitForReady(false) readiness signal — but order execution is simulated. No real funds are used.

const main = async () => {
  const { values } = getArgs();
  if (!values.entry) return;
  if (!values.paper) return;
  await ioc.mongoService.waitForInit();
  await ioc.redisService.waitForInit();
  await waitForReady(false); // false = live/paper mode
  Live.background("TRXUSDT", {
    exchangeName: ExchangeName.CCXT,
    strategyName: StrategyName.Jan2026Strategy,
  });
};

Guard checks

Both --entry and --paper must be present.

Service initialisation

Identical to live mode — MongoDB and Redis are fully initialised.

waitForReady(false)

Same readiness signal as live mode.

Live.background() (simulated)

The strategy runs against live market data but order execution is intercepted and simulated, allowing realistic performance measurement without financial risk.

Running Paper Locally

npm run start -- --entry --paper

The `--ui` Flag and Web Dashboard

Passing UI=1 (Docker) or enabling the UI flag starts the web dashboard on port 60050. The dashboard provides a visual overview of strategy state, open positions, and historical performance.

# Local
npm run start -- --entry --backtest --ui

# Docker (UI=1 is set automatically by start:docker)
npm run start:docker

Access the dashboard at:

http://localhost:60050

The health-check endpoint is also available when the UI is running:

GET http://localhost:60050/api/v1/health/health_check

Mode Comparison

Aspect	Backtest	Paper	Live
CLI flag	`--backtest`	`--paper`	`--live`
`waitForReady` arg	`true`	`false`	`false`
`warmCandles()` called	Yes	No	No
Data source	MongoDB (historical)	Real-time feed	Real-time feed
Order execution	Simulated (replay)	Simulated	Real
`frameName` required	Yes	No	No
Financial risk	None	None	Real funds

Local vs Docker Execution

Aspect	Local (host Node.js)	Docker
Command	`npm run start -- --entry --backtest`	`npm run start:docker`
Infrastructure	Start each service separately	`docker-compose up` (all services)
Hot reload	Yes (rebuild manually with `npm run build`)	No (requires image rebuild)
Debug	`--inspect-brk` available (`start:debug`)	Use `docker logs backtest-kit-redis-mongo-docker`
Redis/Mongo host	`127.0.0.1` / `localhost`	`host.docker.internal`
REPL access	`npm run start:repl`	Not available

During strategy development, run MongoDB and Redis in Docker while executing the Node.js process locally. This gives you fast iteration with npm run build && npm run start -- --entry --backtest while keeping infrastructure isolated from your host.

Debugging a Running Strategy

Local debug (inspect)

npm run start:debug
# Equivalent to: node --inspect-brk ./node_modules/@backtest-kit/cli/build/index.mjs

Open chrome://inspect in Google Chrome and attach to the Node.js process. Execution pauses at the first line, allowing you to set breakpoints before any strategy code runs.

Docker logs

docker logs -f backtest-kit-redis-mongo-docker

Add VERBOSE=1 to your .env to increase log verbosity and surface indicator values, order decisions, and cache hit/miss statistics.

Get Started

Architecture

Configuration

Guides

Configuring Backtest, Paper, and Live Execution Modes

The `--entry` Guard

Backtest Mode

Running Backtest Locally

Running Backtest in Docker

Live Mode

Running Live Locally

Paper Mode

Running Paper Locally

The `--ui` Flag and Web Dashboard

Mode Comparison

Local vs Docker Execution

Debugging a Running Strategy

Local debug (inspect)

Docker logs

Build docs developers (and LLMs) love

Get Started

Architecture

Configuration

Guides

Documentation Index

​The --entry Guard

​Backtest Mode

​Running Backtest Locally

​Running Backtest in Docker

​Live Mode

​Running Live Locally

​Paper Mode

​Running Paper Locally

​The --ui Flag and Web Dashboard

​Mode Comparison

​Local vs Docker Execution

​Debugging a Running Strategy

​Local debug (inspect)

​Docker logs

Build docs developers (and LLMs) love

The `--entry` Guard

Backtest Mode

Running Backtest Locally

Running Backtest in Docker

Live Mode

Running Live Locally

Paper Mode

Running Paper Locally

The `--ui` Flag and Web Dashboard

Mode Comparison

Local vs Docker Execution

Debugging a Running Strategy

Local debug (inspect)

Docker logs