Run Your First Backtest with PostgreSQL and Redis in Docker

backtest-kit-redis-postgres-pgpool-docker provides two ways to run your strategy: a local run where Node.js executes on your host machine against dockerized infrastructure, and a full Docker deploy where the strategy, runner, and backtest-kit container are bundled together. This page walks through both paths.

You need Docker, Docker Compose, and Node.js 20+ installed before continuing. Clone the repository and run npm install first.

Local Run
Full Docker Deploy

The local path runs Node.js on your host machine while PostgreSQL (via Pgpool-II) and Redis run in containers. This is the fastest development loop because you can edit and rebuild without rebuilding a Docker image.

Start the Pgpool-II cluster

docker-compose -f docker/pgpool/docker-compose.yaml up -d

This starts the tripolskypetr/pgpool:latest all-in-one container, which boots one primary + two streaming replicas behind a Pgpool-II proxy, all reachable on :5432. Writes are routed to the primary; reads are load-balanced across the replicas.

First boot takes 60–90 seconds while the two replicas clone from the primary. The healthcheck has a start_period of 120 s to account for this. Wait until docker ps shows the container as healthy before proceeding to the next step.

Start Redis

docker-compose -f docker/redis/docker-compose.yaml up -d

This starts redis:7.4.1 on :6379 with password mysecurepassword. Data is bind-mounted to docker/redis/redis_data/ so it survives restarts.

Copy the environment file

cp .env.example .env

The example file ships with the correct defaults for the local cluster:

CC_REDIS_HOST=host.docker.internal
CC_POSTGRES_CONNECTION_STRING=postgres://backtest:mysecurepassword@host.docker.internal:5432/backtest-pro

host.docker.internal resolves to your host machine from inside containers. For a purely host-side run the Node process reads .env directly, so host.docker.internal is substituted at runtime. No changes are needed for a standard local setup.

Choose a mode and run

The CLI accepts --entry (required to actually execute), a mode flag, and an optional --ui flag that enables the web dashboard on :60050. Pass the compiled strategy bundle as the final positional argument.

Backtest

Replay historical candles over the configured time window:

npm run start -- --entry --backtest --ui ./build/index.cjs

The backtest.ts entry point warms the candle cache via warmCandles() and then calls Backtest.background(). Both Postgres and Redis are fully initialized before any strategy code runs.

Live

Connect to a live exchange feed:

npm run start -- --entry --live --ui ./build/index.cjs

The live.ts entry point skips candle warming and calls Live.background() directly. Real order execution is active in this mode — use paper mode for dry runs.

Paper

Forward-test without real orders:

npm run start -- --entry --paper --ui ./build/index.cjs

The paper.ts entry point follows the same runtime path as live mode but without sending orders to the exchange. Ideal for validating a strategy before going live.

Verify the web UI

Open http://localhost:60050 in your browser. The --ui flag instructs @backtest-kit/cli to serve the web dashboard, where you can monitor open signals, equity curves, and strategy logs in real time.

The container healthcheck also polls http://localhost:60050/api/v1/health/health_check every 30 seconds, so a healthy response confirms the full stack is running.

The full Docker path bundles your compiled strategy, the backtest-kit runner, and the @backtest-kit/cli binary into a single container. The Pgpool-II cluster and Redis still run as separate containers; the main docker-compose.yaml uses extra_hosts: host.docker.internal:host-gateway so the app container can reach them on the host.

Start the infrastructure containers

If they are not already running, bring up the Pgpool-II cluster and Redis:

docker-compose -f docker/pgpool/docker-compose.yaml up -d
docker-compose -f docker/redis/docker-compose.yaml up -d

Wait for both containers to report healthy before continuing (up to 90 s for the Pgpool cluster on first boot).

Copy the environment file

cp .env.example .env

The main docker-compose.yaml mounts .env via env_file and passes every variable through to the container. No other configuration is needed for the default setup.

Start the backtest-kit container

via npm script

The start:docker script builds the strategy bundle and sets all required env vars for a backtest run:

npm run start:docker

This expands to:

npm run build && cross-env MODE=backtest ENTRY=1 UI=1 STRATEGY_FILE=./build/index.cjs docker-compose up -d

via docker-compose directly

Set MODE, ENTRY, UI, and STRATEGY_FILE explicitly to run any mode:

# Backtest
MODE=backtest ENTRY=1 UI=1 STRATEGY_FILE=./build/index.cjs docker-compose up -d

# Live
MODE=live ENTRY=1 UI=1 STRATEGY_FILE=./build/index.cjs docker-compose up -d

# Paper
MODE=paper ENTRY=1 UI=1 STRATEGY_FILE=./build/index.cjs docker-compose up -d

Follow the logs

docker-compose logs -f

You should see Postgres and Redis initialization messages, followed by candle warming (backtest mode) or exchange connection output (live/paper mode), and finally the web UI startup message.

Verify the web UI

Open http://localhost:60050. The container exposes port 60050 and includes a healthcheck that pings /api/v1/health/health_check every 30 seconds.

Stop the container

npm run stop:docker
# or equivalently:
docker-compose down

Environment Variables Reference

The container and the CLI both consume variables from .env. The full set of recognized variables:

Variable	Purpose	Default
`MODE`	Running mode: `backtest` \| `live` \| `paper`	—
`STRATEGY_FILE`	Path to the compiled strategy bundle	`./build/index.cjs`
`ENTRY`	Set to `1` to actually run (mirrors `--entry` CLI flag)	—
`UI`	Set to `1` to enable the web dashboard on `:60050`	—
`SYMBOL`	Override strategy symbol context	—
`STRATEGY`	Override strategy name context	—
`EXCHANGE`	Override exchange name context	—
`FRAME`	Override frame name context	—
`TELEGRAM`	Enable Telegram notifications	—
`VERBOSE`	Enable verbose logging	—
`NO_CACHE`	Disable the Redis read cache	—
`NO_FLUSH`	Skip cache flush on startup	—
`CC_POSTGRES_CONNECTION_STRING`	Full Postgres connection string	see `.env.example`
`CC_REDIS_HOST`	Redis hostname	`host.docker.internal`
`CC_REDIS_PORT`	Redis port	`6379`
`CC_REDIS_USER`	Redis username	`default`
`CC_REDIS_PASSWORD`	Redis password	`mysecurepassword`

CLI Flags

When running locally via npm run start, the flags are passed directly to @backtest-kit/cli:

Flag	Type	Description
`--entry`	boolean	Required. Without it, every `main()` function returns immediately and nothing runs.
`--backtest`	boolean	Select backtest mode. Mutually exclusive with `--live` and `--paper`.
`--live`	boolean	Select live trading mode.
`--paper`	boolean	Select paper trading mode.
`--ui`	boolean	Enable the web dashboard on `:60050`. The strategy bundle path is passed as a positional argument (e.g. `./build/index.cjs`).

Single-Node Postgres for CI

The Pgpool-II cluster is designed for development and production. If you need a simpler setup — for example, in a CI pipeline where the replica boot delay is unacceptable — use the single-node alternative:

docker-compose -f docker/postgres/docker-compose.yaml up -d

This starts postgres:16-alpine directly on :5432 with the same credentials as the cluster. The .env.example connection string works without modification.

The single-node container hides stale-read bugs. A write followed by a separate SELECT always looks correct on one node because all I/O goes through the same process. Use the Pgpool cluster for any testing that involves concurrent writes or connection pooling.

The schema (tables, unique indexes) is created automatically on first connect via TypeORM synchronize: true. There is no manual migration step for either the cluster or the single-node alternative.

Get Started

Architecture

Configuration

Persist Adapters

Strategy Development

Environment Variables Reference

CLI Flags

Single-Node Postgres for CI

Build docs developers (and LLMs) love

Get Started

Architecture

Configuration

Persist Adapters

Strategy Development

Documentation Index

​Environment Variables Reference

​CLI Flags

​Single-Node Postgres for CI

Build docs developers (and LLMs) love

Environment Variables Reference

CLI Flags

Single-Node Postgres for CI