chore(project): introduce Camunda BPM Run

distro/run/README.md

@@ -1,71 +1,57 @@
-# Camunda REST Distribution
+# Camunda BPM Run
 
-## Requirements
+This is a pre-configured Camunda Spring Boot distribution that allows users to simply download and RUN Camunda BPM.
 
-1. User profile:
- * Non-Java developer
- * Able to install the required JDK
- * Familiar with the command line and Rest APIs
-2. No Application Server configuration, i.e., straightforward configuration
-3. Pre-set security configuration
-
-## Design Decisions
-
-We decided to use the Camunda Spring Boot Starter. Reasons:
-1. It produces an uberjar with all the dependencies provided.
-2. It's straightforward to configure (`application.yml`) and to start.
-3. Camunda already supports the technology, and it's easily extendable.
-
-## How to run the Camunda Rest distro
+## How to run it
 1. Build the project with either the `ce` or `ee` profile
-2. In `distro/target`, a `camunda-rest-distro-distro-{project.version}-[ce|ee].zip` will be available.
+2. In `distro/target`, a `camunda-bpm-run-distro-{project.version}-[ce|ee].zip` will be available.
 3. Extract the archive
-4. Go to the `config` folder and add configuration to the application yml
+4. Go to the `config` folder and add configuration to the `application.yml`
 5. Go to the `bin` folder and run `start.sh` (or `start.bat` if you're using Windows).
-  * add the `--webapps` flag if you want to run the Camunda Webapps
-  * add the `--rest` flag if you want to run the Camunda REST API
+  * add the `--webapps` flag if you want to run the Camunda Webapps only
+  * add the `--rest` flag if you want to run the Camunda REST API only
+  * add the `--webapps` and the `--rest` flags if you want to run both (default)
 
 ## Configuration
 
-The distro can be configured through the `application.yml` file found in the `config/` directory
- of the distro archive. You can use the general camunda spring boot starter configuration properties available [here](https://docs.camunda.org/manual/latest/user-guide/spring-boot-integration/configuration/#camunda-engine-properties) as well as the following properties:
+Camunda BPM Run can be configured through the `application.yml` file found in the `config/` directory. 
+You can use the general Camunda Spring Boot Starter configuration properties available [here](https://docs.camunda.org/manual/latest/user-guide/spring-boot-integration/configuration/#camunda-engine-properties) as well as the following additional properties:
 
 ### Authentication
 
-| Prefix           | Property Name   | Description                                                | Defaul Value |
-|------------------|-----------------|------------------------------------------------------------|--------------|
-| rest-distro.auth | .enabled        | Switch on/off authentication                               | true         |
-|                  | .authentication | Authentication method.  Currently only basic is supported | basic        |
-|                  |                 |                                                            |              |
+| Prefix               | Property Name   | Description                                                | Default Value |
+|----------------------|-----------------|------------------------------------------------------------|---------------|
+| camunda.bpm.run.auth | .enabled        | Switch on/off authentication                               | true          |
+|                      | .authentication | Authentication method.  Currently only basic is supported  | basic         |
+|                      |                 |                                                            |               |
 
 ### HTTPS/SSL
 
 The following properties are provided by Spring Boot (see [Common Application Properties](https://docs.spring.io/spring-boot/docs/current/reference/html/appendix-application-properties.html#server-properties)). However, the properties listed below are necessary for Camunda BPM to run with HTTPS.
 
-| Prefix     | Property Name       | Description                                                               | Defaul Value |
-|------------|---------------------|---------------------------------------------------------------------------|--------------|
-| server.ssl | .key-store          | Path to the key store that holds the SSL certificate (.jks or .p12 file). |              |
-|            | .key-store-password | Password used to access the key store.                                    |              |
-|            | .key-store-type     | Type of the key store (pkcs12 or jks).                                    |              |
-|            | .key-alias          | Alias that identifies the key in the key store.                           |              |
-|            | .key-password       | Password used to access the key in the key store.                         |              |
-| server     | .port               | Server HTTPS port (e.g. 8443).                                            |              |
+| Prefix     | Property Name       | Description                                                               | Default Value |
+|------------|---------------------|---------------------------------------------------------------------------|---------------|
+| server.ssl | .key-store          | Path to the key store that holds the SSL certificate (.jks or .p12 file). |               |
+|            | .key-store-password | Password used to access the key store.                                    |               |
+|            | .key-store-type     | Type of the key store (pkcs12 or jks).                                    |               |
+|            | .key-alias          | Alias that identifies the key in the key store.                           |               |
+|            | .key-password       | Password used to access the key in the key store.                         |               |
+| server     | .port               | Server HTTPS port (e.g. 8443).                                            |               |
 
 ### CORS (Cross-Origin Resource Sharing)
 
-| Prefix           | Property Name   | Description                                                            | Defaul Value |
-|------------------|-----------------|------------------------------------------------------------------------|--------------|
-| rest-distro.cors | .enabled        | Switch on/off CORS.                                                    | false        |
-|                  | .allowedOrigins | Comma separated string with origins allowed origins or wildcard ("*"). | "*"          |
+| Prefix               | Property Name   | Description                                                            | Default Value |
+|----------------------|-----------------|------------------------------------------------------------------------|---------------|
+| camunda.bpm.run.cors | .enabled        | Switch on/off CORS.                                                    | false         |
+|                      | .allowedOrigins | Comma separated string with origins allowed origins or wildcard ("*"). | "*"           |
 
 ## Default values
 
-By default, the admin credentials are set to `demo:demo`. This can be changed in the `config
-/application.yml` configuration file.
+By default, the admin credentials are set to `demo:demo`. This can be changed in the `config/application.yml` configuration file.
 
 ### Database
 
-The distro will use the H2 database by default. You will be able to find the database file in the
+Camunda BPM Run will use the H2 database by default. You will be able to find the database file in the
  `bin/camunda-h2-dbs` directory after the initial run. To connect to a different database (out of
   the ones [supported by Camunda](https://docs.camunda.org/manual/latest/introduction/supported-environments/#databases))
  , you will need to perform the following steps:
@@ -76,27 +62,11 @@ The distro will use the H2 database by default. You will be able to find the dat
 ```yaml
 spring.datasource:
   # the DB url and DB Schema name (common template: jdbc:{db-type}://{ip-address}:{port}/{db-schema-name}
-  url: jdbc:h2:./camunda-h2-dbs/process-engine;MVCC=TRUE;TRACE_LEVEL_FILE=0;DB_CLOSE_ON_EXIT=FALSE
+  url: jdbc:h2:./camunda-h2-dbs/process-engine;TRACE_LEVEL_FILE=0;DB_CLOSE_ON_EXIT=FALSE
   # the JDBC driver class
   driver-class-name: org.h2.Driver
   # the DB user
   username: sa
   # the DB password
   password: sa
-```
-
-## Learnings
-
-* New authentication methods have to be implemented in the Engine Rest project through `Filters
-`. Implementing custom authentication methods using `Spring Security` that make use of the
- Engines's authentication layer is not straightforward (however, this means that any new
-  authentication methods are available anywhere the Engine Rest API is integrated).
-* Spring (Boot) uses a custom `maven` property for adding external libraries to the classpath
- (`loader.path`). Using the default `java -cp` or `java -classpath` doesn't work.
-* The `--spring.config.location` argument that passes the location of an external `application.yml
-` configuration file should be passed after the `-jar` argument.
-* The `spring-boot-maven-plugin` provides a `fatjar`. It also packages dependencies with a
- `provided` scope. We needed to explicitly exclude all of the `webapps` dependencies since we
-  optionally include them if the user wants the Camunda Webapps loaded. 
-* Enabling CORS is not straight-forward. The officially documented techniques to enable CORS as well as a filter-based
-approach failed to attach the necessary response headers
+```

distro/run/distro/assembly/base-component.xml

@@ -32,10 +32,10 @@
       <fileMode>0755</fileMode>
     </file>
     <file>
-      <source>target/camunda-rest-distro-distro-${project.version}.jar
+      <source>target/camunda-bpm-run-distro-${project.version}.jar
       </source>
       <outputDirectory>lib/</outputDirectory>
-      <destName>camunda-rest-distro.jar</destName>
+      <destName>camunda-bpm-run.jar</destName>
     </file>
   </files>
   <fileSets>

distro/run/distro/assembly/resources/application.yml

@@ -7,7 +7,7 @@ camunda.bpm:
 
 
 spring.datasource:
-  url: jdbc:h2:./camunda-h2-dbs/process-engine;MVCC=TRUE;TRACE_LEVEL_FILE=0;DB_CLOSE_ON_EXIT=FALSE
+  url: jdbc:h2:./camunda-h2-dbs/process-engine;TRACE_LEVEL_FILE=0;DB_CLOSE_ON_EXIT=FALSE
   driver-class-name: org.h2.Driver
   username: sa
   password: sa

distro/run/distro/assembly/resources/start.bat

@@ -60,4 +60,4 @@ ECHO classpath: %classPath%
 
 
 REM start the application
-call %JAVA% -Dloader.path="%classPath%" -jar "%BASEDIR%/../lib/camunda-rest-distro.jar" --spring.config.location=file:"%BASEDIR%"/../config/application.yml
+call %JAVA% -Dloader.path="%classPath%" -jar "%BASEDIR%/../lib/camunda-bpm-run.jar" --spring.config.location=file:"%BASEDIR%"/../config/application.yml

distro/run/distro/assembly/resources/start.sh

@@ -48,4 +48,4 @@ fi
 echo classpath: $classPath
 
 # start the application
-"$JAVA" -Dloader.path="$classPath" -jar "$BASEDIR/../lib/camunda-rest-distro.jar" --spring.config.location=file:"$BASEDIR"/../config/application.yml
+"$JAVA" -Dloader.path="$classPath" -jar "$BASEDIR/../lib/camunda-bpm-run.jar" --spring.config.location=file:"$BASEDIR"/../config/application.yml

distro/run/distro/pom.xml

@@ -5,14 +5,14 @@
   <modelVersion>4.0.0</modelVersion>
 
   <parent>
-    <groupId>org.camunda.bpm</groupId>
-    <artifactId>camunda-rest-distro-bom</artifactId>
-    <version>1.0-SNAPSHOT</version>
-    <relativePath>../bom</relativePath>
+    <groupId>org.camunda.bpm.run</groupId>
+    <artifactId>camunda-bpm-run-root</artifactId>
+    <version>7.13.0-SNAPSHOT</version>
+    <relativePath>..</relativePath>
   </parent>
 
-  <artifactId>camunda-rest-distro-distro</artifactId>
-  <name>camunda BPM Rest Distro</name>
+  <artifactId>camunda-bpm-run-distro</artifactId>
+  <name>Camunda BPM Run - Distribution</name>
   <packaging>jar</packaging>
 
   <properties>

distro/run/distro/src/main/java/org/camunda/bpm/rest/distro/CamundaRestDistro.java → distro/run/distro/src/main/java/org/camunda/bpm/run/CamundaBpmRun.java

@@ -1,11 +1,11 @@
-package org.camunda.bpm.rest.distro;
+package org.camunda.bpm.run;
 
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 
 @SpringBootApplication
-public class CamundaRestDistro {
+public class CamundaBpmRun {
   public static void main(String... args) {
-    SpringApplication.run(CamundaRestDistro.class, args);
+    SpringApplication.run(CamundaBpmRun.class, args);
   }
 }

distro/run/distro/src/main/java/org/camunda/bpm/rest/distro/CamundaSecurityConfiguration.java → distro/run/distro/src/main/java/org/camunda/bpm/run/CamundaBpmRunSecurityConfiguration.java

@@ -1,13 +1,13 @@
-package org.camunda.bpm.rest.distro;
+package org.camunda.bpm.run;
 
 import javax.servlet.Filter;
 import javax.servlet.ServletException;
 
 import org.apache.catalina.filters.CorsFilter;
 import org.camunda.bpm.engine.rest.security.auth.ProcessEngineAuthenticationFilter;
-import org.camunda.bpm.rest.distro.property.CamundaAuthenticationProperty;
-import org.camunda.bpm.rest.distro.property.CamundaCorsProperty;
-import org.camunda.bpm.rest.distro.property.CamundaRestDistroProperties;
+import org.camunda.bpm.run.property.CamundaBpmRunAuthenticationProperties;
+import org.camunda.bpm.run.property.CamundaBpmRunCorsProperty;
+import org.camunda.bpm.run.property.CamundaBpmRunProperties;
 import org.camunda.bpm.spring.boot.starter.CamundaBpmAutoConfiguration;
 import org.camunda.bpm.spring.boot.starter.rest.CamundaBpmRestInitializer;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -19,41 +19,41 @@
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 
-@EnableConfigurationProperties(CamundaRestDistroProperties.class)
+@EnableConfigurationProperties(CamundaBpmRunProperties.class)
 @Configuration
 @AutoConfigureAfter({ CamundaBpmAutoConfiguration.class })
-public class CamundaSecurityConfiguration {
+public class CamundaBpmRunSecurityConfiguration {
 
   @Autowired
-  CamundaRestDistroProperties camundaRestDistroProperties;
+  CamundaBpmRunProperties camundaBpmRunProperties;
 
   @Bean
   @ConditionalOnClass(CamundaBpmRestInitializer.class)
-  @ConditionalOnProperty(name = "enabled", havingValue = "true", prefix = CamundaAuthenticationProperty.PREFIX)
+  @ConditionalOnProperty(name = "enabled", havingValue = "true", prefix = CamundaBpmRunAuthenticationProperties.PREFIX)
   public FilterRegistrationBean<Filter> processEngineAuthenticationFilter() {
     FilterRegistrationBean<Filter> registration = new FilterRegistrationBean<>();
     registration.setName("camunda-auth");
     registration.setFilter(new ProcessEngineAuthenticationFilter());
     registration.addUrlPatterns("/rest/*");
 
     // if nothing is set, use Http Basic authentication
-    CamundaAuthenticationProperty properties = camundaRestDistroProperties.getAuth();
-    if (properties.getAuthentication() == null || CamundaAuthenticationProperty.DEFAULT_AUTH.equals(properties.getAuthentication())) {
+    CamundaBpmRunAuthenticationProperties properties = camundaBpmRunProperties.getAuth();
+    if (properties.getAuthentication() == null || CamundaBpmRunAuthenticationProperties.DEFAULT_AUTH.equals(properties.getAuthentication())) {
       registration.addInitParameter("authentication-provider", "org.camunda.bpm.engine.rest.security.auth.impl.HttpBasicAuthenticationProvider");
     }
 
     return registration;
   }
 
   @Bean
-  @ConditionalOnProperty(name = "enabled", havingValue = "true", prefix = CamundaCorsProperty.PREFIX)
+  @ConditionalOnProperty(name = "enabled", havingValue = "true", prefix = CamundaBpmRunCorsProperty.PREFIX)
   public FilterRegistrationBean<Filter> corsFilter() throws ServletException {
     FilterRegistrationBean<Filter> registration = new FilterRegistrationBean<>();
     registration.setName("camunda-cors");
     CorsFilter corsFilter = new CorsFilter();
     registration.setFilter(corsFilter);
     registration.addUrlPatterns("/rest/*");
-    registration.addInitParameter(CorsFilter.PARAM_CORS_ALLOWED_ORIGINS, camundaRestDistroProperties.getCors().getAllowedOrigins());
+    registration.addInitParameter(CorsFilter.PARAM_CORS_ALLOWED_ORIGINS, camundaBpmRunProperties.getCors().getAllowedOrigins());
     return registration;
   }
 }

distro/run/distro/src/main/java/org/camunda/bpm/rest/distro/property/CamundaAuthenticationProperty.java → distro/run/distro/src/main/java/org/camunda/bpm/run/property/CamundaBpmRunAuthenticationProperties.java

@@ -1,11 +1,11 @@
-package org.camunda.bpm.rest.distro.property;
+package org.camunda.bpm.run.property;
 
 import java.util.Arrays;
 import java.util.List;
 
-public class CamundaAuthenticationProperty {
+public class CamundaBpmRunAuthenticationProperties {
 
-  public static final String PREFIX = CamundaRestDistroProperties.PREFIX + ".auth";
+  public static final String PREFIX = CamundaBpmRunProperties.PREFIX + ".auth";
   public static final String DEFAULT_AUTH = "basic";
   public static final List<String> AUTH_METHODS = Arrays.asList(DEFAULT_AUTH);
 
@@ -33,6 +33,6 @@ public void setAuthentication(String authentication) {
 
   @Override
   public String toString() {
-    return "CamundaAuthenticationProperty [enabled=" + enabled + ", authentication=" + authentication + "]";
+    return "CamundaBpmRunAuthenticationProperties [enabled=" + enabled + ", authentication=" + authentication + "]";
   }
 }

distro/run/distro/src/main/java/org/camunda/bpm/rest/distro/property/CamundaCorsProperty.java → distro/run/distro/src/main/java/org/camunda/bpm/run/property/CamundaBpmRunCorsProperty.java

@@ -1,8 +1,8 @@
-package org.camunda.bpm.rest.distro.property;
+package org.camunda.bpm.run.property;
 
-public class CamundaCorsProperty {
+public class CamundaBpmRunCorsProperty {
 
-  public static final String PREFIX = CamundaRestDistroProperties.PREFIX + ".cors";
+  public static final String PREFIX = CamundaBpmRunProperties.PREFIX + ".cors";
   public static final String DEFAULT_ORIGINS = "*";
 
   boolean enabled;
@@ -29,6 +29,6 @@ public void setAllowedOrigins(String allowedOrigins) {
 
   @Override
   public String toString() {
-    return "CamundaCorsProperty [enabled=" + enabled + ", allowedOrigins=" + allowedOrigins + "]";
+    return "CamundaBpmRunCorsProperty [enabled=" + enabled + ", allowedOrigins=" + allowedOrigins + "]";
   }
 }

distro/run/distro/src/main/java/org/camunda/bpm/rest/distro/property/CamundaRestDistroProperties.java → distro/run/distro/src/main/java/org/camunda/bpm/run/property/CamundaBpmRunProperties.java

@@ -1,33 +1,33 @@
-package org.camunda.bpm.rest.distro.property;
+package org.camunda.bpm.run.property;
 
 import org.camunda.bpm.spring.boot.starter.property.CamundaBpmProperties;
 import org.springframework.boot.context.properties.ConfigurationProperties;
 import org.springframework.boot.context.properties.NestedConfigurationProperty;
 
-@ConfigurationProperties(CamundaRestDistroProperties.PREFIX)
-public class CamundaRestDistroProperties {
+@ConfigurationProperties(CamundaBpmRunProperties.PREFIX)
+public class CamundaBpmRunProperties {
+
+  public static final String PREFIX = CamundaBpmProperties.PREFIX + ".run";
 
-  public static final String PREFIX = CamundaBpmProperties.PREFIX + ".rest-distro";
-
   @NestedConfigurationProperty
-  private CamundaAuthenticationProperty auth = new CamundaAuthenticationProperty();
+  private CamundaBpmRunAuthenticationProperties auth = new CamundaBpmRunAuthenticationProperties();
 
   @NestedConfigurationProperty
-  private CamundaCorsProperty cors = new CamundaCorsProperty();
+  private CamundaBpmRunCorsProperty cors = new CamundaBpmRunCorsProperty();
 
-  public CamundaAuthenticationProperty getAuth() {
+  public CamundaBpmRunAuthenticationProperties getAuth() {
     return auth;
   }
 
-  public void setAuth(CamundaAuthenticationProperty auth) {
+  public void setAuth(CamundaBpmRunAuthenticationProperties auth) {
     this.auth = auth;
   }
 
-  public CamundaCorsProperty getCors() {
+  public CamundaBpmRunCorsProperty getCors() {
     return cors;
   }
 
-  public void setCors(CamundaCorsProperty cors) {
+  public void setCors(CamundaBpmRunCorsProperty cors) {
     this.cors = cors;
   }
 

distro/run/distro/src/test/java/org/camunda/bpm/rest/distro/test/AbstractRestTest.java → distro/run/distro/src/test/java/org/camunda/bpm/run/test/AbstractRestTest.java

@@ -14,12 +14,12 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.camunda.bpm.rest.distro.test;
+package org.camunda.bpm.run.test;
 
 import java.util.Collections;
 
-import org.camunda.bpm.rest.distro.CamundaRestDistro;
-import org.camunda.bpm.rest.distro.test.util.LoggingInterceptor;
+import org.camunda.bpm.run.CamundaBpmRun;
+import org.camunda.bpm.run.test.util.LoggingInterceptor;
 import org.junit.Before;
 import org.junit.runner.RunWith;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -31,7 +31,7 @@
 import org.springframework.test.context.junit4.SpringRunner;
 
 @RunWith(SpringRunner.class)
-@SpringBootTest(classes = { CamundaRestDistro.class }, webEnvironment = WebEnvironment.RANDOM_PORT)
+@SpringBootTest(classes = { CamundaBpmRun.class }, webEnvironment = WebEnvironment.RANDOM_PORT)
 @ActiveProfiles(profiles = { "test-auth-disabled" })
 public abstract class AbstractRestTest {