Skip to content
ArtificialFlow

Getting started

Start Postgres, Elasticsearch, Kafka, Debezium, and ArtificialFlow on your machine, pointed at the OIDC provider you already run. Then open the UI, or call the gateway from Node.js, Python, or Go.

What you need

  • Docker Engine or Docker Desktop, with Compose v2.23 or newer for files from the deploy builder.
  • Free local ports 5432, 8080, 8081, 8083, 8092, 9092, 9100, and 9200.
  • Enough memory for Elasticsearch, Kafka, and Debezium.
  • An OIDC provider with the clients and roles in IAM and roles. curl for the checks below. Node.js 20 or newer if you run the Node.js SDK on the host. Python 3.10 or newer if you run the Python worker.

Start the stack

Clone release v1.1.0, or generate a single file on the deploy page. On that page, Integrate with IAM true keeps the OIDC settings. False sets IAM_DEPLOYMENT_MODE to disabled and starts the stack without a login provider. The checkout uses docker-compose.external-iam.yml. docker-compose.release.yml pulls published images instead of building from source.

Build images from the checkout:

git clone --depth 1 --branch v1.1.0 https://github.com/artificialflow/artificialflow.git
cd artificialflow
make smoke-core
make up-external-iam

make up-external-iam runs docker compose -f docker-compose.external-iam.yml up -d --build. Replace the issuer placeholders in that file before the first start.

Start the same stack from published images:

export ARTIFICIALFLOW_IMAGE_TAG=v1.1.0
make up-external-iam-release

The equivalent Compose command is:

docker compose -f docker-compose.external-iam.yml -f docker-compose.release.yml up -d

Docker Hub tags v1.1.0, 1.1.0, and 1.1 are the same image digest. The Compose file defaults to 1.1.0, and the Helm chart pins 1.1.0. The image guide prefers v1.1.0. New installs use the artificialflow/* repositories. For this release, azizaltaleb/* points at the same manifests.

Open the UI at http://localhost:9100. Register that origin as the login redirect, silent redirect, post-logout redirect, and allowed web origin. The service-account token must contain the workflow-backend audience and the artificialflow client role.

cd clients/nodejs-sdk
npm ci
npm test
ARTIFICIALFLOW_TOKEN="$EXTERNAL_IAM_ACCESS_TOKEN" \
  ARTIFICIALFLOW_BASE_URL=http://localhost:9100/api \
  node examples/sdk-smoke-test.js

That checks a Node.js client. A Python or Go service that only completes jobs can skip it and follow the worker examples on the SDKs page. The HTTP contract, Swagger UI, and Postman collection are on the HTTP API page.

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

Command and query health return {"status":"ok"}. The Debezium connector and its tasks report RUNNING. The connector name is the legacy wire identifier kept for rolling upgrades. A deployment is ready for use after a browser login, an authenticated /api/identity/me response, a started workflow, and that instance appearing through the query API.

Stop

From a checkout, make down-external-iam stops the stack. make clean-external-iam also deletes the named volumes. A file from the deploy builder stops with docker compose -f artificialflow.compose.yml down.

Fresh Compose deployments use project name artificialflow and the volumes artificialflow-postgres-data and artificialflow-elasticsearch-data. Attach an older install only with the project and volume names that already exist. A wrong name mounts empty storage. Keep -v off that recovery path. The full identity rules are in Deployment.