Install Camunda with Helm for development
Use this guide to install Camunda 8 Self-Managed with the orchestration cluster, and optionally enable additional components.
By default, the Camunda Helm chart uses Bitnami open-source images. For production environments, Camunda recommends switching to vendor-supported enterprise images. This guide explains how to create registry secrets and install Camunda with enterprise images.
Prerequisites
- Kubernetes cluster: A functioning Kubernetes cluster with kubectl access and block-storage persistent volumes for stateful components. See Cloud providers for instructions to create a Kubernetes cluster.
- Helm: The Helm CLI installed. See Installing Helm.
Overview
There are two main ways to install Camunda Helm Charts, depending on your requirements.
Orchestration Cluster only
By default, the Helm chart deploys the Camunda orchestration cluster with basic authentication, intended only for testing and development. In production, Camunda 8 is typically deployed together with additional applications such as Optimize, Web Modeler, and Console, which require OIDC-based authentication (for example, using Keycloak). For details, see the Full Cluster section.
-
Create a namespace to install the platform on Kubernetes:
kubectl create namespace orchestration
Output:
namespace/orchestration created
-
Add the Helm repository:
To install the Camunda 8 Self-Managed Helm chart, add the Helm repository with the following command:
helm repo add camunda https://helm.camunda.io
helm repo update -
Install the Helm chart:
helm install camunda camunda/camunda-platform -n orchestration
-
Access the components:
Use the default credentials:
username: demo
password: demoSet up port-forwarding to access the services:
# Zeebe Gateway (for gRPC and REST API)
kubectl port-forward svc/camunda-zeebe-gateway 26500:26500 -n orchestration
kubectl port-forward svc/camunda-zeebe-gateway 8088:8080 -n orchestration
# Connectors
kubectl port-forward svc/camunda-connectors 8086:8080 -n orchestrationVerify the installation:
Test the Zeebe Gateway connection:
curl -u demo:demo http://localhost:8088/v2/topology
You should see a JSON response with the cluster topology information.
Available services:
- Operate: http://localhost:8088/operate - Monitor process instances
- Tasklist: http://localhost:8088/tasklist - Complete user tasks
- Identity: http://localhost:8088/identity - User and permission management
- Connectors: http://localhost:8086 - External system integrations
- Zeebe Gateway (gRPC): localhost:26500 - Process deployment and execution
- Zeebe Gateway (HTTP): http://localhost:8088 - Zeebe REST API
noteIn Camunda 8.8+, Operate, Tasklist, and Identity are integrated into the Orchestration component and share the same endpoint (port 8088).
Full Cluster
The following components run outside the orchestration cluster and are disabled by default in Helm Charts:
- Optimize
- Web Modeler
- Console
- Management Identity
- Keycloak
These components do not support basic authentication, so you must use any OIDC provider. In the following example, we use Keycloak as a locally running OIDC provider. The values file will deploy all Camunda 8 components.
Because the default configuration of the Helm chart uses basic authentication, you need to create a values.yaml file to modify the default configuration to:
- Enable Keycloak to provide another method of authentication via OIDC.
- Enable other Camunda components that run alongside the orchestration cluster.
Create a file called camunda-values.yaml
with the following content:
global:
secrets:
autoGenerated: true
name: "camunda-credentials"
identity:
auth:
enabled: true
publicIssuerUrl: "http://localhost:18080/auth/realms/camunda-platform"
webModeler:
redirectUrl: "http://localhost:8070"
console:
redirectUrl: "http://localhost:8087"
secret:
existingSecret: "camunda-credentials"
existingSecretKey: "identity-console-client-token"
optimize:
redirectUrl: "http://localhost:8083"
secret:
existingSecret: "camunda-credentials"
existingSecretKey: "identity-optimize-client-token"
orchestration:
redirectUrl: "http://localhost:8080"
secret:
existingSecret: "camunda-credentials"
existingSecretKey: "identity-orchestration-client-token"
connectors:
secret:
existingSecret: "camunda-credentials"
existingSecretKey: "identity-connectors-client-token"
security:
authentication:
method: oidc
identity:
enabled: true
firstUser:
secret:
existingSecret: "camunda-credentials"
existingSecretKey: "identity-firstuser-password"
identityKeycloak:
enabled: true
postgresql:
auth:
existingSecret: "camunda-credentials"
secretKeys:
adminPasswordKey: "identity-keycloak-postgresql-admin-password"
userPasswordKey: "identity-keycloak-postgresql-user-password"
auth:
existingSecret: "camunda-credentials"
passwordSecretKey: "identity-keycloak-admin-password"
optimize:
enabled: true
connectors:
enabled: true
security:
authentication:
method: oidc
oidc:
secret:
existingSecret: "camunda-credentials"
existingSecretKey: "identity-connectors-client-token"
webModeler:
enabled: true
restapi:
mail:
# This value is required, otherwise the restapi pod wouldn't start.
fromAddress: noreply@example.com
# WebModeler Database.
webModelerPostgresql:
enabled: true
auth:
existingSecret: "camunda-credentials"
secretKeys:
adminPasswordKey: "webmodeler-postgresql-admin-password"
userPasswordKey: "webmodeler-postgresql-user-password"
orchestration:
enabled: true
clusterSize: "1"
partitionCount: "1"
replicationFactor: "1"
security:
authentication:
method: oidc
oidc:
redirectUrl: "http://localhost:8080"
secret:
existingSecret: "camunda-credentials"
existingSecretKey: "identity-orchestration-client-token"
console:
enabled: true
Install and verify the deployment
Installing all components in a cluster requires downloading all related Docker images to the Kubernetes nodes. The time required depends on your cloud provider and network speed.
-
Create the namespace:
kubectl create namespace camunda
-
Install the Helm chart:
helm upgrade --install camunda camunda/camunda-platform \
--repo https://helm.camunda.io \
--version 13.0.0 \
--namespace camunda \
-f camunda-values.yaml -
Wait for all pods to be ready:
Monitor the pod status until all pods show
Running
andReady
:kubectl get pods -n camunda -w
Wait until you see output similar to:
NAME READY STATUS RESTARTS AGE
camunda-keycloak-0 1/1 Running 0 5m
camunda-identity-6c8b7f4d9-xyz123 1/1 Running 0 5m
camunda-zeebe-0 1/1 Running 0 5m
camunda-web-modeler-webapp-abc456-def789 1/1 Running 0 5m
...Press
Ctrl+C
to stop monitoring once all pods are ready.
Get started with Web Modeler
Follow this workflow to deploy your first process model and verify it works end-to-end:
1. Set up port-forwarding
Open separate terminal windows and run these commands to access the required services:
# Terminal 1: Keycloak (for authentication)
kubectl port-forward svc/camunda-keycloak 18080:80 -n camunda
# Terminal 2: Web Modeler (for modeling)
kubectl port-forward svc/camunda-web-modeler-webapp 8070:80 -n camunda
# Terminal 3: Zeebe Gateway (for deployment and process execution)
kubectl port-forward svc/camunda-zeebe-gateway 8080:8080 -n camunda
2. Get your credentials
Retrieve the password for the demo
user:
kubectl get secret camunda-credentials -n camunda -o jsonpath='{.data.identity-firstuser-password}' | base64 -d
3. Access Web Modeler
- Open your browser and navigate to http://localhost:8070
- Log in with:
- Username:
demo
- Password: (use the password retrieved in step 2)
- Username:
4. Create and deploy a process
- In Web Modeler, create a new BPMN diagram
- Design a simple process (or use the default process template)
- Click Deploy & Run to deploy your process to the Zeebe cluster
5. Verify in Operate
-
Set up port-forwarding for Operate in a new terminal:
kubectl port-forward svc/camunda-zeebe-gateway 8080:8080 -n camunda
-
Open http://localhost:8080/operate in your browser
-
Log in with the same
demo
credentials -
Verify that your deployed process instance appears in the dashboard and shows the expected flow
Access all components
For complete access to all Camunda components, set up port-forwarding for all services:
# Authentication
kubectl port-forward svc/camunda-keycloak 18080:80 -n camunda
kubectl port-forward svc/camunda-identity 18081:80 -n camunda
# Web interfaces
kubectl port-forward svc/camunda-optimize 8083:80 -n camunda
kubectl port-forward svc/camunda-web-modeler-webapp 8070:80 -n camunda
kubectl port-forward svc/camunda-console 8087:80 -n camunda
# Zeebe and Connectors
kubectl port-forward svc/camunda-zeebe-gateway 26500:26500 -n camunda
kubectl port-forward svc/camunda-zeebe-gateway 8080:8080 -n camunda
kubectl port-forward svc/camunda-connectors 8085:8080 -n camunda
Available URLs
Once port-forwarding is active, access the UIs in your browser:
Component | URL | Description |
---|---|---|
Zeebe Gateway (gRPC) | http://localhost:26500 | Process deployment and execution |
Zeebe Gateway (HTTP) | http://localhost:8080/ | Zeebe REST API |
Operate | http://localhost:8080/operate | Monitor process instances |
Tasklist | http://localhost:8080/tasklist | Complete user tasks |
Web Modeler | http://localhost:8070 | Design and deploy processes |
Console | http://localhost:8087 | Manage clusters and APIs |
Identity | http://localhost:8088/identity | User and permission management for the orchestration cluster |
Management Identity | http://localhost:18081 | User and permission management |
Keycloak | http://localhost:18080 | Authentication server |
Optimize | http://localhost:8083 | Process analytics |
Connectors | http://localhost:8085 | External system integrations |
Database access (for administration)
- PostgreSQL (Management Identity):
localhost:5432
- PostgreSQL (Web Modeler):
localhost:5433
- Elasticsearch:
localhost:9200
Troubleshoot installation issues
Verify that each pod is running and ready. If a pod is pending, it cannot be scheduled onto a node. This usually happens when the cluster does not have enough resources. To check messages from the scheduler, run:
kubectl describe pods <POD_NAME>
If describe
does not help, check the pod logs by running:
kubectl logs -f <POD_NAME>
Install a specific version
By default, the Camunda Helm chart installs the latest version of the Camunda 8 applications. Because Helm chart and application versions are released independently, their version numbers differ. For details, see the Camunda 8 Helm Chart Version Matrix.
To install the latest version of the chart and its application dependencies, run:
helm install camunda camunda/camunda-platform \
--values https://helm.camunda.io/camunda-platform/values/values-latest.yaml
To install a specific chart version, use the --version
flag with the chart version number. For example, the chart version for Camunda 8.8 is 13
:
helm install camunda camunda/camunda-platform --version 13 \
--values https://helm.camunda.io/camunda-platform/values/values-v8.8.yaml
Specifying only the major chart version (for example, 13
) installs the latest available 13.x.y
release. You can also specify a minor version (for example, 12.6
) to install the latest 12.6.y
release.
If you are unsure which chart version corresponds to your Camunda application version, run:
helm search repo -l camunda/camunda-platform
This command lists all available chart versions and their corresponding application versions.
Notes and requirements
- Zeebe supports Kubernetes startup and liveness probes. See Gateway health probes.
- Zeebe must be deployed as a StatefulSet to preserve cluster node identities. StatefulSets require persistent storage, which you must provision in advance. The type of storage depends on your cloud provider.
- Docker pull limits apply when downloading Camunda 8 images from Docker Hub. To avoid disruptions, authenticate with Docker Hub or use a mirror registry.
- Air-gapped environments require additional configuration. See Helm chart air-gapped environment installation.
- Image sources: By default, the Helm chart uses Bitnami open-source images for infrastructure dependencies (PostgreSQL, Elasticsearch, Keycloak). For production environments, Camunda recommends using Bitnami Premium images for enhanced security and vendor support. For detailed information about image types, CVE handling policies, and installation procedures, see Install Bitnami enterprise images.
Next steps
- Explore the Camunda Reference Architectures to learn how to run Camunda 8 in production.
Additional resources
- Helm chart Amazon OpenSearch service usage — configure Camunda to use Amazon OpenSearch Service instead of the default Elasticsearch.
- Getting started with document handling — configure document storage and management in Camunda 8.
- Production installation — configure and install the helm chart for production environments.
- Helm Configuration - customize your installation by modifying the Helm chart configuration.