Developer quickstart – Camunda 8 Run

note

Camunda 8 Run is not supported for production use.

Camunda 8 Run allows you to install and start a simplified, single-application Camunda configuration in a local development environment. This page guides you through using Camunda 8 Run on a local or virtual machine.

Camunda 8 Run includes the following:

• Orchestration Cluster
• Connectors
• Elasticsearch

Camunda 8 Run also supports document storage and management with document handling.

Prerequisites

• OpenJDK 21–23: Required for running Camunda 8 as a Java application.
• Docker 20.10.21+: Required for running Camunda 8 via Docker Compose.
• Desktop Modeler
• If using Ubuntu: Ubuntu 22.04 or newer

note

After installing OpenJDK, ensure JAVA_HOME is set by running java -version in a new terminal.

If no version of Java is found, follow your chosen installation's instructions for setting JAVA_HOME before continuing.

Install and start Camunda 8 Run

1. Download the latest release of Camunda 8 Run for your operating system and architecture. Opening the .tgz file extracts the Camunda 8 Run script into a new directory.
2. Navigate to the new c8run directory.
3. Start Camunda 8 Run by running one of the following in your terminal:

• On Mac and Linux:
  • Run the helper script: ./start.sh
  • Or use the command: ./c8run start
• On Windows:
  • Use the command: .\c8run.exe start

If startup is successful, a browser window for Operate will open automatically. Alternatively, you can access Operate at http://localhost:8080/operate.

To start Camunda 8 Run using Docker:

• On Mac and Linux: ./start.sh --docker
• On Windows: .\c8run.exe start --docker

When started with Docker, Operate will be available at http://localhost:8088/operate.

note

If Camunda 8 Run fails to start, run the shutdown script to end the current processes, then run the start script again.

Configuration options

The following options provide a convenient way to override settings for quick tests and interactions in Camunda 8 Run.
For more advanced or permanent configuration, modify the default configuration/application.yaml or supply a custom file using the --config flag (e.g., to enable authentication and authorization).

Argument	Description
--config <path>	Applies the specified Zeebe application.yaml.
--username <arg>	Configures the first user’s username as <arg>.
--password <arg>	Configures the first user’s password as <arg>.
--keystore <arg>	Configures the TLS certificate for HTTPS. If not specified, HTTP is used. For more information, see enabling TLS.
--keystorePassword <arg>	Provides the password for the JKS keystore file.
--port <arg>	Sets the Camunda core port (default: 8080).
--log-level <arg>	Sets the log level for the Camunda core.
--docker	Downloads and runs the Camunda Docker Compose distribution. Additional options are not supported and will be ignored. See the shutdown script for information on stopping the Docker application.
--disable-elasticsearch	Prevents the built-in Elasticsearch from starting. Ensure another Elasticsearch instance is provided via --config. See the external Elasticsearch section for details.
--startup-url	The URL to open after startup (e.g., 'http://localhost:8080/operate'). By default, Operate is opened.

Work with Camunda 8 Run

Access Camunda components

You can log in to all web interfaces using with the default credentials:

• Username: demo
• Password: demo

These web interfaces are available at:

• Operate: http://localhost:8080/operate
• Tasklist: http://localhost:8080/tasklist
• Identity: http://localhost:8080/identity

The following components do not have a web interface, but their endpoints are useful for additional configuration:

• Orchestration Cluster REST API: http://localhost:8080/v2/
• Inbound Connectors API: http://localhost:8086/
• Zeebe API (gRPC): http://localhost:26500/
• Metrics (Prometheus): http://localhost:9600/actuator/prometheus
• Swagger UI (API Explorer): http://localhost:8080/swagger-ui/index.html

note

• The URLs for the Docker Compose application can be found in the Docker Compose documentation.
• The Connectors URL displays a login page, but it cannot be logged into.

Deploy diagrams from Desktop Modeler

Make sure you have installed Desktop Modeler before continuing.

To deploy diagrams from Desktop Modeler, use the following configuration:

• Target: Self-Managed
• Cluster endpoint: http://localhost:26500 (Zeebe Gateway)
• Authentication: None

A success notification will display when complete. Start a new process instance to view your running process in Operate.

Use built-in and custom connectors

Desktop Modeler automatically fetches templates for pre-built connectors. Custom connectors can also be added to your Camunda 8 Run distribution.

To add a custom connector:

1. Place the connector’s .jar file in the /custom_connectors folder within the /c8run directory.
2. Place the element template in the appropriate folder for your installation. See Search Paths for more information.

Once configured, your connectors are available for use in Modeler.

Configure Connector secrets

Connector Secrets can be provided as environment variables by adding them to the .env file in the root folder.

When starting C8Run with the --docker option, add the connector secrests to the connector-secrets.txt file in the docker-compose folder.

Use Camunda APIs

All APIs are unprotected by default in Camunda 8 Run and can be accessed without credentials or tokens.

Available APIs include:

• Orchestration Cluster REST API
• Zeebe gRPC

Enable authentication and authorization

By default, Camunda 8 Run starts with authentication enabled and API endpoints unprotected.
To enforce authorization rules, provide a custom configuration file.

You can either:

• Update the existing configuration/application.yaml, or
• Create a new application.yaml in the /c8run folder and pass it at startup using the --config flag:

camunda:
  security:
    authentication:
      # Require authentication for API requests
      unprotected-api: false
    authorizations:
      # Enable authorization checks
      enabled: true

Start C8Run with the configuration:

./start.sh --config application.yaml

Once enabled, API requests must include valid credentials. For example:

curl --request GET 'http://localhost:8080/v2/topology'  \
  -u demo:demo \
  --header 'Content-Type: application/json' \
  --data-raw '{}'

To add additional users (e.g., an admin user), extend the configuration:

camunda:
  security:
    initialization:
      users:
        - username: user
          password: user
          name: user
          email: user@example.com
      defaultRoles:
        admin:
          users:
            - user

Shut down Camunda 8 Run

To shut down Camunda 8 Run and end all running processes, run ./shutdown.sh (or .\c8run.exe stop on Windows) from the c8run directory.

To shut down the Camunda 8 Run Docker distribution, use ./shutdown.sh --docker (or .\c8run.exe stop --docker on Windows).

Advanced options

Enable TLS

TLS can be enabled by providing a local keystore file using the --keystore argument at startup. Camunda 8 Run accepts .jks certificate files.

Access metrics

Metrics are enabled in Camunda 8 Run by default and can be accessed at http://localhost:9600/actuator/prometheus. For more information, see the metrics documentation.

Start external Elasticsearch

To start Elasticsearch outside of Camunda 8 Run, use the --disable-elasticsearch flag at startup. This prevents Camunda 8 Run from starting its own Elasticsearch instance.

The following command starts an external Elasticsearch instance using docker run:

docker run \
    -m 1GB \
    -d \
    --name elasticsearch \
    -p 9200:9200 \
    -p 9300:9300 \
    -e "discovery.type=single-node" \
    -e "xpack.security.enabled=false" \
    elasticsearch:8.15.2

Environment variables

The following advanced configuration options can be provided via environment variables:

Variable	Description
ES_JAVA_OPTS	Allows you to override Java command line parameters for Elasticsearch. This can allow you to increase memory limits. Default: -Xms1g -Xmx1g
JAVA_OPTS	Allows you to override Java command line parameters for Camunda.

Next steps

Check out the getting started guide to start a new Java Project to connect to this local cluster.

Troubleshooting

User creation

User creation in Identity only happens on the first startup. This means:

• If you want to add a user using the --username and --password options, or
• If you want to seed users at startup via configuration in application.yaml,

then you must ensure that Elasticsearch starts fresh. Otherwise, Identity will reuse the existing indices and skip creating new users.

Tip: If you are testing locally, delete the existing Elasticsearch indices before restarting C8Run:

# Example: delete indices to reset Identity state
curl -XDELETE 'http://localhost:9200/identity*'

After clearing the indices, restart C8Run with your configuration or command-line options, and the users will be created as expected.