We've had some customers who would like to offer some "citizen dev tools" to their business users :
- build Forms using drag'n drop tools like form-js but with more components.
- build/adapt mail templates
The goal of this project is to show how to build such a solution with React, an extended form-js, Spring-Boot, spring-zeebe, tasklist-client and operate-client
This repository contains a Java application template for Camunda Platform 8 using Spring Boot and a docker-compose.yaml file for local development. For production setups we recommend to use our helm charts.
- Documentation
- Camunda Platform SaaS
- Getting Started Guide
- Releases
- Helm Charts
- Zeebe Workflow Engine
- Contact
The Spring Boot Java application includes an example Tasklist React front-end. Run mvnw package
from the project root, start the Spring Boot app, and then browse to http://localhost:8080.
This front-end relies on a customized version of @bpmnio/form-js.
If needed, you can also run the React front-end independent of the spring boot app. To do so, run npm run start
to start a nodejs server serving the react app over port 3000.
Fork this repository on GitHub and rename/refactor the following artifacts:
groupId
,artifactId
,name
, anddescription
in pom.xmlprocess/@id
andprocess/@name
in src/main/resources/models/camunda-process.bpmnProcessConstansts#BPMN_PROCESS_ID
in src/main/java/org/example/camunda/process/solution/ProcessConstants.java- Java package name, e.g.
org.example.camunda.process.solution.*
By forking this project, you can stay connected to improvements that we do to this template and simply pull updates into your fork, e.g. by using GitHub's Web UI or the following commands:
git remote add upstream git@github.com:camunda-community-hub/camunda-8-lowcode-ui-template.git
git pull upstream main
git push
The application requires a running Zeebe engine. You can run Zeebe locally using the instructions below for Docker Compose or have a look at our recommended deployment options for Camunda Platform.
Run the application via
./mvnw spring-boot:run
UI http://localhost:8080/ Swagger UI: http://localhost:8080/swagger-ui.html
The first time you use the project, you should be able to connect with demo/demo to create new forms, mail templates and manage your user organization.
When you start the application for the first time, an "ACME" organization is created for you with a single user demo/demo with admin rights. When you access the landing page, you'll be able to access the "admin" section where you can manage forms, mail templates and your organization.
You can create forms with 3 different approaches :
- Embedded forms into your process definition (classic approach)
- Create Extended Forms from the admin application. Form name should match the formKey. Forms will be stored in the workspace/forms folder.
- Create custom react forms. From the react application, in the forms folder, create your custom forms. You should then reference them in the customForms map in the forms/index.ts file.
Translations will be managed from the backend in the 2 first approaches. Input labels should be references in the Forms translations. In the 3rd case, translation will be managed from the front-end and translations should be added in the "siteTranslations".
If you want to secure your app with keycloak, you can set the keycloak.enabled to true and uncomment the properties in the application.yaml file
keycloak:
enabled: true
auth-server-url: http://localhost:18080/auth
realm: camunda-platform
resource: CustomTasklist
public-client: true
principal-attribute: preferred_username
This application relies on 3 kind of users :
- Admin : has a role Admin
- Editor : has a role Editor
- User : is connected without Admin or Editor roles.
ℹ️ To use the application with Keycloak, create the Admin role and assign it to (at least) one user.
ℹ️ The application also relies on groups. So you should add a custom mapper into your keycloak client with :
- Type : Group Membership
- Token Claim Name : groups
If you want to send emails through Gmail (what is coded for now), you will need to download a [client_secret_google_api.json from your Google console] (https://console.cloud.google.com/) and put it in your resources folder.
ℹ️ The docker-compose file in this repository uses the latest compose specification, which was introduced with docker-compose version 1.27.0+. Please make sure to use an up-to-date docker-compose version.
ℹ️ The Docker required is 20.10.16+
To stand-up a complete Camunda Platform 8 Self-Managed environment locally the docker-compose.yaml file in this repository can be used.
The full enviornment contains these components:
- Zeebe
- Operate
- Tasklist
- Connectors
- Optimize
- Identity
- Elasticsearch
- Keycloak
Clone this repo and issue the following command to start your environment:
docker-compose up -d
Wait a few minutes for the environment to start up and settle down. Monitor the logs, especially the Keycloak container log, to ensure the components have started.
Now you can navigate to the different web apps and log in with the user demo
and password demo
:
- Operate: http://localhost:8081
- Tasklist: http://localhost:8082
- Optimize: http://localhost:8083
- Identity: http://localhost:8084
- Elasticsearch: http://localhost:9200
Keycloak is used to manage users. Here you can log in with the user admin
and password admin
- Keycloak: http://localhost:18080/auth/
The workflow engine Zeebe is available using gRPC at localhost:26500
.
To tear down the whole environment run the following command
docker-compose down -v
If Optimize, Identity, and Keycloak are not needed you can use the docker-compose-core.yaml instead which does not include these components:
docker-compose -f docker-compose-core.yaml up -d
Zeebe, Operate, Tasklist, along with Optimize require a separate network from Identity as you'll see in the docker-compose file.
In addition to the local environment setup with docker-compose, you can download the Camunda Desktop Modeler to locally model BPMN diagrams for execution and directly deploy them to your local environment.
Feedback and updates are welcome!
Both docker-compose files contain our out-of-the-box Connectors.
Refer to the Connector installation guide for details on how to provide the related Connector templates for modeling.
To inject secrets into the Connector runtime they can be added to the
connector-secrets.txt
file inside the repository in the format NAME=VALUE
per line. The secrets will then be available in the Connector runtime with the
format secrets.NAME
.
To add custom Connectors either create a new docker image bundling them as described here.
Alternatively, you can mount new Connector JARs as volumes into the /opt/app
folder by adding this to the docker-compose file. Keep in mind that the Connector JARs need to bring along all necessary dependencies inside the JAR.
A kibana
profile is available in the provided docker compose files to support inspection and exploration of the Camunda Platform 8 data in Elasticsearch.
It can be enabled by adding --profile kibana
to your docker compose command.
In addition to the other components, this profile spins up Kibana.
Kibana can be used to explore the records exported by Zeebe into Elasticsearch, or to discover the data in Elasticsearch used by the other components (e.g. Operate).
You can navigate to the Kibana web app and start exploring the data without login credentials:
- Kibana: http://localhost:5601
Note You need to configure the index patterns in Kibana before you can explore the data.
- Go to
Management > Stack Management > Kibana > Index Patterns
.- Create a new index pattern. For example,
zeebe-record-*
matches the exported records.
- If you don't see any indexes then make sure to export some data first (e.g. deploy a process). The indexes of the records are created when the first record of this type is exported.
- Go to
Analytics > Discover
and select the index pattern.
⚠️ Web Modeler Self-Managed is currently offered as a beta release with limited availability for enterprise customers only. It is not recommended for production use, and there is no maintenance service guaranteed. Special terms & conditions apply. However, we encourage you to provide feedback via your designated support channel or the Camunda Forum.
The Docker images for Web Modeler Beta are available in a private registry. Enterprise customers either already have credentials to this registry, or they can request access to this registry through their CSM contact at Camunda.
To run Camunda Platform with Web Modeler Self-Managed clone this repo and issue the following commands:
$ docker login registry.camunda.cloud
Username: your_username
Password: ******
Login Succeeded
$ docker-compose -f docker-compose.yaml -f docker-compose-web-modeler-beta.yaml up -d
To tear down the whole environment run the following command
$ docker-compose -f docker-compose.yaml -f docker-compose-web-modeler-beta.yaml down -v
If you want to delete everything (including any data you created). Alternatively, if you want to keep the data run:
$ docker-compose -f docker-compose.yaml -f docker-compose-web-modeler-beta.yaml down
Now you can access Web Modeler Self-Managed and log in with the user demo
and password demo
at http://localhost:8070.
Once you are ready to deploy or execute processes use these settings to deploy to the local Zeebe instance:
- Authentication: None
- URL:
zeebe:26500
The setup includes MailHog as a test SMTP server. It captures all emails sent by Web Modeler, but does not forward them to the actual recipients.
You can access emails in MailHog's Web UI at http://localhost:8075.
When using arm64-based hardware like a M1 or M2 Mac the Keycloak container might not start because Bitnami only provides amd64-based images. Until bitnami adds support for linux/arm64 images, you can build and tag an arm-based image locally using the following command. After building and tagging the image you can start the environment as described in Using docker-compose.
$ DOCKER_BUILDKIT=0 docker build -t bitnami/keycloak:19.0.3 "https://github.com/camunda/camunda-platform.git#main:.keycloak/"
Pull in the latest updates from the Process Solution Template, which this template was forked from, using:
git remote add upstream git@github.com:camunda-community-hub/camunda-8-process-solution-template.git
git checkout -b pull-upstream
git pull upstream main --no-rebase
git mergetool
git commit # to conclude merge
git push --set-upstream origin pull-upstream
gh pr create --title "Update from Process Solution Template" --body "Pulls in the latest updates from the [Process Solution Template](https://github.com/camunda-community-hub/camunda-8-process-solution-template) which this template was forked from"
Pulling another change into the same PR:
git pull upstream main --no-rebase
git push