Externalized Configuration

You are viewing content for Planview Hub version .

This page is not applicable to Planview Hub Cloud.

Externalized Configuration

Planview Hub enables you to externalize configurations from Tomcat, Keycloak, and certain application properties in a single place. This allows you to use property files to override default values such as:

Keycloak: ports (e.g., https), Keycloak database paths, java memory variables, and custom system properties
Tomcat: ports (e.g., https), keystores (e.g., files, passwords, types), java memory variables, and custom system properties
Application Properties: Derby, Tasktop Hub, Liquibase, log4j, and keycloak host

To override default values through a properties file, you must provide the tasktop-hub.properties file in a directory that Hub can scan and read.

This can be done as follows:

Rename the file tasktop-hub.properties.default to tasktop-hub.properties.
1. For Windows, this file can be found in the App Data Directory.
2. For Linux, this file can be found in the root level of the .tar.gz package.
  1. Note: For Linux users, we recommend creating an environment variable named TASKTOP_HOME with its value pointing to an exclusive directory where the tasktop-hub.properties file will be placed.
Provide values to properties that need to be overridden.
1. For example, if you'd like to change the Tomcat https port to port 9443, uncomment the property from #server.port=8443 to server.port=9443

Good to Know:

Only properties/lines uncommented within the <AppDataDirectory>/tasktop-hub.properties file will be applied, otherwise Hub will assume default values for commented properties.
Only properties at <AppDataDirectory>/tasktop-hub.properties file will be used; the file <AppDataDirectory>/tasktop-hub.properties.default is just a template and will not work in Hub.
Keycloak properties prefixed with jboss have been deprecated. It is recommended to replace the prefix with keycloak. For example, jboss.https.portshould be changed to keycloak.https.port.

Upgrading

Upgrading on Windows

The tasktop-hub.properties file will not be replaced or deleted during the installation/upgrade process. For this reason, newer versions of Hub can retain settings automatically after upgrading.

Upgrading on Linux

Because the properties file is placed in the $TASKTOP_HOME directory, newer versions of Planview Hub will automatically apply all configurations.

If the properties file is not placed in the $TASKTOP_HOME directory, it is necessary to copy the properties file from the old installation directory to the new installation directory.

Upgrading from a Version Earlier than 20.4

If you have made manual changes to Tomcat and/or Jboss files, you have two options upon upgrading to 20.4:

1. You can apply all configurations that have been applied manually to server.xml, standalone.xml, standalone.conf, standalone.conf.bat, setenv.sh, and Manage Tasktop -> Java -> Java Options to the tasktop-hub.properties file .

During an upgrade, it is not necessary to override the server.xml file from the old version to the new installation directory. This can be done by simply providing the tasktop-hub.properties file in a directory that Hub is able to read and ensuring that there is an uncommented line as shown below:

...
server.port=9443
...

Other properties can be configured the same way as shown in the example above.

2. You can copy all configuration files from Tomcat and/or Jboss that were previously modified and override them in the new version directories.

Upgrading to Version 23.2 or Later

Manual customizations to Keycloak outside of tasktop-hub.properties are no longer supported. Please ensure that all Keycloak customizations are configured in tasktop-hub.properties.

Properties

The tasktop-hub.properties file contains three main blocks:

Keycloak Properties
Tomcat Properties
Planview Hub Properties

Keycloak

The properties listed in the table below are used only if Hub is using Keycloak as an Authentication Provider.

Note: Starting in 23.2, Keycloak runs on the Quarkus framework instead of the Jboss application server. This change led to the deprecation or renaming of certain properties as noted in the table.

Property	Purpose	Notes
`keycloak.https.port`	Use this property to select a custom HTTPS port for keycloak.	Formerly named `jboss.https.port`.
`keycloak.server.data.dir`	Use this property if you want to place the keycloak database in a custom directory.	This is the directory where the keycloak database lives. Formerly named `jboss.server.data.dir`. The name of the database file must not be changed (it should be `keycloak.h2.db`. For both Windows and Linux, the directory separator needs to be '/'.
`keycloak.java.memory`	Use this property to change memory settings.	We recommend setting the maximum Java heap size value to 50-75% of your system’s memory. Formerly named `jboss.java.memory`.
`keycloak.custom.system.properties`	Use this property to load custom system properties. For example: `-keycloak.*=value, -Dkey=value, -XX:key=value, -javaagent:value, -agentlib:value`	Formerly named `jboss.custom.system.properties`.
`keycloak.custom.auth-server-url`	Use this property to override the default authentication server URL detection	This is only needed in rare scenarios with proxies or load balancers where Planview Hub is unable to determine the externally accessible URL for Keycloak. It is recommended to host Hub and Keycloak on the same machine and restrict access to Keycloak via firewall.

Tomcat

The properties listed in the table below are used to override some properties from Tomcat

Property	Purpose	Notes
`server.port`	Use this property to provide a value for the attribute port in the tag `<Connector/>` within the `server.xml` descriptor.	After changing the port, if Keycloak is being used, you will need to go into the User Administration Console and adjust the client to the new port.
`server.redirect.port`	Use this property to provide a value for the attribute redirectPort in the tag `<Connector/>` within the `server.xml` descriptor.
`server.shutdown.port`	Use this property to provide a value for the attribute port in the tag `<Server/>` within the `server.xml` descriptor.
`server.tomcat.connection-timeout`	Use this property to provide a value for the attribute connectionTimeout in the tag `<Connector/>` within the `server.xml` descriptor.
`server.ssl.key-store=/path/to/keystore-file`	Use this property to provide a value for the attribute keystoreFile in the tag `<Connector/>` within the `server.xml` descriptor.	This property is shared with Keycloak.
`server.ssl.key-store-password=changeit`	Use this property to provide a value for the attribute `keystorePass` in the tag `<Connector/>` within the `server.xml` descriptor.	This property is shared with Keycloak.
`server.ssl.key-store-type=JKS`	Use this property to provide a value for the attribute `keystoreType` in the tag `<Connector/>` within the `server.xml` descriptor.
`server.ssl.key-alias`	Use this property to provide a value for the attribute `keyAlias` in the tag `<Connector/>` within the `server.xml` descriptor.	Enable this property only if your custom Keystore has an alias and it is different than Tomcat.
`tomcat.java.memory=-Xms256M -Xmx2118M`	Use this property to change memory settings.	We recommend setting the maximum Java heap size value to 50-75% of your system’s memory. For Windows: Initial memory pool size (-Xms) and maximum memory pool size (-Xmx) needs to be in MB. That means that the value needs to be suffixed with 'M'. Values suffixed with 'G' will cause an error at the start of Hub. For Linux: Values can be specified in MB or GB. Both suffixes 'M' and 'G' work.
`tomcat.java.errorFile=/path/to/hs_err_pid%%p.log`	Use this property to provide a custom path for -`XX:ErrorFile`.
`tomcat.java.io.tmpdir=path/to/temp`	Use this property to provide a custom path for `java.io.tmpdir` directory.
`tomcat.java.util.logging.config.file=path/to/logging.properties`	Use this property to provide a custom path for Tomcat’s `logging.properties` file.
`tomcat.jdk.tls.rejectClientInitiatedRenegotiation=true`	Use this property to provide `jdk.tls.rejectClientInitiatedRenegotiation` value.
`tomcat.custom.system.properties`	Use this property to load custom system properties such as: `-XX:key=value, -javaagent:value, -agentlib:value`

Tasktop Hub

The properties listed in the table below are used to override some Hub values.

Property	Purpose	Notes
`derby.storage.pageCacheSize`	Use this property to change the data page cache in the database.	Reference
`derby.system.home=/path/to/db`	Use this property to provide a custom path to the Derby database directory.	Providing the Derby database directory is useful for Linux environments when upgrading, as you do not need to copy files from the old installation directory to the new installation directory.
`hub.database.configuration.directory=/path/to/db`	Use this property to provide a custom path to the Derby database.
`liquibase.ignoreRecycleBinWarning=true`	Use this property to whether or not suppress liquibase warnings.
`log4j.configuration=file:/path/to/log4j2.xml`	Use this property to provide a custom path to the `log4j2.xml` file.
`log4j.configuration.verbose=file:/path/to/log4j2-troubleshooting.xml`	Use this property to provide a custom path to the`log4j2-troubleshooting.xml` file.
`hub.security.cors.exclusionPaths`	Use this property to provide a list of paths that will be excluded from the CORS verification. For example: `/first-path,/second-path`	Prior to version 21.1, this property was configured in `/tasktop/container/webapps/root/WEB-INF/web.xml`

Good to Know

Properties must be modified in the tasktop-hub.properties file as this file has more priority than properties modified in Manage Tasktop > Java > Java Options | Initial memory pool | Maximum memory pool.

Linux

It is possible to use environment variables to compound a specific value. As an example, it is possible to use $CATALINA_BASE to compound a path.

hub.database.configuration.directory=$CATALINA_BASE/../../directory
log4j.configuration.verbose=file:$CATALINA_BASE/../../log4j2-troubleshooting.xml