Configuration

Everything is environment variables, validated once at boot. A mistyped role, a missing database URL or a malformed JSON map fails the start rather than surfacing minutes later as a confusing runtime error — or worse, as a silent default: a cluster where every workflow starts and none progresses because no process took the decider role.

Failures are reported all at once, which matters more than it sounds: fixing misconfiguration one restart at a time is how a five-minute deploy becomes an hour.

Invalid environment configuration:
  - DATABASE_URL: DATABASE_URL is required
  - NODE_FLOW_JWT_SECRET: NODE_FLOW_JWT_SECRET must be at least 32 characters
  - NODE_FLOW_ROLES: unknown role(s): decidr (expected api, decider, poller)

The rule this follows: a setting whose wrong value is silently survivable gets no default.

How values are parsed

Required

Two variables have no default, and the server will not start without them.

Core

First-install seeding

Creates the first namespace and administrator on a database that has no namespaces at all — not "no namespace by this name". That makes it idempotent in the only sense that matters: it acts once in the lifetime of a database, and every later boot is one SELECT that does nothing.

Authentication and tokens

Secrets

Empty means this install stores no secrets and says so when asked to — rather than storing them in clear, which is the failure an optional encryption key invites. Two entries is what a rotation looks like in flight: the first seals, the rest still open what they sealed before.

openssl rand -base64 32
NODE_FLOW_SECRET_KEYS='k2:NEW_KEY,k1:OLD_KEY'

Workload identity (machines)

[
  { "issuer": "https://token.actions.githubusercontent.com", "jwksUri": "https://token.actions.githubusercontent.com/.well-known/jwks", "audience": "node-flow" }
]

Each entry requires all three fields. Empty disables the mechanism entirely — an install that does not use workload identity should not be reachable by anything presenting a token from an IdP it never chose. The issuer is matched exactly; nothing looser is offered, because a prefix or hostname match is how an IdP nobody configured ends up able to mint tokens for this install.

SSO (humans)

OIDC providers require every one of name, issuer, clientId, clientSecret, authorizationEndpoint, tokenEndpoint, jwksUri, redirectUri, namespace; scopes is optional.

[
  {
    "name": "okta",
    "issuer": "https://acme.okta.com",
    "clientId": "0oa…",
    "clientSecret": "…",
    "authorizationEndpoint": "https://acme.okta.com/oauth2/v1/authorize",
    "tokenEndpoint": "https://acme.okta.com/oauth2/v1/token",
    "jwksUri": "https://acme.okta.com/oauth2/v1/keys",
    "redirectUri": "https://flows.example.com/v1/auth/sso/okta/callback",
    "namespace": "default",
    "scopes": "openid email profile"
  }
]

SAML providers require name, entryPoint, issuer, callbackUrl, namespace and idpCert (one PEM, or several during a rotation). Optional: emailAttribute, nameAttribute, privateKey, decryptionPvk, spCertificate, identifierFormat, signatureAlgorithm (sha256 or sha512), acceptedClockSkewMs.

Payloads and blob storage

# AWS — omit the credentials and the SDK reads the instance role or IRSA,
# so node-flow holds no long-lived keys.
NODE_FLOW_BLOB_S3='{"bucket":"nf-payloads","region":"eu-west-1","prefix":"prod/"}'

# MinIO and other S3-compatible endpoints
NODE_FLOW_BLOB_S3='{"bucket":"payloads","endpoint":"http://minio:9000","forcePathStyle":true,"accessKeyId":"…","secretAccessKey":"…"}'

Fields: bucket, region, endpoint, forcePathStyle, accessKeyId, secretAccessKey, prefix.

NODE_FLOW_BLOB_STORE=s3 without a bucket fails at boot with the rest of the configuration, instead of at the first payload large enough to offload — which could be days later.

Outbound HTTP

System task limits

Worker protocol

Databases for the JDBC task

NODE_FLOW_SQL_DATASOURCES='{"reporting":"postgres://reader:pw@warehouse:5432/analytics","legacy":"postgres://…"}'

Empty (the default) disables the task entirely, so an install that needs none is not exposed at all. A definition that supplies its own connection string is refused — see System tasks → JDBC.

gRPC services

{
  "pricing": {
    "address": "pricing.svc:50051",
    "protoPath": "/etc/node-flow/pricing.proto",
    "package": "pricing.v1",
    "service": "Pricing",
    "tls": false,
    "includeDirs": ["/etc/node-flow/protos"]
  }
}

address, protoPath, package and service are all required; a missing one fails the boot. tls defaults to false, because most gRPC is mesh-internal.

Message brokers

Connection names may use only letters, digits, _ and -. A connection missing its required key fails the boot rather than becoming a source that never connects.

NODE_FLOW_KAFKA_CLUSTERS='{"default":{"brokers":["kafka-1:9092","kafka-2:9092"]}}'
NODE_FLOW_NATS_CONNECTIONS='{"default":{"servers":"nats://nats:4222"}}'
NODE_FLOW_AMQP_CONNECTIONS='{"default":{"url":"amqp://guest:guest@rabbit:5672"}}'
NODE_FLOW_SQS_CONNECTIONS='{"default":{"region":"eu-west-1"}}'
NODE_FLOW_REDIS_CONNECTIONS='{"default":{"url":"redis://redis:6379"}}'

Sink and source naming

The configured sources of a running install are readable at GET /v1/ns/{ns}/event-handlers/sources.

The broker client libraries are optional peers. An install that uses none never loads them.

SMTP, for the EMAIL task

{
  "default": {
    "host": "smtp.example.com",
    "port": 587,
    "secure": false,
    "user": "…",
    "pass": "…",
    "from": "ops@example.com"
  },
  "staging": { "host": "localhost", "disabled": true }
}

Only host is required. secure: true is implicit TLS (port 465); port 587 negotiates STARTTLS and leaves it false. disabled: true makes the transport fail loudly rather than swallowing mail — a staging install that quietly drops mail teaches everyone that the task works, and the surprise arrives in production.

nodemailer is an optional peer, so an install that sends no mail never loads it.

Circuit breakers

NODE_FLOW_CIRCUIT_BREAKER='{"enabled":true}'
NODE_FLOW_CIRCUIT_BREAKER='{"enabled":true,"failureRatio":0.5,"minimumRequests":10,"windowMs":30000,"openMs":5000,"maxOpenMs":60000}'

Shared by HTTP, HTTP_POLL, WEBHOOK and GRPC. See Execution controls → circuit breakers.

Browser access to the REST gateway

Empty means no CORS headers and therefore no cross-origin browser access — the safe default, because a gateway route runs a workflow and the wrong origin list is a way for someone else's page to do that with a visitor's credentials.

* is deliberately not special-cased: it cannot be combined with credentials anyway, and an install that means "anyone" should say so origin by origin, or put a proxy in front that owns the policy.

NODE_FLOW_GATEWAY_CORS_ORIGINS='https://app.example.com,https://admin.example.com'

Telemetry

Read directly rather than through the validated schema, because the SDK must start before anything else is imported.

Everything except the on/off switch uses the standard OTEL_* variables the SDK already reads, so there is no second vocabulary for things that already have names.

The dashboard image

The UI is a separate container and reads only these.

The nf CLI

Flags win over environment variables.

The benchmark harness (nf-bench) reads NODE_FLOW_API_KEY.

A production starting point

# ---- required ----
DATABASE_URL='postgres://nodeflow:…@db.internal:5432/nodeflow?sslmode=verify-full&sslrootcert=/certs/ca.pem'
NODE_FLOW_JWT_SECRET='…at least 32 characters…'

# ---- identity ----
NODE_FLOW_SECRET_KEYS='k1:…base64 of 32 random bytes…'
# Leave NODE_FLOW_SEED_PASSWORD unset. Set NODE_FLOW_SEED=false once the
# install has its accounts.

# ---- roles: one of these per deployment ----
NODE_FLOW_ROLES=api
# NODE_FLOW_ROLES=decider
# NODE_FLOW_ROLES=poller

# ---- storage ----
NODE_FLOW_BLOB_STORE=s3
NODE_FLOW_BLOB_S3='{"bucket":"nf-payloads","region":"eu-west-1"}'

# ---- safety ----
NODE_FLOW_HTTP_ALLOW_PRIVATE=false
NODE_FLOW_HTTP_ALLOWED_HOSTS='internal-api.svc.cluster.local'
NODE_FLOW_CIRCUIT_BREAKER='{"enabled":true}'
NODE_FLOW_GATEWAY_CORS_ORIGINS=''

# ---- capacity ----
DATABASE_MAX_CONNECTIONS=20
NODE_FLOW_SYSTEM_TASK_CONCURRENCY=20
NODE_FLOW_MAX_POLL_SECONDS=30
NODE_FLOW_DEFAULT_LEASE_SECONDS=60

# ---- migrations: run them as a job, not on every pod ----
DATABASE_MIGRATE_ON_BOOT=false

# ---- observability ----
NODE_FLOW_OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
OTEL_SERVICE_NAME=node-flow

Next

• Self-hosting — what to do with these.
• Execution controls — the per-workflow and per-task settings that are not environment variables.