Deployment

Compose is for local evaluation. The Helm chart is the production path. Both modes run the command API, runtime, query API, sync worker, frontend, and gateway.

Compose files

The deploy builder merges the release override into one file and embeds gateway/nginx.conf, so the generated file does not need a checkout of the product repository. It requires Compose v2.23 or newer. A checkout uses ARTIFICIALFLOW_IMAGE_TAG=v1.1.0 make up-external-iam-release. The walkthrough is in Getting started.

Published images are artificialflow/workflow-command, artificialflow/workflow-runtime, artificialflow/workflow-query, artificialflow/sync-worker, and artificialflow/frontend. Tags 1.1.0, v1.1.0, and 1.1 share one digest. The chart and the Compose default pin 1.1.0. The deploy builder writes v1.1.0, the tag the image guide prefers. For this release, azizaltaleb/* publishes the same manifests. New installs use artificialflow/*.

Compose identity

Fresh Compose deployments use project name artificialflow. The files leave container_name unset so Compose derives names from the project and service. These volume names are explicit:

• artificialflow-postgres-data
• artificialflow-elasticsearch-data

An install created from another directory or another COMPOSE_PROJECT_NAME can already own different names. Discover those names before attaching storage. A wrong override mounts empty volumes and can look like data loss. Back up the old volumes first, and keep the legacy environment overrides together as the rollback configuration. Skip volume-deleting cleanup during that rename.

docker compose -f docker-compose.external-iam.yml config --quiet
bash scripts/validate_compose_identities.sh

Kubernetes

A production install needs:

• A cluster, Helm 3, and kubectl.
• An ingress controller, DNS, and a TLS secret for the ArtificialFlow hostname.
• Reachable Postgres and Elasticsearch.
• Reachable Kafka plus Debezium Connect.
• A registry the cluster can pull, and a Secret for every credential.

There is no published Helm repository. Clone the tag that matches the images. Create an environment values file and layer it on the checked-in IAM example. The builder follows the schema in charts/artificialflow/values.yaml and writes that overlay as one file, so its install command uses a single -f.

git clone --depth 1 --branch v1.1.0 https://github.com/artificialflow/artificialflow.git
cd artificialflow
helm upgrade --install artificialflow ./charts/artificialflow \
  --namespace artificialflow --create-namespace \
  -f ./charts/artificialflow/values-external-iam.yaml \
  -f ./values-production.yaml

Pin every ArtificialFlow image tag. Point Postgres at an existing Secret whose key is PG_DSN, and set Elasticsearch and Kafka to addresses you operate:

postgresql:
  existingSecret: artificialflow-postgres
  existingSecretKey: PG_DSN
search:
  backend: elasticsearch
  address: https://elasticsearch.example.internal:9200
eventBus:
  type: kafka
  kafka:
    brokers: kafka.example.internal:9092
syncWorker:
  env:
    connectUrl: http://debezium-connect.example.internal:8083
    connectBootstrapEnabled: "false"

Kafka production leaves connector registration off. The embedded connector config is the Compose development connection. Provision Debezium through a process that can read secrets. syncWorker.env.connectorJson can override that config, and it is rendered into a ConfigMap, so it stays free of the database password. Postgres must allow logical replication, and the connector identity must be able to read the captured tables and manage the publication and slot.

In external introspection mode, postgresql.existingSecret also contains AUTH_INTROSPECTION_CLIENT_SECRET, unless the chart creates that key from iam.auth.introspectionClientSecret.

Upgrades and canonical names

Fresh Helm installs use release name artificialflow, canonical selectors, canonical Secrets and PVCs, and artificialflow/* images. Stock images run as UID and GID 10001.

An in-place upgrade of an older release keeps the live fullname and immutable selectors with compatibility.legacyResourceNames. Set enabled, fullnameOverride, selectorNameOverride, and selectorInstanceOverride from the running manifests. Leave that block disabled on a fresh install. The v1.1.0 chart validates those four fields when the block is enabled. The deployment guide also names values-legacy-persistent-identifiers.yaml; that example is not in the v1.1.0 tag, so derive the values from the live release.

Moving an old release onto the canonical names is a second install, with traffic still on the old stack until health, IAM, and a write-to-query check pass. Keep the two writers off one database, connector slot, consumer group, or ReadWriteOnce claim. Roll back by returning DNS to the old stack and its recorded values.

After install

kubectl get pods -n artificialflow
kubectl get ingress -n artificialflow
curl -fsS https://app.example.com/api/health
curl -fsS https://app.example.com/api/query/health

Pod readiness and HTTP health show that the process is up. Finish with an OIDC login, the expected roles from /api/identity/me, a running Debezium connector, and a workflow that can be deployed, started, and found through the query API. Sync health can return HTTP 200 with status starting or degraded while healthFailOnStale is false.

Command and runtime currently run GORM AutoMigrate on startup. There is no separate migration Job. Plan schema changes and rollbacks with that in mind. Replace example hostnames, keep audience validation on, store SDK profiles in a secret manager, and verify image signatures before rollout. More operational checks are in Operations.