Skip to main content
Version: 8.9 (unreleased)

Install Camunda with Helm for development

Use this guide to install Camunda 8 Self-Managed with the orchestration cluster, and optionally enable additional components.

note

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

Deploys only a small set of necessary components (Orchestration Cluster and connectors). Quicker and good enough for most development and testing.

Full Cluster

Deploys Orchestration Cluster, Connectors, Management Identity, Console, and Optimize.

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.

  1. Create a namespace to install the platform on Kubernetes:

    kubectl create namespace orchestration

    Output:

    namespace/orchestration created

  2. 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

  3. Install the Helm chart:

    helm install camunda camunda/camunda-platform -n orchestration

  4. Access the components:

    Use the default credentials:

    username: demo
    password: demo

    Set 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 orchestration

    Verify 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:

    note

    In 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

elasticsearch:
  master:
    replicaCount: 1
    persistence:
      size: 10Gi

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.

  1. Create the namespace:

    kubectl create namespace camunda

  2. Install the Helm chart:

    helm install camunda camunda-platform \
      --version 13.0.0 \
      --namespace camunda \
      -f camunda-values.yaml

  3. Wait for all pods to be ready:

    Monitor the pod status until all pods show Running and Ready:

    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​

  1. Open your browser and navigate to http://localhost:8070
  2. Log in with:
    • Username: demo
    • Password: (use the password retrieved in step 2)

4. Create and deploy a process​

  1. In Web Modeler, create a new BPMN diagram
  2. Design a simple process (or use the default process template)
  3. Click Deploy & Run to deploy your process to the Zeebe cluster

5. Verify in Operate​

  1. Set up port-forwarding for Operate in a new terminal:

    kubectl port-forward svc/camunda-zeebe-gateway 8080:8080 -n camunda

  2. Open http://localhost:8080/operate in your browser

  3. Log in with the same demo credentials

  4. 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:

ComponentURLDescription
Zeebe Gateway (gRPC)http://localhost:26500Process deployment and execution
Zeebe Gateway (HTTP)http://localhost:8080/Zeebe REST API
Operatehttp://localhost:8080/operateMonitor process instances
Tasklisthttp://localhost:8080/tasklistComplete user tasks
Web Modelerhttp://localhost:8070Design and deploy processes
Consolehttp://localhost:8087Manage clusters and APIs
Identityhttp://localhost:8088/identityUser and permission management for the orchestration cluster
Management Identityhttp://localhost:18081User and permission management
Keycloakhttp://localhost:18080Authentication server
Optimizehttp://localhost:8083Process analytics
Connectorshttp://localhost:8085External system integrations

Database access (for administration)​

  • PostgreSQL (Management Identity): localhost:5432
  • PostgreSQL (Web Modeler): localhost:5433
  • Elasticsearch: localhost:9200
tip

For a richer localhost experience (and to avoid managing many individual port-forward commands), you can use kubefwd to forward all Services in the target namespace and make them resolvable by their in-cluster DNS names on your workstation.

Example (requires sudo to bind privileged ports and modify /etc/hosts):

sudo kubefwd services -n "$CAMUNDA_NAMESPACE"

After this runs, you can reach services directly, for example:

  • Identity: http://$CAMUNDA_RELEASE_NAME-identity/managementidentity
  • Keycloak: http://$CAMUNDA_RELEASE_NAME-keycloak
  • Zeebe Gateway gRPC: $CAMUNDA_RELEASE_NAME-zeebe-gateway:26500

You can still use localhost ports if you prefer traditional port-forwarding. Stop kubefwd with Ctrl+C when finished. Be aware kubefwd modifies your /etc/hosts temporarily; it restores the file when it exits.

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.
  • Infrastructure deployment alternatives: For production deployments, consider using vendor-supported infrastructure deployment methods with official operators for PostgreSQL, Elasticsearch, and Keycloak.

Next steps​

Additional resources​