Docker Compose Layout and Service Configuration Guide

The project ships four Docker Compose files that cover every deployment scenario from a single-node CI run to a full production-like cluster. They are intentionally kept separate so you can compose only the services you need, rather than starting everything in one command.

docker/
  pgpool/docker-compose.yaml    # recommended for dev: 1 primary + 2 replicas + Pgpool-II
  postgres/docker-compose.yaml  # single postgres:16-alpine (CI / simple use)
  redis/docker-compose.yaml     # redis:7.4.1 on :6379
docker-compose.yaml             # main: backtest-kit container, mounts project as /workspace

Service Files

Pgpool cluster (recommended)
Single Postgres (CI)
Redis
Main compose (strategy container)

File: docker/pgpool/docker-compose.yamlRuns the all-in-one tripolskypetr/pgpool:latest image, which bundles a full PostgreSQL streaming-replication cluster — one primary and two read replicas — behind a Pgpool-II load balancer, all inside a single container. The external interface is a single port 5432; Pgpool-II routes write queries to the primary and distributes reads across both replicas transparently.

services:
  pgpool:
    image: tripolskypetr/pgpool:latest
    container_name: pgcluster
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: backtest
      POSTGRES_PASSWORD: mysecurepassword
      POSTGRES_DB: backtest-pro
      REPL_USER: replicator
      REPL_PASSWORD: replicatorpass
      PGCLUSTER_ROOT: /var/lib/pgcluster
      PGBIN: /usr/local/bin
    volumes:
      - ./data:/var/lib/pgcluster
    healthcheck:
      test: ["CMD-SHELL", "PGPASSWORD=mysecurepassword psql -h 127.0.0.1 -p 5432 -U backtest -d backtest-pro -tAc 'SELECT 1' || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 15
      start_period: 120s
    restart: always

Environment variables

POSTGRES_USER

string

default:"backtest"

The application role that the adapter layer connects as. Must match the username in CC_POSTGRES_CONNECTION_STRING.

POSTGRES_PASSWORD

string

default:"mysecurepassword"

Password for POSTGRES_USER. Must match the password in CC_POSTGRES_CONNECTION_STRING and the Redis requirepass value if you want the defaults to stay consistent across services.

POSTGRES_DB

string

default:"backtest-pro"

Database name created on first boot. Must match the database segment of CC_POSTGRES_CONNECTION_STRING.

REPL_USER

string

default:"replicator"

Internal replication role used by the standby nodes to stream WAL from the primary. Never exposed outside the container.

REPL_PASSWORD

string

default:"replicatorpass"

Password for REPL_USER. Change together with REPL_USER when hardening the cluster.

PGCLUSTER_ROOT

string

default:"/var/lib/pgcluster"

Root directory inside the container where the primary and replica data directories live. The volume mount ./data:/var/lib/pgcluster maps this to a local folder so cluster state survives container restarts.

PGBIN

string

default:"/usr/local/bin"

Directory containing the PostgreSQL binary tools (pg_basebackup, pg_ctl, etc.) used by the init scripts inside the image. Rarely changed.

Volume mount

Cluster data is bind-mounted to ./data (relative to docker/pgpool/). This directory is gitignored so data survives restarts and is easy to inspect or wipe:

# Wipe all cluster data and start fresh
rm -rf docker/pgpool/data
docker-compose -f docker/pgpool/docker-compose.yaml up -d

Healthcheck and startup time

The healthcheck polls every 10 seconds with a 120-second start_period. The extended start period is necessary because the first boot clones two streaming replicas from the primary via pg_basebackup, which takes approximately 60–90 seconds on typical hardware.

Do not reduce start_period below 90 seconds. Docker will mark the container unhealthy before replication is complete, which can cause dependent services to fail their own startup checks.

Why use this in development?

The replica cluster catches a class of bugs that are invisible on a single-node database. PostgreSQL on a single node is one process — all reads and writes go through the same memory, so a write followed immediately by a SELECT always returns the just-written value. On a cluster, reads are load-balanced to asynchronous replicas that lag the primary by a few milliseconds. Any adapter code that does a follow-up SELECT after a write will silently return stale data in production but pass every test on a single node.

All upsert operations in this project return the written row via RETURNING * in the same statement and seed the Redis cache from that result — never from a follow-up read. Running the dev cluster confirms this invariant is preserved end-to-end.

File: docker/postgres/docker-compose.yamlA minimal single-node postgres:16-alpine container. Use this for CI pipelines or quick local experiments where a full cluster is unnecessary overhead.

version: "3.8"
services:
  postgres:
    image: postgres:16-alpine
    container_name: postgres
    environment:
      POSTGRES_USER: backtest
      POSTGRES_PASSWORD: mysecurepassword
      POSTGRES_DB: backtest-pro
    ports:
      - "5432:5432"
    volumes:
      - ./pg_data:/var/lib/postgresql/data
    restart: always
volumes:
  pg_data:

Data is stored in a bind-mount at ./pg_data (relative to docker/postgres/) mapped to the standard PostgreSQL data directory. The image initialises the database on first start using the POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB variables, which mirror the defaults in CC_POSTGRES_CONNECTION_STRING.

The single-node setup deliberately omits a healthcheck — most CI orchestrators handle readiness probes differently, and the TypeORM DataSource.initialize() call will retry on its own. Add a healthcheck if your pipeline requires it.

File: docker/redis/docker-compose.yamlRuns redis:7.4.1 with password authentication enabled via the --requirepass server flag.

version: '3.8'
services:
  redis:
    image: redis:7.4.1
    container_name: redis
    ports:
      - "6379:6379"
    environment:
      - REDIS_PASSWORD=mysecurepassword
    command: ["redis-server", "--requirepass", "mysecurepassword"]
    volumes:
      - ./redis_data:/data
    restart: always
volumes:
  redis_data:

The password mysecurepassword matches the default value of CC_REDIS_PASSWORD in src/config/params.ts. Change both together if you need a different credential.Redis data is persisted via a bind-mount at ./redis_data (relative to docker/redis/). A 30-second keep-alive PING is sent by the getRedis singleton in src/config/redis.ts to prevent idle-timeout disconnections on managed Redis services.

File: docker-compose.yamlRuns the tripolskypetr/backtest-kit image with the entire project directory bind-mounted as /workspace. This is the file you use for a full Docker deploy where the strategy, CLI, and persistence layer all run inside the container.

version: '3.8'
services:
  backtest:
    image: tripolskypetr/backtest-kit
    platform: linux/amd64
    extra_hosts:
      - "host.docker.internal:host-gateway"
    container_name: backtest-kit-redis-mongo-docker
    ports:
      - "60050:60050"
    restart: unless-stopped
    volumes:
      - ./:/workspace
    working_dir: /workspace
    environment:
      - MODE
      - STRATEGY_FILE
      - SYMBOL
      - STRATEGY
      - EXCHANGE
      - FRAME
      - UI
      - TELEGRAM
      - VERBOSE
      - NO_CACHE
      - NO_FLUSH
      - ENTRY
    env_file:
      - .env
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:60050/api/v1/health/health_check"]
      interval: 30s
      timeout: 10s
      retries: 3

Key configuration points

extra_hosts: host.docker.internal:host-gatewayThis Linux-specific alias maps host.docker.internal to the Docker bridge gateway IP, giving the container a stable hostname to reach services running on the host. Set CC_REDIS_HOST=host.docker.internal and use host.docker.internal in CC_POSTGRES_CONNECTION_STRING when the database containers are started separately via docker/pgpool/ or docker/redis/.Volume mount ./:/workspaceThe entire project directory is mounted read-write at /workspace. The STRATEGY_FILE variable (default ./build/index.cjs) is resolved relative to this path, so running npm run build on the host before docker-compose up is enough to make the latest compiled bundle available inside the container.HealthcheckThe container is considered healthy when GET http://localhost:60050/api/v1/health/health_check returns HTTP 200. This endpoint is served by the @backtest-kit/cli web UI and becomes available only after both PostgreSQL and Redis connections are established. The check runs every 30 seconds with a 10-second timeout and up to 3 retries before the container is marked unhealthy.

The web UI (and therefore the healthcheck endpoint) is only active when UI=1 is set. If you run without UI=1, the healthcheck will always fail. Either set UI=1 or remove the healthcheck stanza if you do not need the UI.

Port Mapping Summary

Service	Host port	Container port	Compose file
Pgpool-II / PostgreSQL	`5432`	`5432`	`docker/pgpool/docker-compose.yaml`
Single PostgreSQL	`5432`	`5432`	`docker/postgres/docker-compose.yaml`
Redis	`6379`	`6379`	`docker/redis/docker-compose.yaml`
backtest-kit web UI	`60050`	`60050`	`docker-compose.yaml`

Both Postgres compose files bind to host port 5432. Run only one of them at a time to avoid a port conflict.

Volume Mount Locations

Service	Host path	Container path	Purpose
Pgpool cluster	`docker/pgpool/data`	`/var/lib/pgcluster`	Primary + replica data dirs
Single Postgres	`docker/postgres/pg_data` (bind-mount)	`/var/lib/postgresql/data`	Database data directory
Redis	`docker/redis/redis_data` (bind-mount)	`/data`	RDB / AOF persistence files
backtest-kit	`./` (project root)	`/workspace`	Strategy bundle + `.env` + build output

Connecting from Inside a Container vs. the Host

Running Node on the host

Both PostgreSQL and Redis are reachable at 127.0.0.1 (or localhost) because the Docker containers publish their ports to the host network.

CC_REDIS_HOST=127.0.0.1
CC_POSTGRES_CONNECTION_STRING=postgres://backtest:mysecurepassword@localhost:5432/backtest-pro

Running strategy in Docker

The strategy container cannot reach 127.0.0.1 on the host. Use host.docker.internal, which is mapped to the host gateway by extra_hosts.

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

When running the strategy inside the tripolskypetr/backtest-kit container, always use host.docker.internal instead of 127.0.0.1 or localhost in your connection strings. Using 127.0.0.1 inside the container resolves to the container’s own loopback interface, where no database is listening, causing the DataSource.initialize() call to hang and eventually time out.

Typical Startup Sequences

Start infrastructure (development)

Boot the Pgpool cluster and Redis. Wait for the Pgpool healthcheck to turn green before proceeding — the first boot takes 60–90 seconds while replicas clone.

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

Run the strategy on the host

With infrastructure running, execute the strategy directly with Node. The TypeORM DataSource will create all tables on first connect.

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

Or run everything in Docker

Build the strategy bundle first, then start the main compose file. Set MODE, ENTRY, and optionally UI via environment variables.

npm run build
MODE=backtest ENTRY=1 UI=1 STRATEGY_FILE=./build/index.cjs docker-compose up -d
docker-compose logs -f

Using single Postgres for CI

For CI pipelines where a full replica cluster is overkill, substitute docker/postgres/docker-compose.yaml for docker/pgpool/docker-compose.yaml. The connection string stays identical because both files publish port 5432 with the same credentials:

# .github/workflows/test.yml (example)
services:
  postgres:
    image: postgres:16-alpine
    env:
      POSTGRES_USER: backtest
      POSTGRES_PASSWORD: mysecurepassword
      POSTGRES_DB: backtest-pro
    ports:
      - 5432:5432
  redis:
    image: redis:7.4.1
    ports:
      - 6379:6379

Or start the bundled file directly in your CI script:

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

Get Started

Architecture

Configuration

Persist Adapters

Strategy Development

Service Files

Environment variables

Volume mount

Healthcheck and startup time

Why use this in development?

Key configuration points

Port Mapping Summary

Volume Mount Locations

Connecting from Inside a Container vs. the Host

Running Node on the host

Running strategy in Docker

Typical Startup Sequences

Build docs developers (and LLMs) love

Get Started

Architecture

Configuration

Persist Adapters

Strategy Development

Documentation Index

​Service Files

​Environment variables

​Volume mount

​Healthcheck and startup time

​Why use this in development?

​Key configuration points

​Port Mapping Summary

​Volume Mount Locations

​Connecting from Inside a Container vs. the Host

Running Node on the host

Running strategy in Docker

​Typical Startup Sequences

Build docs developers (and LLMs) love

Service Files

Environment variables

Volume mount

Healthcheck and startup time

Why use this in development?

Key configuration points

Port Mapping Summary

Volume Mount Locations

Connecting from Inside a Container vs. the Host

Typical Startup Sequences