Quick Start

This guide walks through deploying a simple BPMN process and writing a worker.

1. Pull the image

Orrery is available as a Docker image from the GitHub Container Registry:

docker pull ghcr.io/orrery-io/orrery:latest

Browse all available tags at ghcr.io/orrery-io/orrery .

2. Start the server

Orrery requires a PostgreSQL database. Provision one and pass the connection details as environment variables:

docker run \
  -e DATABASE_URL=postgres://orrery:orrery@localhost:5433/orrery \
  -e ORRERY_HOST=0.0.0.0 \
  -e ORRERY_PORT=3000 \
  -p 3000:3000 \
  ghcr.io/orrery-io/orrery:latest

Once running, the Cockpit is available at http://localhost:3000 and the API explorer at http://localhost:3000/docs.

3. Deploy a BPMN process

curl -X POST http://localhost:3000/api/definitions \
  -F "file=@process.bpmn"

4. Start a process instance

curl -X POST http://localhost:3000/api/instances \
  -H "Content-Type: application/json" \
  -d '{"processDefinitionKey": "myProcess", "variables": {}}'

5. Write a worker

import { OrreryWorker } from "@orrery/sdk";
 
const worker = new OrreryWorker({
  baseUrl: "http://localhost:3000",
  topic: "myTask",
  handler: async (task) => {
    await task.complete({ result: "done" });
  },
});
 
worker.start();

Full SDK docs: TypeScript SDK

What’s next

• Cockpit — open http://localhost:3000 to access the built-in web UI for monitoring processes, inspecting instances, and viewing BPMN diagrams.
• API docs — interactive API explorer (powered by Scalar ) is available at http://localhost:3000/docs. Browse all endpoints, try requests, and download the OpenAPI spec.