Skip to content
ArtificialFlow

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 ComposeHelm chart
Use forLocal evaluation and developmentKubernetes, staging, production
Filedocker-compose.ymlcharts/artificialflow
Default IAMIAM_DEPLOYMENT_MODE=falseiam.mode: true
DependenciesPostgres, Elasticsearch, Kafka, and Debezium Connect in containersBundled 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, and 9200.
  • 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 building

make 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 up

Create 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/status

Open http://localhost:9100 and sign in.

SurfaceURL
UI and gatewayhttp://localhost:9100
Command APIhttp://localhost:9100/api/v1
Query APIhttp://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.js

Python 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.