From 8f97e8b02c7a1063fa0a0199531d9a357dcdca69 Mon Sep 17 00:00:00 2001 From: Emmanuel Duchastenier Date: Wed, 13 Dec 2023 13:03:34 +0100 Subject: [PATCH 1/3] feat(properties): how to configure Bonita with properties * with Setup Tool * via Java Sysprops * via Env vars --- modules/ROOT/pages/release-notes.adoc | 4 +- .../configuring-bonita-with-properties.adoc | 179 ++++++++++++++++++ 2 files changed, 182 insertions(+), 1 deletion(-) create mode 100644 modules/runtime/pages/configuring-bonita-with-properties.adoc diff --git a/modules/ROOT/pages/release-notes.adoc b/modules/ROOT/pages/release-notes.adoc index b0c08f12e9..53b8c5e370 100644 --- a/modules/ROOT/pages/release-notes.adoc +++ b/modules/ROOT/pages/release-notes.adoc @@ -333,10 +333,12 @@ When enabled, the application will start, go through its initialization and upda === Properties source priority order -Prior Bonita 2023.2, properties files from database had priority over environment or system variables. We decide to reverse this order so that you can easily override database properties with environment or system variables, and to be in line with the https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.external-config[Spring / Spring Boot philosophy]. +Prior to Bonita 2023.2, properties files from database had priority over environment or system variables. We decide to reverse this order so that you can easily override database properties with environment or system variables, and to be in line with the https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.external-config[Spring / Spring Boot philosophy]. To be backward compatible, we introduce the boolean property `bonita.runtime.properties.order.legacy-mode` (default: `false`) to enable the previous priority order of properties source. +Full details can be found xref:runtime:configuring-bonita-with-properties.adoc[on the dedicated page]. + === Runtime property renaming In order to improve Bonita property naming coherence, a work is in progress to change some property names. diff --git a/modules/runtime/pages/configuring-bonita-with-properties.adoc b/modules/runtime/pages/configuring-bonita-with-properties.adoc new file mode 100644 index 0000000000..b896b4a44a --- /dev/null +++ b/modules/runtime/pages/configuring-bonita-with-properties.adoc @@ -0,0 +1,179 @@ += Bonita Runtime configuration +:description: This page explains how Bonita runtime can be configured through properties, via database, Java System properties, or environment variables + +{description} + + +== Context + +Bonita runtime can be configured in a variety of ways: + +* by changing values in `.properties` files that are stored in Bonita database. This process involves the retrieval (`pull`) and the update (`push`) of the database through xref:runtime:bonita-platform-setup.adoc[]. +* by setting a https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[Java System Property] that is passed to the JVM (Java Virtual Machine) at startup +* by setting an OS https://www3.ntu.edu.sg/home/ehchua/programming/howto/Environment_Variables.html[Environment Variable] that is present either globally for the entire Operating System, or locally in the Shell that starts Bonita. +** DevOps familiar with Docker are used to set Env Variables via `-e prop=value` + + +== Changing a property in database via the Setup Tool + +The xref:runtime:bonita-platform-setup.adoc[Setup Tool] allows you to modify Bonita properties in the database. + +Use `setup.sh / setup.bat pull` to retrieve the configuration files from the database, then edit the configuration file according to your needs +, then push back the configuration file to database using `setup.sh / setup.bat push`. + +Here is an example of one of Bonita configuration files `bonita-platform-community-custom.properties`: + +[source,properties,subs="+macros,+attributes"] +---- +# ... +# Hibernate persistence configuration: +#bonita.platform.persistence.generate_statistics=false +# ... +---- + +In `\*-custom.properties` files, all lines are commented out (prefixed by a # character), and the *default value* is set. +You can change a property value by removing the # character at the beginning of the line, and change the default value with the one that suits your needs. + + +== Setting a property via a Java System Property + +Instead of changing a property in the database, you can set a Java System Property that will override the default value defined in the database. + +This is usually done in the `setenv.sh` or `setenv.bat` file that is used to start Bonita Runtime, located in the `setup/tomcat_templates/` folder. + +Eg. + +[source,shell] +---- +# ... +CUSTOM_OPTS="-Dbonita.platform.persistence.generate_statistics=true" +# ... +CATALINA_OPTS="${CATALINA_OPTS} ${CUSTOM_OPTS}" +# ... +---- + +[NOTE] +==== +Keep in mind that doing this, the value in database is ignored, so the values there do not reflect the actual configuration. +==== + + + +== Setting a property via an Environment Variable + +Instead of changing a property in the database, you can set an Environment Variable that will override the default value defined in the database. + +As soon as the Environment Variable is set, it will be taken into accoutn by Bonita Runtime at startup. It includes Environment Variables available globally on the OS, Environment Variables set in the shell that starts Bonita Runtime, or Environment Variables set in the Docker container that starts Bonita Runtime. + +Eg. + +In a Linux Shell: + +[source,shell,subs="+macros,+attributes"] +---- +export BONITA_PLATFORM_PERSISTENCE_GENERATE_STATISTICS=true +---- + +When starting a Bonita Docker container: + +[source,shell,subs="+macros,+attributes"] +---- +docker run -e BONITA_PLATFORM_PERSISTENCE_GENERATE_STATISTICS=true ... +---- + +In a `docker-compose.yml` file: + + +[source,yaml,subs="+macros,+attributes"] +---- +services: +# ... + bonita: + image: bonita:pass:a[{bonitaVersion}] + environment: + - BONITA_PLATFORM_PERSISTENCE_GENERATE_STATISTICS=true +# ... +---- + + + +[NOTE] +==== +Keep in mind that doing this, the value in database is ignored, so the values there do not reflect the actual configuration. +==== + +== Naming convention + +You may have noticed that the property name as an *Environment Variable* is not exactly the same as the name in the database or as a Java System Property. + +Because of limitations of the set of characters allowed in Environment Variables, the name of the Environment Variable is obtained from the base property name: + +* by replacing all dots (`.`) and dashes (`-`) by underscores (`_`) +* and by putting all characters in UPPERCASE + +Eg. + +* `bonita.platform.persistence.generate_statistics` becomes `BONITA_PLATFORM_PERSISTENCE_GENERATE_STATISTICS` +* `bonita.runtime.authorization.dynamic-check.enabled` becomes `BONITA_RUNTIME_AUTHORIZATION_DYNAMIC_CHECK_ENABLED` + + +== How a property is looked up + +When Bonita Runtime starts, it looks up for properties *in the following order*: + +* defined as a Java System property +* if not found, defined as an Environment Variable +* if not found, defined in the database, in one of the properties files that Bonita supports + + +Prior to Bonita 2023.2, properties files from database had priority over environment or system variables. We decide to reverse this order so that you can easily override database properties with environment or system variables, and to be in line with the https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.external-config[Spring / Spring Boot philosophy]. + + +== Compatibility with versions prior to 9.0 (2023.2) + +In most environments, you should not have any conflict between existing Environment Variables and Bonita Runtime properties stored in the database. +However, if you have a conflict, you can use the `bonita.runtime.properties.order.legacy-mode` (default: `false`) property to revert to the previous order of priority. + +Like any other property, you can set it as a Java System Property + +[source,shell,subs="+macros,+attributes"] +---- +-Dbonita.runtime.properties.order.legacy-mode=true +---- + +or as an Environment Variable: + +In a Linux Shell: + +[source,shell,subs="+macros,+attributes"] +---- +export BONITA_RUNTIME_PROPERTIES_ORDER_LEGACY_MODE=true +---- + +When starting a Bonita Docker container: + +[source,shell,subs="+macros,+attributes"] +---- +docker run -e BONITA_RUNTIME_PROPERTIES_ORDER_LEGACY_MODE=true ... +---- + +In a `docker-compose.yml` file: + + +[source,yaml,subs="+macros,+attributes"] +---- +services: +# ... + bonita: + image: bonita:pass:a[{bonitaVersion}] + environment: + - BONITA_RUNTIME_PROPERTIES_ORDER_LEGACY_MODE=true +# ... +---- + + +== limitations + +Some properties cannot be changed via System Properties or Environment Variables: + +* TODO \ No newline at end of file From aa477cca3241c796cb740b5a1f9c0b563a395f62 Mon Sep 17 00:00:00 2001 From: Emmanuel Duchastenier Date: Wed, 13 Dec 2023 21:41:13 +0100 Subject: [PATCH 2/3] Integrate code review feedbacks --- .../runtime/pages/configuring-bonita-with-properties.adoc | 7 +++++-- modules/runtime/pages/runtime-configuration-index.adoc | 5 +++++ modules/runtime/runtime-nav.adoc | 1 + 3 files changed, 11 insertions(+), 2 deletions(-) diff --git a/modules/runtime/pages/configuring-bonita-with-properties.adoc b/modules/runtime/pages/configuring-bonita-with-properties.adoc index b896b4a44a..8a847e9a51 100644 --- a/modules/runtime/pages/configuring-bonita-with-properties.adoc +++ b/modules/runtime/pages/configuring-bonita-with-properties.adoc @@ -31,7 +31,7 @@ Here is an example of one of Bonita configuration files `bonita-platform-communi # ... ---- -In `\*-custom.properties` files, all lines are commented out (prefixed by a # character), and the *default value* is set. +In `+++*-custom.properties+++` files, all lines are commented out (prefixed by a # character), and the *default value* is set. You can change a property value by removing the # character at the beginning of the line, and change the default value with the one that suits your needs. @@ -176,4 +176,7 @@ services: Some properties cannot be changed via System Properties or Environment Variables: -* TODO \ No newline at end of file +* properties from file `security-config.properties` +* properties from file `spnego-config.properties` (used for SSO Kerberos) +* SAML configuration files +* permissions from files `dynamic-permissions-checks-custom.properties`, `compound-permissions-mapping-custom.properties`, `resources-permissions-mapping-custom.properties` diff --git a/modules/runtime/pages/runtime-configuration-index.adoc b/modules/runtime/pages/runtime-configuration-index.adoc index 52dcf6a21e..f5f19c91c0 100644 --- a/modules/runtime/pages/runtime-configuration-index.adoc +++ b/modules/runtime/pages/runtime-configuration-index.adoc @@ -17,6 +17,11 @@ xref:runtime:bonita-platform-setup.adoc[[.card-title]#Setup tool# [.card-body.ca xref:ROOT:database-configuration.adoc[[.card-title]#Database configuration# [.card-body.card-content-overflow]#pass:q[Create and customize the database for Bonita Engine and the BDM]#] -- +[.card.card-index] +-- +xref:runtime:configuring-bonita-with-properties.adoc[[.card-title]#Bonita configurability# [.card-body.card-content-overflow]#pass:q[Know how Bonita runtime can be configured through properties (database, Java System properties, environment variables)]#] +-- + [.card.card-index] -- xref:ROOT:licenses.adoc[[.card-title]#Licenses# [.card-body.card-content-overflow]#pass:q[Generate and install your license]#] diff --git a/modules/runtime/runtime-nav.adoc b/modules/runtime/runtime-nav.adoc index aef4e96245..d4b76d8685 100644 --- a/modules/runtime/runtime-nav.adoc +++ b/modules/runtime/runtime-nav.adoc @@ -67,6 +67,7 @@ ** xref:runtime-configuration-index.adoc[Configuration] *** xref:bonita-platform-setup.adoc[Setup tool] *** xref:database-configuration.adoc[Database configuration] + *** xref:configuring-bonita-with-properties.adoc[Bonita configuration properties] *** xref:first-steps-after-setup.adoc[First steps after setup] *** xref:licenses.adoc[Licenses] *** xref:set-log-and-archive-levels.adoc[Recording levels] From 21f46b774ed14dc5e05075e6ee382540f49e7b05 Mon Sep 17 00:00:00 2001 From: Emmanuel Duchastenier Date: Wed, 13 Dec 2023 21:49:01 +0100 Subject: [PATCH 3/3] PR feedbacks: put code samples in (synched) tabs --- .../configuring-bonita-with-properties.adoc | 48 ++++++++++++------- 1 file changed, 31 insertions(+), 17 deletions(-) diff --git a/modules/runtime/pages/configuring-bonita-with-properties.adoc b/modules/runtime/pages/configuring-bonita-with-properties.adoc index 8a847e9a51..eacee85809 100644 --- a/modules/runtime/pages/configuring-bonita-with-properties.adoc +++ b/modules/runtime/pages/configuring-bonita-with-properties.adoc @@ -1,5 +1,6 @@ = Bonita Runtime configuration :description: This page explains how Bonita runtime can be configured through properties, via database, Java System properties, or environment variables +:tabs-sync-option: {description} @@ -67,23 +68,29 @@ As soon as the Environment Variable is set, it will be taken into accoutn by Bon Eg. -In a Linux Shell: - +[tabs] +==== +In a Linux Shell:: ++ +-- [source,shell,subs="+macros,+attributes"] ---- export BONITA_PLATFORM_PERSISTENCE_GENERATE_STATISTICS=true ---- +-- -When starting a Bonita Docker container: - +Starting a Docker container:: ++ +-- [source,shell,subs="+macros,+attributes"] ---- docker run -e BONITA_PLATFORM_PERSISTENCE_GENERATE_STATISTICS=true ... ---- +-- -In a `docker-compose.yml` file: - - +docker-compose:: ++ +-- [source,yaml,subs="+macros,+attributes"] ---- services: @@ -94,8 +101,8 @@ services: - BONITA_PLATFORM_PERSISTENCE_GENERATE_STATISTICS=true # ... ---- - - +-- +==== [NOTE] ==== @@ -143,23 +150,29 @@ Like any other property, you can set it as a Java System Property or as an Environment Variable: -In a Linux Shell: - +[tabs] +==== +In a Linux Shell:: ++ +-- [source,shell,subs="+macros,+attributes"] ---- export BONITA_RUNTIME_PROPERTIES_ORDER_LEGACY_MODE=true ---- +-- -When starting a Bonita Docker container: - +Starting a Docker container:: ++ +-- [source,shell,subs="+macros,+attributes"] ---- docker run -e BONITA_RUNTIME_PROPERTIES_ORDER_LEGACY_MODE=true ... ---- +-- -In a `docker-compose.yml` file: - - +docker-compose:: ++ +-- [source,yaml,subs="+macros,+attributes"] ---- services: @@ -170,7 +183,8 @@ services: - BONITA_RUNTIME_PROPERTIES_ORDER_LEGACY_MODE=true # ... ---- - +-- +==== == limitations