Camunda Platform 7 is very flexible and can be hooked into the architecture of your choice, giving you a number of important decisions to make. If you don't have special architecture requirements, we recommend following the proposed greenfield stack. You can also check the decision criteria presented below to make more customized choices. Choosing the stack will have big influence on your overall architecture.
This best practice targets Camunda Platform 7.x only! If you look for Camunda Platform 8, please refer to Deciding about your Camunda Platform 8 stack.
The Java greenfield stack
Use the following stack:
Use Maven as a build tool.
Use your favorite IDE, for example Visual Studio Code, IntelliJ or Eclipse.
Use OpenJDK JDK 17 as Java runtime.
Model the processes with the Camunda Modeler.
Add your process models and all Java code to the project.
The default distribution leverages an H2 file-based Java database. We recommend using this for development. We strongly discourage multiple developers share the same database during development as this can lead to a multitude of problems.
To run the process application in production, extend the stack:
Use PostgreSQL, or the database you already operate.
Run the process application by copying the
jarfile to the server and start it with
java -jar YourProcessApplication.jar. This can also be done via Docker.
See our example application.
Understanding the stack's architecture
The basic architecture with this stack is shown in the following diagram:
Understanding our motivation for the stack
While we went through long and detailed discussions to come to this recommendation, it doesn't mean that it is necessarily superior to alternative stacks. You can still feel confident if you go down another route (see below for alternative options). But for our Best Practices, we wanted to give exactly one greenfield recommendation for all our customers who have no special requirements on the stack.
We decided on this stack for the following reasons:
- All components are open source and easily available.
- Camunda Run is the favorite distribution, as it focuses on external tasks, the more modern paradigm also present in Camunda Platform 8.
- Spring Boot is currently the most adopted way of building Java applications.
- Spring Boot applications are easy to customize as well as easy to roll out into test and production environments, either on-premise or in the cloud.
- PostgreSQL has a great track-record for performance.
There are several advantages using the greenfield stack:
- Fewer decisions: Depending on your experience with the Java cosmos, the decisions to chose a stack might not be easy to take. So if you don't have special requirements, follow a well-known path.
- Proven: Many of our customers use this stack with great success.
- More documentation & Best Practices: You don't have to write your own extensive documentation, just point to the Camunda docs.
- Easier support: Asking for help gets much easier as you do not have to explain your setup in detail.
Considering Camunda Platform 8 instead
Camunda Platform 8 is an alternative process automation offering that catches up on funcationality quickly. For new projects, consider using Camunda Platform 8 from the start. You can find a quick comparison of concepts in the docs. Note that architecturally, the recommended greenfield stack in this best practice is close to what you do using Camunda Platform 8.
Getting started with the greenfield stack
Check the prerequisites:
Install OpenJDK JDK 17.
Install Camunda Modeler.
Install an IDE like Eclipse. We recommend the latest "Eclipse IDE for Java Developers".
- Activate workspace file sync refresh using native hooks or polling to improve interaction of Eclipse and Camunda Modeler.
- Add Camunda Assert to your Eclipse content assist favorites.
Check your network access to Camunda Artifactory for downloading Maven Artifacts.
As an Enterprise Customer, check that you have your company credentials at hand to log in and get enterprise versions.
Create your development project
- Create a new Spring Boot project (e.g. using Spring initializr)
- Add the dependency for the Camunda Engine OpenAPI REST Client community extension:
- Model a process with Camunda Modeler and save it under
- Run the main Java application class via your IDE.
- Play around with your process using the Camunda web apps (user
- Package your application with
mvn clean install.
- Bring the
jarfile to your test or production server and start it there.
- You can set up or integrate it into an existing continuous delivery pipeline.
Customize your stack
Selecting the process engine mode
|Camunda Run (Remote engine)||Embedded Engine||Container-Managed Engine|
|Run the engine as an isolated BPM server only, communicating with it via Web Services.||Use the process engine as a simple library within your own application, typically started via Spring Boot.||Run the engine as a service preconfigured in your Java EE container.|
|Engine Bootstrap / Lifecycle Management||Out-of-the-box||Out-of-the-box for Spring Boot, otherwise do-it-yourself (see options below)||Out-of-the-box|
|Camunda Webapps work in all use-cases||✔||See limitations below||✔|
|Camunda REST API work in all use-cases||✔||See options below||✔|
|Multiple Process Applications can share a central engine||✔||Doable with a shared database, but requires custom development and has limitations||✔|
|Multiple Engines can share resources (e.g. share the Job Executor)||✔|
|One application WAR/EAR can include the process engine||✔|
|Supports untouched ("vanilla") containers||✔||✔|
|Runs in every Java environment||✔||✔||On Supported Containers|
|Responsibility for Engine Installation and Configuration||Operations or Application Developer||Application Developer||Operations or Application Developer|
|Application point of view on process engine||Remote Server||Library||Library|
|Possible communication types with services||Remote||Java InVM, Remote||Java InVM, Remote|
|Programming language||Polyglot (Java, NodeJs, C#, ...)||Java||Java|
|Use when||Default, if there is no reason against it. Especially if your architecture or applications are not Java based.||You want a single deployment including the engine.||You use a supported application server and prefer to seperate engine installation from application development.|
|Learn More||Learn More||Learn More|
In essence, the general recommendation is:
Use Camunda Run whenever possible.
Do not use a container-managed engine. The container managed engine allows to separate installation and configuration of the engine from the application development. This is an advantage if you really separate these roles within your organization. However, we experienced that this causes trouble more often than it does help. Developers most often are still responsible to install the engine, but might not be able to access the application server itself. That also explains the rise of Spring Boot (often alongside with Docker) and many projects successfully moved to that approach instead. Unless you have good reasons, we would not recommend starting new projects using a container-managed engine.
Use an embedded engine via Spring Boot if you need to provide one combined deployment artifact.
Understanding embedded engine specifics
If you want to use an embedded engine (which is not the default recommendation; see above,) the following information will help you use it correctly.
Using Spring Boot
The Camunda Spring Boot Starter is a clean way of controlling the embedded engine easily, so you don't have to think about the specifics mentioned below in this section. This makes Spring Boot a good choice for Camunda projects.
Bootstrapping the engine and managing its lifecycle
When running the engine in embedded mode, you have to control the lifecycle of the engine yourself, basically starting up and shutting down the engine, and providing access to the API whenever a client needs it. You have several options to do that.
|Spring Boot||Spring Application Context||Programmatic|
|Configure, start, and stop the engine via Spring Boot Starter||Configure, start, and stop the engine via Spring Beans defined in your Application Context.||Configure, start, and stop the engine via Camunda’s processes.xml descriptor and a ProcessApplication class.||Configure, start, and stop the engine yourself programmatically by using Java code.|
|Use when||You target Spring Boot as runtime environment.||You already use Spring.||You do not want to introduce a Spring dependency just for Camunda.||You need full control over the engine or want to do advanced customizations.|
|Unlimited Configuration Options||✔||✔||✔|
Providing a REST API
When running an embedded engine, it might be harder to deploy the pre-built REST API.
|Use Spring Boot Starter for REST API||Embed Camunda’s REST API||Use Camunda’s Standalone Web App REST API|
|The Spring Boot Starter allows to run the REST API as well as the Camunda web applications.||Provide Camunda’s REST API by embedding its JAX-RS code into your application.||Deploy Camunda’s "Standalone" Web Application (which runs its own engine) and use its REST API.|
|No Classloading Restrictions||✔||✔|
Providing Camunda web applications (Tasklist, Cockpit)
When running an embedded engine, you may want to use a Camunda web application like Tasklist and Cockpit, but have to decide how exactly to run these web applications in your environment.
|Use Spring Boot Starter for Camunda Web Applications||Camunda "Standalone" Web Application||Embedded Camunda Web Applications|
|The Spring Boot Starter allows you to run the REST API as well as the Camunda web applications.||Deploy Camunda’s "Standalone" Web Application, which is a WAR running its own engine, and point it to your applications engine database.||Embed the Camunda Web Applications into your own application, which is not a particularly easy task to do.|
|Classloading Restrictions||None||For example, you can not submit a task in Tasklist when a following synchronously called service uses a class contained in your own application. However, you can solve this by adding additional safe points.||None|
|Development Effort||Low||Low||High (undocumented)|
|Spring Boot Starter||Download Standalone Web Application||Implement e.g. via Maven WAR Overlays|
Choosing a database
Camunda Platform 7 requires a relational database for persistence. Even if the persistence provider is in theory pluggable and can be exchanged by e.g. some NoSQL persistence this is neither recommended nor supported. Therefore, if you have use cases for this, discuss them with Camunda beforehand!
|PostgreSQL is an open source, object-relational database system.||Oracle Database is a commercial object-relational database system.||H2 is a Java SQL database with in-memory mode and a small footprint.|
|Best Performance Observations||✔||✔|
|No installation required||✔|
|Recommended for unit testing||✔|
|Recommended for production use||✔||✔||✔ (if supported)|
|Learn More||Learn More||Learn More||Supported Databases|
Ideally, use the database your organization already operates and your team is experienced with!
Modeling for executable processes
We distinguish two different roles modeling in BPM projects:
Process developers develop an executable process implementation. Process developers implementing solutions with Camunda must use Camunda Modeler to model executable processes, edit technical attributes, and manage and version (e.g. in Git or SVN) the resulting (XML) files as part of the development project.
Process analysts capture the operational know how about a process. For this part of the work, it is possible to use a different tool than Camunda Modeler.
|Camunda Modeler||Third-Party Modeler (BPMN Standard Compliant)||Third-Party Modeler (Non-Compliant to Standard)|
|Roundtrip in between process analysts and developers possible||✔||✔ (Carefully check level of BPMN compliance - the Model Interchange Working Group can serve as a first starting point|
|Use for process analysts||✔||✔|
|Use for process developers||✔|
|Use when||You do not have a BPMN standard compliant modeling tool already rolled out.||You already rolled out a BPMN tool with a standard compliancy sufficient for roundtrip.||Try to avoid|