How to run the IronFlow server in Docker¶

Quick path for a single-container API server with embedded scheduler and local worker (Tier A). For production-shaped Postgres + services + HTTP workers, use Docker Compose. Overview: Self-hosted server.

Prefect example to borrow from: Run the Prefect server in Docker — same “one container, publish the API port” shape; IronFlow serves the API on 8000 (Prefect’s UI/API default is 4200).

Pull a release image (when published)¶

docker pull ghcr.io/pppsdavid/ironflow-server:0.2.0

docker run -p 8000:8000 \
  -v ironflow-data:/data \
  -e IRONFLOW_HISTORY_PATH=/data/ironflow_history.jsonl \
  ghcr.io/pppsdavid/ironflow-server:0.2.0

Open http://127.0.0.1:8000/health — expect {"status":"ok"}.

Build from this repository¶

# Build a wheel from the current checkout (needs Rust toolchain for the native engine)
mkdir -p dist/wheels
python -m pip install build
python -m build --wheel --outdir dist/wheels --directory python-shim

docker build -f deploy/docker/Dockerfile.server \
  --build-arg INSTALL_MODE=local \
  -t ironflow-server:local .

Or use a PyPI wheel inside the image (no local cargo):

mkdir -p dist/wheels
docker build -f deploy/docker/Dockerfile.server \
  --build-arg INSTALL_MODE=pypi \
  --build-arg IRONFLOW_VERSION=0.2.0 \
  -t ironflow-server:0.2.0 .

Run¶

docker run -p 8000:8000 \
  -v ironflow-data:/data \
  -e IRONFLOW_HISTORY_PATH=/data/ironflow_history.jsonl \
  ironflow-server:local

Important container settings (same idea as Prefect’s --host 0.0.0.0):

The image binds 0.0.0.0:8000 inside the container.
Map a host port with -p 8000:8000.
Persist state with a volume on /data (IRONFLOW_HISTORY_PATH).

Point clients at the host-mapped URL:

export IRONFLOW_API_URL=http://127.0.0.1:8000
ironflow deploy --file ironflow.yaml --all

Optional: basic auth¶

See Secure a self-hosted server. Example:

docker run -p 8000:8000 \
  -v ironflow-data:/data \
  -e IRONFLOW_SERVER_API_AUTH_STRING='admin:pass' \
  ironflow-server:local

Clients and CLI:

export IRONFLOW_API_AUTH_STRING='admin:pass'
curl -u admin:pass http://127.0.0.1:8000/api/deployments

Validate end-to-end¶

bash scripts/docker_server_smoke.sh

PyPI package vs Docker image¶

Install path	Best for
`pip install ironflow-prefect-compat`	Flow code, libraries, custom processes
`docker pull ghcr.io/.../ironflow-server`	Running the control-plane API without managing Python/uvicorn

Both ship the same wheel version; the image is an opinionated server runtime. Maintainer notes (PyPI vs GHCR tags) live in deploy/docker/README.md in the repository.