Skip to content

Deployment Modes

EventConductor supports three deployment modes controlled by two independent properties. No code changes are required to switch between them.

Chapter 13 of EventConductor in N minutes (2:38) · English, with English and Spanish subtitles

PropertyValuesDefault
workflow.modekafka | embeddedembedded
workflow.persistencejpa | memorymemory

Mode 1 — Fully embedded (embedded + memory)

Section titled “Mode 1 — Fully embedded (embedded + memory)”

Default mode. No Kafka, no database. Everything runs in-process. Ideal for unit tests, local development, and embedding in other applications.

Two working examples are available:

  • testbench/workflow-embedded — embedded mode with an HTTP server and MCP endpoint
  • testbench/workflow-embedded-headless — embedded mode with no HTTP server (pure background process)
workflow.mode=embedded
workflow.persistence=memory

Kafka and JPA autoconfiguration classes are excluded automatically by workflow-engine when workflow.mode=embedded. No manual spring.autoconfigure.exclude configuration is needed.

Use @WorkflowEmbeddedApplication instead of @SpringBootApplication. It automatically excludes the UI adapter layer (which requires a web context and JPA) from component scanning:

@WorkflowEmbeddedApplication
public class MyApplication {
public static void main(String[] args) {
SpringApplication.run(MyApplication.class, args);
}
}

Who can reach it. An embedded application without Spring Security refuses anonymous requests to the engine’s REST API (401, since 2.27.0) and to the admin UI, the MCP endpoints, GET /rules and the task-project zips (403, since 2.28.0). Protect the application with Spring Security, set workflow.message-api.allow-anonymous=true for an isolated or development deployment, or leave the admin UI out with workflow.ui.enabled=false — see HTTP security.

Characteristics:

  • Domain events dispatched synchronously on each repository save()
  • State held in ConcurrentHashMap — lost on restart (with jpa, processes carry on where they were: see Restarting the engine)
  • Workflow definitions loaded from classpath:/workflows/ at startup (*.ec.yaml recommended; also .ec, *.workflow.yaml, .json, .yaml, .yml)
  • No external dependencies

No Kafka required. Requires a supported database. Good for single-node deployments, development with a real database, or demos with an in-memory H2 DB.

A working example is available:

  • testbench/workflow-embedded-db-headless — embedded + JPA + H2, no HTTP server (pure background process)
workflow.mode=embedded
workflow.persistence=jpa
spring.datasource.url=jdbc:postgresql://localhost:5432/workflow
spring.datasource.username=workflow
spring.datasource.password=secret
spring.jpa.hibernate.ddl-auto=validate

Add Flyway to the classpath and the engine applies its own schema at startup:

<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-core</artifactId>
</dependency>
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-database-postgresql</artifactId>
</dependency>

Kafka autoconfiguration classes are excluded automatically by workflow-engine when workflow.mode=embedded.

Use @WorkflowEmbeddedApplication (which handles component scanning) plus @EnableJpaRepositories and @AutoConfigurationPackage pointing at the engine’s persistence package, so Spring Data JPA and Hibernate find the repositories and entities regardless of where your main class lives:

@WorkflowEmbeddedApplication
@EnableJpaRepositories(basePackages = "io.mateu.workflow.infra.out.persistence")
@AutoConfigurationPackage(basePackages = "io.mateu.workflow.infra.out.persistence")
public class MyApplication {
public static void main(String[] args) {
SpringApplication.run(MyApplication.class, args);
}
}

To show the engine’s UI in this application — your own @UI mounts WorkflowMenu (or FormsMenu, RulesMenu) — add @EnableWorkflowUi beside @WorkflowEmbeddedApplication; workflow.ui.enabled=false still removes it, and the console access rule still applies (see Mounting the admin UI). Scan your own extra packages through an imported class, not a @ComponentScan on the application class: declared there, it replaces the embedded annotation’s scans instead of adding to them.

@WorkflowEmbeddedApplication
@EnableWorkflowUi
@EnableJpaRepositories(basePackages = "io.mateu.workflow.infra.out.persistence")
@AutoConfigurationPackage(basePackages = "io.mateu.workflow.infra.out.persistence")
public class MyApplication { … }

Characteristics:

  • Events dispatched in-process via EmbeddedOutboxRelay. It is woken by the pod’s own writes; the poll interval is a fallback, not the latency of a step
  • All state persisted via JPA/Hibernate — survives restarts
  • Workflow definitions placed in classpath:/workflows/ are automatically imported into the database at startup by ClasspathWorkflowDefinitionImporter (idempotent — skips definitions already present)

Requires a running Kafka broker and a supported database (PostgreSQL, MariaDB/MySQL, or Oracle). Designed for production multi-pod deployments.

workflow.mode=kafka
workflow.persistence=jpa
spring.datasource.url=jdbc:postgresql://localhost:5432/workflow
spring.datasource.username=workflow
spring.datasource.password=secret
spring.jpa.hibernate.ddl-auto=validate
spring.kafka.bootstrap-servers=localhost:9092

Characteristics:

  • Domain events flow through Kafka topics (outbox, upstream, downstream)
  • State persisted in the configured database
  • One pod owns each process. Every event carries its process as the Kafka message key, so all of a process’s events land on one partition and a consumer group gives that partition to exactly one consumer. Nothing coordinates; an optimistic version on the process fences the brief window of a rebalance
  • Horizontally scalable — add more orchestrator pods at any time

Supported databases (workflow.persistence=jpa)

Section titled “Supported databases (workflow.persistence=jpa)”

Two things need coordinating across pods, and they are not the same thing.

Per-process exclusion. In kafka mode nothing does it: the partition already guarantees a single writer, and an optimistic version on the process and its steps rejects the stale write a rebalance can produce. In embedded mode there are no partitions, so a row lock on the process (SELECT … FOR UPDATE, held by the transaction the work already runs in) keeps two pods apart. Neither needs configuration.

Singleton background jobs — the timeout scan, cron-scheduled starts and the embedded relay — still take a database advisory lock so only one pod runs each. That is what the table below selects, automatically, from the JDBC driver in use.

DatabaseLock mechanismNotes
PostgreSQLpg_try_advisory_lock / pg_advisory_unlockNo prerequisites
MariaDB / MySQLGET_LOCK / RELEASE_LOCKNo prerequisites
OracleDBMS_LOCK.REQUEST / DBMS_LOCK.RELEASERequires GRANT EXECUTE ON DBMS_LOCK TO <user> — see below
H2In-process AtomicBoolean per lock IDFor testing and demos only — single JVM, not distributed

These locks are held only for the length of one scan, and a crashed pod’s locks are released by the database when its connection closes.

Earlier versions also took an advisory lock per process, which required a watchdog to force-release locks held too long — and a watchdog that yanks exclusivity from an operation still running is a hazard of its own. Neither exists now: exclusion is either the partition or the transaction, and both end on their own.

The singleton job locks above are implemented on Oracle via the DBMS_LOCK package, which is not granted by default. A DBA must run the following once per schema user before starting the application:

GRANT EXECUTE ON DBMS_LOCK TO <your_schema_user>;

Without this grant the application will fail to acquire locks on startup. The JDBC URL for Oracle follows the standard format:

spring.datasource.url=jdbc:oracle:thin:@localhost:1521:XE
spring.datasource.username=workflow
spring.datasource.password=secret
spring.jpa.database-platform=org.hibernate.dialect.OracleDialect

Pre-built images are published to Docker Hub on every release and are ready to use — no build step required:

ImageDocker Hub
orchestrator-standalone-appmiguelperezcolom/orchestrator-standalone-app
forms-standalone-appmiguelperezcolom/forms-standalone-app
worker-standalone-appmiguelperezcolom/worker-standalone-app

All images are fully configured via environment variables. See the environment variable reference for the complete list.

A ready-to-use docker-compose.yml is included in the apps/ directory. It starts the full stack — Redpanda, PostgreSQL, orchestrator, forms, and worker — with healthcheck-gated startup ordering:

Terminal window
cd apps
docker compose up -d
ServicePortDescription
postgres-db5432PostgreSQL (workflow database)
redpanda9092Kafka-compatible broker (external)
redpanda-console8888Redpanda web console
orchestrator8105orchestrator-standalone-app
forms8106forms-standalone-app
worker8107worker-standalone-app — the test worker; UI at /_worker

The UIs log in as admin with the password in SECURITY_PASSWORD — changeme unless you set it, a local-only default. (Without a password the apps generate one and, since 2.28.0, do not show it: nobody could log in.)

To override values (e.g. a different image tag):

Terminal window
SECURITY_PASSWORD=mypwd DB_PASSWORD=mypwd docker compose up -d
# or
docker compose up -d --env-file .env.prod

The chart in charts/eventconductor/ deploys the whole stack — Redpanda, PostgreSQL, the orchestrator, the forms engine and the rule engine — with PersistentVolumeClaims, Secrets and readiness-gated initContainers. The workers and the webhook gateway are optional components of the same chart, off by default (see Optional components).

Install:

Terminal window
helm install ec charts/eventconductor --set postgres.password=mypwd

The password has no default and the chart refuses to render without one, deliberately: the alternative is a known password on a database reachable from every pod in the namespace. To hold it outside your shell history, put it in a Secret with the keys POSTGRES_DB, POSTGRES_USER and POSTGRES_PASSWORD and name it instead:

Terminal window
helm install ec charts/eventconductor --set postgres.existingSecret=ec-postgres

Admin password. The three apps run with HTTP Basic on, as user admin. Unless you name a Secret (key SECURITY_PASSWORD) in orchestrator.security.passwordSecret / forms.security.passwordSecret / rules.security.passwordSecret, the chart generates one Secret, <release>-eventconductor-admin, with a random password shared by the apps that have none, and reuses it on every upgrade. Read it with:

Terminal window
kubectl get secret ec-eventconductor-admin -o jsonpath='{.data.SECURITY_PASSWORD}' | base64 -d

Where the chart is rendered without access to the cluster (helm template, some GitOps tools), the generated password would change on every render: name your own Secret there. The apps never print a password.

The rules engine’s gRPC API (rules.grpcEnabled, port rules.grpcPort) is off by default since 2.28.0: it is plaintext and unauthenticated — anyone who reaches the port can list and read every rule. Off, the port is neither opened in the pod nor exposed on the Service. Turn it on only for runtimes that read rules over gRPC (rules.source=grpc), behind mTLS from a service mesh (Istio, Linkerd) and with networkPolicy.enabled=true limiting who reaches it; runtimes can read the same rules over the REST API (rules.source=rest), which is behind the app’s authentication.

Key values (charts/eventconductor/values.yaml):

ValueDefaultDescription
postgres.password—PostgreSQL password. Required unless postgres.existingSecret is set
postgres.existingSecret""Secret holding POSTGRES_DB / POSTGRES_USER / POSTGRES_PASSWORD
postgres.maxConnections200Server connection limit. The three apps ask for 96 of them before anything else connects
postgres.storage8GiPVC size for PostgreSQL
redpanda.defaultTopicPartitions6Partitions, which cap how many orchestrator pods can share the load
redpanda.storage8GiPVC size for Redpanda
redpanda.externalNodePort30092NodePort for external Kafka access (0 = disabled)
orchestrator.replicas2Orchestrator pod count
orchestrator.dbPoolSize16Connections per pod. Must cover both consumer bindings, the relay, the scanner and the UI
orchestrator.consumerConcurrency3Consumer threads per pod, per binding
orchestrator.extraEnv{}Extra environment, injected verbatim (tracing endpoints, git import, HTTP/LLM connections, event destinations, …)
orchestrator.builtinWorkers.httpAllowedHosts""Hosts the orchestrator’s built-in HTTP_CALL worker may reach (WORKFLOW_HTTP_ALLOWED_HOSTS); empty = any host the SSRF guard lets through. Set it in production
orchestrator.builtinWorkers.existingSecret""Secret loaded into the orchestrator’s environment (envFrom): WORKFLOW_HTTP_SECRETS_<NAME> for ${secret:NAME}, WORKFLOW_LLM_CONNECTIONS_<NAME>_APIKEY
orchestrator.builtinWorkers.startOffsetearliestWhere the built-in workers’ group starts on a new topic (BUILTIN_WORKERS_START_OFFSET); latest for the rollout that moves a topic from a standalone worker onto the orchestrator
forms.replicas / rules.replicas2Pod counts
*.image / *.imageTagsee valuesImage; the tag defaults to the chart’s appVersion
*.flywayTableper appMigration history table for that app’s engine. The three apps share one database and must not share one history table
ingress.enabledfalseIngress for the three UIs
*.security.passwordSecret""Secret with the app’s admin SECURITY_PASSWORD; blank uses the generated <release>-eventconductor-admin
rules.grpcEnabledfalseThe rule catalog’s plaintext gRPC read API (see above)
networkPolicy.enabledfalseNetworkPolicies limiting ingress to the apps to pods of the release (or networkPolicy.ingressFromPodSelector)

Optional components: workers and webhook gateway

Section titled “Optional components: workers and webhook gateway”

The orchestrator serves HTTP_CALL, LLM_CALL and PUBLISH_EVENT itself — its built-in workers consume http-calls, llm-calls and event-publications (group orchestrator-builtin-workers) and are configured through orchestrator.builtinWorkers and orchestrator.extraEnv — so those steps need no worker deployment.

Since chart 0.2.0 four more applications can be switched on. Each runs as non-root with a read-only root filesystem and all capabilities dropped, is probed on /actuator/health/liveness and /readiness, waits for Redpanda before starting, and gets a NetworkPolicy when networkPolicy.enabled is set.

ComponentValues keyReadsServiceSecrets it may need
Test worker (worker-standalone-app)workerdownstreamworker:8108 (its UI)none (DB credentials come from the chart’s PostgreSQL Secret)
HTTP worker (http-worker-standalone-app), optionalhttpWorkerhttp-calls—WORKFLOW_HTTP_SECRETS_<NAME> for ${secret:NAME}
LLM worker (llm-worker-standalone-app), optionalllmWorkerllm-calls—ANTHROPIC_API_KEY, LOCAL_LLM_API_KEY, WORKFLOW_LLM_CONNECTIONS_<NAME>_APIKEY
Webhook gateway (webhook-gateway-standalone-app)webhookGateway— (receives POST /webhooks/<name>)webhook-gateway:8109WORKFLOW_WEBHOOKS_ENDPOINTS_<NAME>_SECRET; ENGINE_API_KEY with transport: rest

The chart never takes a credential as a value. Put them in a Secret of your own and name it in <component>.existingSecret: every key becomes an environment variable of the pod. Everything that is not secret goes in <component>.extraEnv, with Spring’s relaxed binding:

Terminal window
kubectl create secret generic ec-webhooks \
--from-literal=WORKFLOW_WEBHOOKS_ENDPOINTS_GITHUB_SECRET=<the secret given to GitHub>
helm upgrade ec charts/eventconductor --reuse-values \
--set webhookGateway.enabled=true \
--set webhookGateway.existingSecret=ec-webhooks \
--set webhookGateway.extraEnv.WORKFLOW_WEBHOOKS_ENDPOINTS_GITHUB_PROVIDER=github \
--set webhookGateway.extraEnv.WORKFLOW_WEBHOOKS_ENDPOINTS_GITHUB_DESTINATION=github \
--set webhookGateway.extraEnv.WORKFLOW_EVENTS_DESTINATIONS_GITHUB_TOPIC=github-events
  • Test worker. A simulator for tests and demos, not a production worker. worker.persistence is jpa (its two tables in the chart’s PostgreSQL, created by itself; add worker.dbPoolSize to your postgres.maxConnections budget) or memory (no database, nothing survives a restart).
  • HTTP and LLM workers. Optional: deploy one to keep that egress and its secrets or API keys out of the orchestrator’s pods. With httpWorker.enabled / llmWorker.enabled the chart takes that topic out of the orchestrator’s BUILTIN_WORKER_TOPICS and switches its own off (WORKFLOW_HTTP_ENABLED=false / WORKFLOW_LLM_ENABLED=false), so a task never runs in both. When you later retire a standalone worker and hand its topic back to the orchestrator, set orchestrator.builtinWorkers.startOffset=latest for that upgrade, or the orchestrator runs the tasks still retained on the topic again.
  • HTTP worker. Set httpWorker.allowedHosts in production (orchestrator.builtinWorkers.httpAllowedHosts when the orchestrator serves HTTP_CALL). Only names listed under workflow.http.secrets resolve (see HTTP calls): a key WORKFLOW_HTTP_SECRETS_PARTNER_TOKEN in the Secret is what ${secret:PARTNER_TOKEN} reaches.
  • Webhook gateway. transport: kafka (the default) publishes on the destination’s topic, which the orchestrator consumes. transport: rest hands events to an engine’s POST /workflow/api/events/{destination} with X-Api-Key, which suits an embedded engine with workflow.message-api.api-key, not this chart’s orchestrator (HTTP Basic); the chart refuses to render it without webhookGateway.engineUrl and an existingSecret holding ENGINE_API_KEY. With ingress.enabled, /webhooks on ingress.host routes to the gateway (webhookGateway.exposeOnIngress, webhookGateway.ingressPath). With networkPolicy.enabled, name your ingress controller in webhookGateway.networkPolicyFrom (NetworkPolicy from peers), or senders from outside the namespace are blocked.

Upgrade / uninstall:

Terminal window
helm upgrade ec charts/eventconductor --reuse-values --set orchestrator.replicas=3
helm uninstall ec

charts/eventconductor-demo/ deploys the seven services of the demo — shell, gateway, users, content, control plane, booking and the AI agent — as ordinary applications that participate in workflows. It brings no infrastructure of its own: it talks to the PostgreSQL, Redpanda and orchestrator of an EventConductor release, so install that one first and point this one at it.

Terminal window
helm install demo charts/eventconductor-demo \
--set engine.postgresSecret=ec-postgres

The AI agent is the one service that needs something from you — a Claude key, without which it cannot start at all. Create the Secret and name it:

Terminal window
kubectl create secret generic ec-demo-anthropic --from-literal=ANTHROPIC_API_KEY=sk-...
helm upgrade demo charts/eventconductor-demo \
--reuse-values --set services.ia-agent-service.anthropicSecret=ec-demo-anthropic

Both charts install into whatever namespace you give them; the demo resolves the engine by service name, so they have to share one.

ScenarioRecommended mode
Unit / integration testsworkflow-embedded + memory
Local development (no infra)workflow-embedded + memory
Local development (H2, no infra)workflow-embedded + jpa (H2)
Local development (with real DB)workflow-embedded + jpa
Single-node productionworkflow-embedded + jpa
Multi-node / Kuberneteskafka + jpa

Both embedded variants support running without an HTTP server. Simply use spring-boot-starter instead of spring-boot-starter-web as your application’s base dependency and omit spring-ai-starter-mcp-server-webmvc. Spring Boot will detect no servlet container on the classpath and start as a non-web application — the workflow engine runs fully in-process with no open port.

Working headless examples:

  • testbench/workflow-embedded-headless — embedded + memory, no HTTP server
  • testbench/workflow-embedded-db-headless — embedded + jpa (H2), no HTTP server; state survives restarts