Documentation Index
Fetch the complete documentation index at: https://mintlify.com/theonetrade/backtest-kit-redis-mongo-docker/llms.txt
Use this file to discover all available pages before exploring further.
backtest-kit-redis-mongo-docker is a production-grade persistence layer for the backtest-kit algorithmic trading framework. It replaces the default file-based ./dump/ storage with a MongoDB-backed source of truth and a Redis ID cache, then packages all three services — the backtest runner, MongoDB, and Redis — in a docker-compose configuration that is ready to deploy on any Linux host.
The Problem with File-Based Persistence
The defaultbacktest-kit installation writes every adapter snapshot to the local ./dump/ directory. This approach works well during initial development but breaks down under production conditions for three concrete reasons.
Scalability. File I/O on a shared disk does not scale horizontally. A single slow write can block every adapter that touches the same symbol, causing read latency to grow linearly with dataset size.
Read-after-write consistency. The filesystem offers no atomic compare-and-swap semantics across multiple adapter files. A process restart between two related writes can leave the store in a partially-updated state with no way to detect or recover from it.
Look-ahead bias protection. A backtest that reads stale candle data from a previous, longer run can silently introduce future price information into a historical test, making strategy metrics meaningless. MongoDB’s document model, combined with the Redis cache flush performed at startup, prevents this class of error by enforcing a clean slate for every run.
Architecture Overview
The integration is built around three layers. MongoDB (source of truth). Every adapter persists its canonical state as a BSON document in a dedicated collection. Writes go to MongoDB first; the Redis cache is populated or invalidated only after a successful write acknowledgement. Redis (O(1) ID cache). Each adapter stores its lookup key — a composite of the fields shown in the adapter table below — as a Redis hash entry. Reads check Redis first. A cache hit returns the MongoDB_id directly, allowing a single indexed findById instead of a full collection scan.
docker-compose. Three compose files manage the full lifecycle: one for MongoDB, one for Redis, and one for the backtest runner container itself. The runner image is tripolskypetr/backtest-kit (linux/amd64) and mounts your local workspace at /workspace so that the compiled strategy bundle is always in scope.
Run Modes
The project supports three operating modes selected via CLI flags passed to the entry point.| Mode | CLI flag | Description |
|---|---|---|
| Backtest | --backtest | Replays historical candles within a fixed time window and records all signals, risk events, and partial fills to MongoDB |
| Paper | --paper | Runs the strategy against live market data without sending real orders; all state is persisted identically to live mode |
| Live | --live | Executes real orders on the configured exchange; MongoDB and Redis state is authoritative across process restarts |
--entry flag to be present. Without it the process exits immediately, which allows the same compiled bundle to be imported as a library without side effects.
Adapter Reference
All 15IPersist* adapter interfaces defined by backtest-kit are implemented. Each adapter owns exactly one MongoDB collection and derives its Redis cache key from the context tuple listed below.
| Adapter | MongoDB Collection | Cache Key Fields |
|---|---|---|
| Candle | candle-items | symbol, interval, timestamp |
| Signal | signal-items | symbol, strategyName, exchangeName |
| Schedule | schedule-items | symbol, strategyName, exchangeName |
| Risk | risk-items | riskName, exchangeName |
| Partial | partial-items | symbol, strategyName, exchangeName, signalId |
| Breakeven | breakeven-items | symbol, strategyName, exchangeName, signalId |
| Storage | storage-items | backtest, signalId |
| Notification | notification-items | backtest, notificationId |
| Log | log-items | entryId |
| Measure | measure-items | bucket, entryKey |
| Interval | interval-items | bucket, entryKey |
| Memory | memory-items | signalId, bucketName, memoryId |
| Recent | recent-items | symbol, strategyName, exchangeName, frameName, backtest |
| State | state-items | signalId, bucketName |
| Session | session-items | strategyName, exchangeName, frameName |
Redis stores only the cache key → MongoDB
_id mapping. Document payloads are never written to Redis. This keeps memory usage predictable regardless of document size.Next Steps
Quickstart
Spin up MongoDB and Redis with docker-compose and run your first backtest in under five minutes.
Architecture Overview
Deep-dive into the adapter lifecycle, the Redis invalidation strategy, and the MongoDB index design.
Adapter Reference
Full API documentation for all 15 IPersist* adapter implementations.
Environment Variables
Complete reference for CC_REDIS_HOST, CC_MONGO_CONNECTION_STRING, and all Docker env vars.