Getting started
One Compose file starts the stack on a laptop. The same images and the same configuration keys run on Kubernetes from the Helm chart.
Compose or Helm
| Docker Compose | Helm chart | |
|---|---|---|
| Use for | Local evaluation and development | Kubernetes, staging, production |
| File | docker-compose.yml | charts/artificialflow |
| Default IAM | IAM_DEPLOYMENT_MODE=false | iam.mode: true |
| Dependencies | Postgres, Elasticsearch, Kafka, and Debezium Connect in containers | Bundled by default, or your own managed services |
There is one Compose file and one chart. IAM_DEPLOYMENT_MODE is the boolean true or false. Any other value, including the old external and disabled, fails startup.
Prerequisites
- Docker with Compose v2, Make, curl, and jq.
- Free ports
5432,8080,8081,8083,8092,9092,9100, and9200. - For a worker: Node.js 20+, Python 3.10+, or Go 1.26.
Start the stack
docker-compose.yml needs no .env. false is the Compose default: sign in at the console as admin / admin, and the API needs no token. That mode is for a private machine. The console login does not protect the API.
git clone --depth 1 --branch release/v1.2.0 https://github.com/artificialflow/artificialflow.git
cd artificialflow
make up # build from this checkout
make up-release # pull published images and start without buildingmake up-release runs docker compose pull and then docker compose up -d --no-build. It does not overlay a second Compose file. Run it from a checkout of the matching release. On a development branch, use make up, because published images may not match the branch. The Compose file and the chart pin 1.2.0. Git tag v1.2.0 is what the product guides name; it is not published yet, so this site clones release/v1.2.0. Docker Hub does not have tag 1.2.0 yet. The images for commit 6b80b6b are published as candidate-v1.2.0-6b80b6b7700bab43f6fe0d8c35ec062b341b90ed. Set ARTIFICIALFLOW_IMAGE_TAG to that candidate when you need a pull today. The deploy builder writes one file you can start without the rest of the checkout.
Turn on your OIDC provider before you start in true mode:
IAM_DEPLOYMENT_MODE=true \
AUTH_ISSUER_INTERNAL_URL=https://login.example.com \
AUTH_ISSUER_PUBLIC_URL=https://login.example.com \
make upCreate the backend audience workflow-backend, the browser client workflow-frontend, a machine client with artificialflowclient, and the four roles first. Recipes: Keycloak, Entra ID, and Auth0.
Verify
curl -fsS http://localhost:9100/api/health
curl -fsS http://localhost:9100/api/query/health
curl -fsS http://localhost:8092/health
curl -fsS http://localhost:8083/connectors/artificialflow-postgres-connector/statusOpen http://localhost:9100 and sign in.
| Surface | URL |
|---|---|
| UI and gateway | http://localhost:9100 |
| Command API | http://localhost:9100/api/v1 |
| Query API | http://localhost:9100/api/v1/query |
/api/... remains an unversioned compatibility alias. New clients should use /api/v1. Health stays at /api/health and /api/query/health.
Run a process
The demo process examples/golden-demo/order-approval.bpmn has a service task of type golden-validate and a user task for approver. In true mode, add Authorization: Bearer $TOKEN. Skip that header in false mode.
export API=http://localhost:9100/api/v1
curl -fsS -X POST "$API/workflows" \
-H "Content-Type: application/xml" \
--data-binary @examples/golden-demo/order-approval.bpmn
INSTANCE_ID=$(curl -fsS -X POST "$API/instances" \
-H "Content-Type: application/json" \
-d '{"workflow_id": "golden_order_approval", "context": {"orderId": "ord-1"}}' \
| jq -r .id)The instance waits at golden-validate for a worker. Pick one client:
cd clients/nodejs-sdk && npm ci && npm run build && cd ../..
ARTIFICIALFLOW_BASE_URL=http://localhost:9100/api \
ARTIFICIALFLOW_WORKER_JOB_TYPE=golden-validate \
node clients/nodejs-sdk/examples/sdk-smoke-test.jsPython and Go are worker clients only. .NET and Java also include workers. The commands are on SDKs. After the job completes, claim and complete the user task:
TASK=$(curl -fsS "$API/tasks?processInstanceKey=$INSTANCE_ID" | jq '.tasks[0]')
EXECUTION_ID=$(echo "$TASK" | jq -r .executionId)
curl -fsS -X POST "$API/instances/$INSTANCE_ID/tasks/$EXECUTION_ID/claim" \
-H "Content-Type: application/json" -d '{"assignee": "approver"}'
curl -fsS -X POST "$API/instances/$INSTANCE_ID/tasks/$EXECUTION_ID/complete" \
-H "Content-Type: application/json" -d '{"assignee": "approver"}'
curl -fsS "$API/query/instances/$INSTANCE_ID"make down stops the stack. make clean also deletes the volumes. Kubernetes is the next step in Deployment.