Hippodrome Docker Packaging

Self-contained Docker image that runs the full Hippodrome stack without Pants at runtime.

Build

Two-step process: Pants builds PEX files, Docker assembles the runtime image.

# 1. Build PEX files (Pants caches dependencies across runs)
pants package //components/hippodrome:: //components/fake_cell:run //components/fake_cognito:run

# 2. Build Docker image (copies PEX files from dist/)
docker build -f components/hippodrome/Dockerfile -t hippodrome .

Run

docker run -p 9000-9019:9000-9019 hippodrome                   # full profile
docker run -p 9000-9019:9000-9019 hippodrome up --profile ecom  # ecom only
docker run -p 9000-9019:9000-9019 hippodrome up --no-seed       # skip seeding

Architecture

The Docker image contains these service packaging types:

Type	Services	Packaging
Python (PEX)	fake_cell, fake_cognito, admin_server, admin_lambda, fork_action_worker, ecom_indexer, ecom_indexer_trigger, ecom_settings_exporter, merchandising_exporter	Pre-built PEX files at /opt/hippodrome/pex/
Go binaries	ecom_indexer_service, ecom_ingest	Static binaries at /opt/hippodrome/bin/
Node.js (Wrangler)	search_proxy, agentic_search, admin_worker	Source + node_modules at /opt/hippodrome/src/components/
Django (venv)	controller	Python 3.11 venv at /opt/hippodrome/controller-venv/
React (static)	console	Production build served by python3 -m http.server

The Hippodrome orchestrator (cli.pex) manages all services. It detects Docker mode via the HIPPODROME_PEX_DIR environment variable and uses PEX commands instead of pants run.

Docker mode

When HIPPODROME_PEX_DIR is set, config.py changes behaviour:

• build_run_command() emits PEX execution commands instead of pants run
• Console serves a static build via python3 -m http.server instead of npm run dev
• Controller uses the Docker venv path instead of .venv/
• Wrangler workers use absolute source paths under HIPPODROME_SRC_DIR
• _find_project_root() falls back to HIPPODROME_SRC_DIR (no pants.toml at runtime)

EC2 sizing

Instance	vCPU	RAM	Fit
t3.medium	2	4GB	Tight
t3.large	2	8GB	Recommended
t3.xlarge	4	16GB	Generous

Baseline memory: ~2.1GB (11 Python services ~100MB each, 3 Wrangler workers ~200MB each, moto ~200MB). PEX packaging eliminates ~2.5GB of Pants client overhead vs local dev.

CI

The hippodrome_docker.yaml workflow builds and smoke-tests the image on PRs that change Hippodrome files or Go inputs copied into the image. It uses the pantsbuild/actions/init-pants action for cached Pants bootstrapping, then runs docker build separately.