Skip to content
Holdout LabHoldout Lab

Deployment

Holdout Lab is designed for one deployment shape: local, on your own machine, bound to 127.0.0.1. Its defenses are sized to that — see the security model.

The processes

Section titled “The processes”
Component How it runs Notes
Postgres Docker (infra/docker-compose.yml) App state.
Redis Docker Job queue + pub/sub.
IB Gateway (paper / live) Docker, behind compose profiles ib / ib-live Only needed for trading.
API host (uv run) FastAPI/Uvicorn.
Worker host (uv run) The arq worker — runs the engine.
Frontend host (Vite dev server) or built static assets The SPA.
Paper/Live runners host (uv run python -m ats.paper/ats.live) The trading nodes.

The compose stack binds services to 127.0.0.1 — nothing listens publicly by default.

For a zero-toolchain evaluation there is also a fully containerized app profile (api + worker + built web UI in Docker) — one command, one browser tab. Host-run stays the supported mode for IB trading.

Scripts

Section titled “Scripts”
  • scripts/setup.sh — scaffold backend/.env with a generated session secret.
  • scripts/start.sh — start the API, worker, and frontend (runs migrations; logs to .run/). Add --prod for the no-reload, built-frontend mode.
  • scripts/stop.sh — stop them (graceful SIGTERM→SIGKILL; --keep-services leaves Postgres/Redis).

Start the supporting services with docker compose -f infra/docker-compose.yml up -d postgres redis (add the ib / ib-live profiles when trading).

For an always-on machine — launchd supervision that survives crashes and reboots, a deep health probe, scheduled backups with a tested restore, and log rotation — see the production runbook.

Configuration

Section titled “Configuration”

Everything is in backend/.env (see the configuration reference). Both the API and worker read it at startup, so restart after changing a setting.

Rendering these docs as a website (later)

Section titled “Rendering these docs as a website (later)”

This documentation is authored as portable Markdown under docs/ with relative links and minimal tool-specific syntax, so it can be rendered by any static-site generator when you build the marketing site. The structure maps cleanly to a nav: docs/index.md is the home, and each top-level folder (overview/, getting-started/, …) is a section. Recommended generators:

  • MkDocs Material (Python; mkdocs.yml nav mirrors the folder tree) — closest to this repo’s tooling.
  • Astro Starlight or Docusaurus (JS) — richer marketing-site theming.

docs/llms.txt doubles as the standard /llms.txt for the site (a pointer file for LLMs). Nothing about the current docs depends on a generator; pick one when the site is wanted.

Section titled “Related”