Skip to content

Quickstart: first deployment

End-to-end path for a PyPI user who wants a named deployment, a running API, and a triggered run — similar to Prefect's "first deployable workflow" tutorial.

Prerequisites

  1. Installation — pip install ironflow-prefect-compat (Python 3.11 or 3.12).
  2. A terminal where the ironflow CLI is on your PATH (included in the wheel).
  3. This tutorial uses uvicorn to start the API (bundled with the package dependencies). The repository's scripts/ironflow_server.py helper is optional and requires a clone.

Overview

flowchart LR
  A[Write flow file] --> B[Start API]
  B --> C[ironflow init]
  C --> D[ironflow deploy]
  D --> E[Trigger run]

1. Write a flow module

Create a project directory and flows/hello.py:

from prefect_compat import flow, task


@task
def greet(name: str) -> str:
    return f"Hello, {name}!"


@flow
def hello_flow(name: str = "IronFlow") -> str:
    return greet.submit(name).result()

2. Start the API

In one terminal, from your project directory:

export IRONFLOW_HISTORY_PATH="$(pwd)/data/ironflow_history.jsonl"
python -m uvicorn prefect_compat.server:app --host 127.0.0.1 --port 8000

Check health:

curl -s http://127.0.0.1:8000/health

The embedded local worker and scheduler are enabled by default (IRONFLOW_ENABLE_LOCAL_WORKER=1, IRONFLOW_ENABLE_SCHEDULER=1). See Environment variables to disable them for split-process workers.

OpenAPI docs: http://127.0.0.1:8000/docs

3. Initialize ironflow.yaml

In a second terminal (same project directory):

ironflow init

Edit the generated manifest so the deployment points at your flow:

ironflow-version: "1"

pull:
  - step: ironflow.deployments.steps.set_working_directory
    inputs:
      directory: .

deployments:
  - name: hello-deployment
    entrypoint: flows/hello.py:hello_flow
    parameters:
      name: World
    work_pool:
      name: default-process-pool

4. Deploy

export IRONFLOW_API_URL=http://127.0.0.1:8000
ironflow deploy --file ironflow.yaml --name hello-deployment

5. Trigger a run

curl -s -X POST "http://127.0.0.1:8000/api/deployments/by-name/hello-deployment/run" \
  -H "Content-Type: application/json" \
  -d '{"parameters": {"name": "Deployment"}}'

List flow runs:

curl -s "http://127.0.0.1:8000/api/flow-runs?limit=5"

6. Optional: web UI

The Vite UI requires a repository clone (npm --prefix frontend run dev). PyPI-only users can inspect runs via the REST API or OpenAPI UI at /docs.

If you have the repo: How to run the server and UI and Verify the web UI.

Next steps