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 working directory>/config

Headless Mode

Cadenza Web uses parts of the Java AWT Library to render images in the map, therefore the Java VM must not run in "Headless" mode as that would disable the AWT API.

This property must always be set to false.

Environment variable

none

Java system property

java.awt.headless

Default value

none

Example

-Djava.awt.headless=false

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 working directory>/WEB-INF/classes/log4j2.xml

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 working directory>

Session Timeout

Time in minutes for session timeout.

Environment variable

CADENZA_SESSION_TIMEOUT

Java system property

CADENZA_SESSION_TIMEOUT

Default value

<Cadenza working directory>

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

<Cadenza working directory>

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,Permalink

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,Permalink