Environment Variables, System Properties and Other Runtime Configuration Options

Environment Variables

Environment Variables are configuration options that are present in the execution environment where Cadenza is running. Depending on the operating system (Windows or Linux) or the execution environment (as a script in Linux or as a container for example) there are different ways of setting these.

In Linux when starting from the command line an environment variable can for example be set with the export command:

$ export CADENZA_EXIT_ON_STARTUP_ERROR=true
$ ./start_cadenza.sh

If you look into the cadenza_settings.sh script that is included with our distribution you will see a bunch of environment variables already preset. See Installation From an Archive File for more information on this.

If you run Cadenza via Docker you can pass environment variables to the docker command with the -e flag.

Existing environment variables in your environment will be available to and used by Cadenza. If you want to prevent this, you need to unset or overwrite these environment variables explicitly before starting Cadenza.

System Properties

System Properties are a mechanism provided by the Java runtime. Some configuration options are only available through System Properties as they are provided by the Java runtime itself. For options that Cadenza provides we try to provide them both as environment variables as well as System Properties.

System Properties are passed to the Java VM with the -D command line parameter, for example:

java -Dnet.disy.cadenza.web.session.cookies.secure=true ...

Note the special syntax where the property name is concatenated with the -D parameter, followed by an equals sign and then the value. If the value contains spaces you need to surround it with double quotes.

Other Options

Some configuration properties are directly provided by the Java runtime and have their own special flags that need to be passed directly to the java executable. These are options like the maximum amount of memory to allow for the Java VM with -Xmx.

Relevant options to the operation of Cadenza are described in this document.

Priority of Options

You will note that many of the options can be specified as both environment variables as well as system properties. These are evaluated in a special order:

  1. If a system property is present it will win over the environment variable

  2. If no system property is present but there is an environment variable then that will be used

  3. We fall back to the default value if neither option is present

Required Options

Configuration Path

Environment variable

CADENZA_CONFIG_PATH

Java system property

CADENZA_CONFIG_PATH

Default value

<cadenza_home>/config

Preferences Mechanism

This disables usage of the Java Preferences system. This prevents unnecessary - and when using Docker illegal - disk usage.

This must always be set to net.disy.cadenza.web.preferences.NoopPreferencesFactory.

Environment variable

none

Java system property

java.util.prefs.PreferencesFactory

Default value

none

Example

-Djava.util.prefs.PreferencesFactory=net.disy.cadenza.web.preferences.NoopPreferencesFactory

Recommended Options

Path to Write Logfile to (if relevant)

To configure only the path where the cadenza-web-*.log files are written, you can set it using:

Environment variable

CADENZA_LOG_PATH

Java system property

none

Default value

<CATALINA_HOME>/logs

Configuration File for Logging (if relevant)

Logging, including performance logging, uses the log4j framework. If you want to modify more than just the location (see CADENZA_LOG_PATH above) where the logfile is written you can specify your own log4j2 XML configuration file using:

Environment variable

LOG4J_CONFIGURATION_FILE

Java system property

log4j2.configurationFile

Default value

<cadenza_home>/WEB-INF/classes/log4j2.xml

Configuration Modes

Cadenza can be started using different configuration modes. Supported are the following combinations:

  • multi-file, env (default): Configuration is done via the different XML configuration files in the configuration directory of Cadenza (see CADENZA_CONFIG_PATH) and can be overwritten using environment variables or system properties.

  • multi-file: Configuration is only done via the different XML configuration files in the configuration directory of Cadenza (see CADENZA_CONFIG_PATH). Overwriting using environment variables or system properties is not possible.

  • single-file, env: Configuration is done via a single unified configuration file (see CADENZA_CONFIG_FILE) and can be overwritten using environment variables or system properties.

  • single-file: Configuration is only done via a single unified configuration file (see CADENZA_CONFIG_FILE). Overwriting using environment variables or system properties is not possible.

Environment variable

CADENZA_CONFIG_MODES

Java system property

CADENZA_CONFIG_MODES

Default value

multi-file, env

Single Unified Configuration File

Only required if the single-file mode is enabled (see CADENZA_CONFIGURATION_MODE): absolute file path that refers to the single unified configuration file. Supported file extensions are .yml/.yaml.

For example:

/foo/bar/cadenzaconfig.yml

or

C:/foo/bar/cadenzaconfig.yaml

Logging Cadenza Configuration

Specifying a value enables the log output on info-level of the current (unresolved) Cadenza configuration in the specified format. Possible values are

  • yml

  • yaml

  • env

  • properties

Logging the current (xml-based) unresolved configuration can be a convenient method to convert the multi-file configuration to a single unified file.

Environment variable

CADENZA_CONFIG_LOGGING_FORMAT

Java system property

CADENZA_CONFIG_LOGGING_FORMAT

Default value

none

Logging Cadenza Configuration Content

Specifies what content to log if CADENZA_CONFIG_LOGGING_FORMAT is enabled. By default this is the 'unresolved' configuration. When logging the unresolved configuration, the unset values are not displayed. However, it is possible to set the content type to `sample' instead, which allows exploration of possible settings at a structural level. Configuration settings for inactive plugins are not logged.

Settings with unresolved variables (like $SYSTEM{}) for non-string values cannot be logged.

It is strongly recommended to compare the occurrences of $SYSTEM/$VAR in the logged output with the existing configuration files. It depends on the particular configuration scheme and circumstances whether variables for non-string values cause visible error hints (look for "!!!" in the logged output), or simply don’t appear.

Environment variable

CADENZA_CONFIG_LOGGING_CONTENT

Java system property

CADENZA_CONFIG_LOGGING_CONTENT

Default value

unresolved

Custom Theme Path (if relevant)

Cadenza Web ships with a default theme, but also supports using custom themes.

The directory structure as well as the file names have to correspond to the files from the default theme that are intended to be overridden – as Cadenza allows overriding individual files from the default theme.

For any file which is not overridden in the custom theme, the original file from the default theme is used.

Environment variable

CADENZA_THEMES_PATH

Java system property

CADENZA_THEMES_PATH

Default value

<cadenza_home>

Session Timeout

Time in minutes for session timeout.

Environment variable

CADENZA_SESSION_TIMEOUT

Java system property

CADENZA_SESSION_TIMEOUT

Default value

15

Session Max Keep Alive Time

Time in minutes for http connection keep alive time.

Environment variable

CADENZA_MAXKEEPALIVEINTERVAL

Java system property

CADENZA_MAXKEEPALIVEINTERVAL

Default value

30

Available Main Memory

Max amount of main memory available to Cadenza Web. The default value chosen by the JVM is usually too low.

Environment variable

—

Java system property

mx<memory in MB or GB>

Default value

depends on available system memory

Examples

-Xmx2000M or -Xmx2G

User Interface Language

The ISO-639 alpha-2 or alpha-3 language code. Cadenza currently only supports "DE" and "EN".

Environment variable

—

Java system property

user.language=<language code>

Default value

current operating system language

Example

-Duser.language=de

User Interface Country

The ISO-3166 alpha-2 country code or UN M.49 numeric-3 area code. Cadenza currently only support "DE" and "US".

Environment variable

—

Java system property

user.country=<country code>

Default value

current operating system locale country

Example

-Duser.country=DE

Timezone

If you want to have timestamps that reflect your local timezone in the log files generated by Cadenza or other programs inside the container, then you need to set the timezone accordingly.

The format of the values of this parameter are TZ database names.

Environment variable

TZ

Java system property

 — 

Default value

defined by the operating system

Example

In Docker: -e TZ=Europe/Berlin

Clean Exit on Startup Errors

Cadenza can exit the java process when it encounters configuration or other errors that prevent it from starting. This has the advantage that the log output looks much more understandable to users as we log the startup errors and then cleanly exit. The downside of this option is that it terminates the entire Java process.

Terminating the Java process can be problematic if you run the Cadenza WAR file in a container with other applications. If you don’t or if you run Cadenza through our distribution or in a docker container then you can enable this setting and enjoy the improved log output.

Environment variable

CADENZA_EXIT_ON_STARTUP_ERROR

Java system property

CADENZA_EXIT_ON_STARTUP_ERROR

Default value

false

Changing the Cadenza Web Application Context Path (if relevant)

By default Cadenza is hosted under the context path /cadenza/, so if you installed Cadenza on a host that is reachable on example.com over HTTPS then your default main page for Cadenza would be https://example.com/cadenza/. You can change this context path to a different one with this system property.

Environment variable

 — 

Java system property

net.disy.cadenza.web.contextpath

Default value

cadenza

Security Settings, Cookie Options

It is possible to configure the following cookie flags for Cadenza Web. When embedding Cadenza in another application it may be required to set one or more of these flags.

Secure

The secure flag makes Tomcat only send session cookies over a secure (TLS) connection (except on localhost). The default value is false. The setting should only be enabled if Cadenza Web is solely reachable over HTTPS. In that case enabling the setting does increase security a little bit as it will prevent the session cookie from being sent over an insecure connection.

This flag is required when embedding Cadenza in another application across different origins. Since this requires the samesite attribute to be None and that in turns requires Secure to be set.

This flag can be configured by setting the System Property net.disy.cadenza.web.session.cookies.secure to true or false.

Environment variable

none

Java system property

net.disy.cadenza.web.session.cookies.secure

Default value

false

Example

-Dnet.disy.cadenza.web.session.cookies.secure=true

Samesite

The Samesite attribute for a cookie controls whether the cookie is restricted to the first party origin or whether it can be sent other domains.

This flag be set to None when Cadenza is embedded in another application using iframes and is available on different origin from the embedding application.

When the samesite attribute is set to None, then the Secure attribute must also be set to true.

This attribute can be configured by setting the System Property net.disy.cadenza.web.cookies.samesite.

The possible values are:

  • unset: In this case the attribute will not be set, this is the default. Browsers will typically handle cookies as if they are configured as Lax.

  • none: The attribute will be set and its value is None. Cookies will always be sent in cross site requests. This value is required when embedding Cadenza in another application using different origins.

  • lax: The attribute will be set to the value Lax. Means that the cookie is not sent on cross-site requests, such as on requests to load images or frames, but is sent when a user is navigating to the origin site from an external site (for example, when following a link).

  • strict: The attribute will be set and the browser prevents sending the cookie in any cross-site request. This setting is NOT recommended for Cadenza and may cause various features to break.

More information on the cookie options can be found in the Mozilla documentation.

Environment variable

none

Java system property

net.disy.cadenza.web.cookies.samesite

Default value

unset

Example

-Dnet.disy.cadenza.web.cookies.samesite=unset

Activating and Deactivating Plugins

This pair of options allows activating and deactivating plugins. Deactivation takes precedence over activation (if you specify the same plugin in both). This can be used to do something like disabling access management for a certain installation type.

Activating Plugins

This property takes a list of strings that are comma separated and represent the names of plugins to activate.

Environment variable

CADENZA_ACTIVATE_PLUGINS

Java system property

CADENZA_ACTIVATE_PLUGINS

Default value

 — 

Example

-DCADENZA_ACTIVATE_PLUGINS=Import_Office,AuditLogging

Deactivating Plugins

This property takes a list of strings that are comma separated and represent the names of plugins to deactivate.

Environment variable

CADENZA_DEACTIVATE_PLUGINS

Java system property

CADENZA_DEACTIVATE_PLUGINS

Default value

 — 

Example

-DCADENZA_DEACTIVATE_PLUGINS=Import_Office,AuditLogging