Getting Started

Quickstart


Start an Orcher engine on your machine, run a workflow, then crash its worker halfway through and watch the workflow finish anyway. Everything here comes from the public quickstart repository, and the same guide is on the website at orcher.io/quickstart.

What you'll build

An order workflow with two tasks and a durable timer between them:

1
charge ──▶ sleep 10s ──▶ ship

The engine records every step as it finishes, and keeps the timer itself, so no process has to stay up while it runs. A worker that dies mid-order is replaced by a new one, which picks the order up where it stopped: it ships the order without charging it again.

Prerequisites

  • Docker with Compose v2
  • For the language you pick: Python 3.11 or later, Node.js 22 or later, or stable Rust

1. Start the engine

1
git clone https://github.com/orcher-io/quickstart.git
2
cd quickstart
3
docker compose up -d --wait

This starts Postgres and the engine, which applies its database schema as it starts, with gRPC on localhost:50051 and health checks on localhost:8080/health/ready. Authentication is off: this engine is for your machine only.

2. Run a worker

A worker connects to the engine, registers the workflow and its tasks, and runs them. Pick a language and leave the worker running in its own terminal.

1
cd python
2
python3 -m venv .venv && source .venv/bin/activate
3
pip install -r requirements.txt
4
python worker.py

The workflow and its tasks, from python/worker.py:

1
@task(name="charge")
2
async def charge(ctx: TaskContext, order_id: str) -> str:
3
# Tasks are where side effects go: call the payment API here.
4
print(f"charged {order_id}", flush=True)
5
return f"charged {order_id}"
6
7
8
@task(name="ship")
9
async def ship(ctx: TaskContext, order_id: str) -> str:
10
print(f"shipped {order_id}", flush=True)
11
return f"shipped {order_id}"
12
13
14
@workflow(name="order")
15
async def order(ctx: WorkflowContext, order_id: str) -> str:
16
charged = await ctx.execute_task(charge, order_id=order_id)
17
# A durable timer: the engine keeps it, so a worker restart doesn't reset it.
18
await ctx.sleep(timedelta(seconds=10))
19
shipped = await ctx.execute_task(ship, order_id=order_id)
20
return f"{charged}, then {shipped}"

3. Start a workflow

In a second terminal, in the same directory, start an order and wait for it:

1
python start.py # Python
2
npm run start-workflow # TypeScript
3
cargo run --bin start # Rust

The worker prints charged order-…, then shipped order-… ten seconds later, and the starter prints the workflow's result:

1
started workflow order-3f9c1a7e
2
result: charged order-3f9c1a7e, then shipped order-3f9c1a7e

4. Kill the worker mid-run and watch it resume

  1. Start another order, as in step 3.
  2. When the worker prints charged order-…, the workflow is sleeping. Stop the worker with Ctrl+C, or kill it outright.
  3. The starter keeps waiting: the order is safe in the engine, not in the worker. Start the worker again, as in step 2.
  4. The new worker prints shipped order-… once the ten seconds are up, and the starter prints the result. It never prints charged again: the charge already happened, so the workflow resumes after it.

scripts/kill-and-resume.sh does the same with kill -9, and fails unless the order was charged exactly once and shipped by the second worker:

1
scripts/kill-and-resume.sh python # or typescript, or rust

It runs the examples from their directories, so install them first, as in step 2 (for Rust, cargo build --bins; for Python, set PYTHON to your virtualenv's interpreter if it isn't active).

When you're done, docker compose down -v stops the engine and deletes its data.

The engine image

ghcr.io/orcher-io/orcher:0.7.0 is the engine, open source under the Apache License 2.0 (orcher-io/orcher), like the quickstart and the SDKs. Its license ships in the image as /LICENSE, beside /THIRD_PARTY_NOTICES, which lists the open-source components built into the engine with their own licenses:

1
docker compose exec orcher cat /LICENSE
2
docker compose exec orcher cat /THIRD_PARTY_NOTICES

Next steps

Each SDK's README covers retries, events, child workflows, actors and testing:

LanguageSDKPackage
Pythonorcher-io/sdk-pyorcher-sdk on PyPI
TypeScriptorcher-io/sdk-ts@orcher/sdk on npm
Rustorcher-io/sdk-rustorcher-sdk on crates.io

Beneath them, orcher-io/sdk-core is the core the SDKs share, and orcher-io/protos holds the Protocol Buffer definitions of the API they speak.

Then read on in these docs: