In releases prior to 24.3, the LabKey Server configuration file contained settings required for LabKey Server to run on Tomcat, including SMTP, Encryption, LDAP, and file roots. Typically this <CONFIG_FILE> was named "ROOT.xml", "labkey.xml", or it could have another name. In addition, settings in the Tomcat "server.xml" and "web.xml" file controlled other parts of the Tomcat configuration. This topic provides guidance to help you migrate from this older way of configuring a standalone Tomcat installation to the new embedded distribution system which uses an application.properties file for most configuration details.

• Locate Prior Configuration Details
• Translate <CONFIG_FILE> Settings:
• Primary Database (labkeyDataSource) Settings
• Encryption Key
• Context Path Redirect
• External Data Sources (If needed)
• SMTP Mail Server Settings (If using SMTP)
• GUID
• The docBase Attribute
• Translate Tomcat Settings (server.xml and web.xml)
• HTTPS and Port Settings
• Respond to Both HTTP and HTTPS Requests
• Session Timeout
• Custom Header Size Settings (Uncommon)
• CORS Filters (Uncommon)
• More Tomcat Settings (Uncommon)
• Custom Logging Configuration (Log4j2.xml) (Uncommon)
• Custom Tomcat Access Log Pattern (Uncommon)
• Extra Webapps
• Content Security Policy
• SAML Authentication (Premium Feature)
• LDAP Synchronization (Premium Feature)
• JMS Queue (If using ActiveMQ)

Locate Prior Configuration Details

Your prior installation of standalone Tomcat 9 can be in a variety of locations on your machine. We use the shorthand <CATALINA_HOME> for that location. Under that top level, you'll find key configuration files:

• <CONFIG_FILE>: This is usually named "ROOT.xml" or "labkey.xml" and is located under <CATALINA_HOME>/conf/Catalina/localhost.
• Settings to migrate from this file are described in the Translate <CONFIG_FILE> Settings section below.
• server.xml and web.xml: These are located under <CATALINA_HOME>/conf.
• Settings to migrate from these files are described in the Translate Tomcat Settings section below.

The application.properties File

Beginning with 24.3.4, the application.properties template included with your distribution shows values to be substituted bracketed with "@@", i.e. @@jdbcPassword@@. Replace the entire placeholder, including the @@s, with the value for your system.

In previous versions of 24.3, the application.properties template used several indicators of values to be substituted with your own:

• Placeholders highlighted with "@@", i.e. @@jdbcPassword@@, as used in the prior <CONFIG_FILE>
• Bracketed values like <placeholder>
• Fictional /paths/that/should/be/provided

Note as you populate necessary values in application.properties, you may need to remove the leading # to uncomment lines you need to activate.

Translate <CONFIG_FILE> Settings

The application properties in this section were previously defined in your <CONFIG_FILE>, i.e. "ROOT.xml", "labkey.xml", or similar.

Primary Database (labkeyDataSource) Settings

All deployments need a labkeyDataSource as their primary database. In the application.properties file, complete these lines, taking the values highlighted with "@@" before and after from your previous configuration file(s):

context.resources.jdbc.labkeyDataSource.driverClassName=@@jdbcDriverClassName@@
context.resources.jdbc.labkeyDataSource.url=@@jdbcURL@@
context.resources.jdbc.labkeyDataSource.username=@@jdbcUser@@
context.resources.jdbc.labkeyDataSource.password=@@jdbcPassword@@

For example, if your <CONFIG_FILE> settings included a <Resource> tag like:

<Resource name="jdbc/labkeyDataSource" auth="Container" type="javax.sql.DataSource"
        username="postgres"
        password="WHATEVER_THE_PASSWORD_IS"
        driverClassName="org.postgresql.Driver"
        url="jdbc:postgresql://localhost:5433/labkey162"
...

This section in the application.properties file would be:

context.resources.jdbc.labkeyDataSource.driverClassName=org.postgresql.Driver
context.resources.jdbc.labkeyDataSource.url=jdbc:postgresql://localhost:5433/labkey162
context.resources.jdbc.labkeyDataSource.username=postgres
context.resources.jdbc.labkeyDataSource.password=WHATEVER_THE_PASSWORD_IS

Additional properties available are listed in the application.properties file and can also be customized as needed for the primary data source.

Encryption Key

As you are upgrading, if you had previously set an encryption key, you must provide the same key, otherwise the upgrade will be unable to decrypt the database.

context.encryptionKey=VALUE_OF_PRIOR_ENCRYPTION_KEY

If you are upgrading and had not previously set a key, set one now by providing a key for this property instead of the <encryptionKey> placeholder:

context.encryptionKey=<encryptionKey>

Premium Feature: With a Premium Edition of LabKey Server, administrators can change the encryption key as described in this topic:

• Premium Resource: Change the Encryption Key

Context Path Redirect

The name of the <CONFIG_FILE> determined whether there was a context path in the URL in your previous version. Beginning with version 24.3, the application will be deployed at the root and no context path will be necessary.

If your previous <CONFIG_FILE> was named "ROOT.xml", the application was deployed in the root already and you can skip this section.

If the config file was named anything else, such as "labkey.xml", you will want to include a legacyContextPath so that any URLs or API calls using that context path will be redirected to the root context and continue to work. As a common example, if the file was named "labkey.xml", include this in your application.properties:

context.legacyContextPath=/labkey

Note: Do not set the contextPath property, which is also present, and commented out in the application.properties file.

External Data Sources (If needed)

If your <CONFIG_FILE> does not include any additional data sources, you can skip this section.

If you do have additional data sources, you will create (and uncomment) a new set of these lines for each external data source resource tag you included previously, substituting the unique name for the data source where you see "@@extraJdbcDataSource@@" in the property name:

#context.resources.jdbc.@@extraJdbcDataSource@@.driverClassName=@@extraJdbcDriverClassName@@
#context.resources.jdbc.@@extraJdbcDataSource@@.url=@@extraJdbcUrl@@
#context.resources.jdbc.@@extraJdbcDataSource@@.username=@@extraJdbcUsername@@
#context.resources.jdbc.@@extraJdbcDataSource@@.password=@@extraJdbcPassword@@

For example, if your <CONFIG_FILE> Resource for "anotherMsSqlDataSource" included these lines:

<Resource name="jdbc/anotherMsSqlDataSource" auth="Container" type="javax.sql.DataSource"
  username="mssqlUSERNAME"
  password="mssqlPASSWORD"
  driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
url="jdbc:sqlserver://SERVER_NAME:1433;databaseName=DATABASE_NAME;trustServerCertificate=true;applicationName=LabKey Server;"

You would include these lines for this data source, noting the customization of the property name as well as copying the value over:

context.resources.jdbc.anotherMsSqlDataSource.driverClassName=com.microsoft.sqlserver.jdbc.SQLServerDriver
context.resources.jdbc.anotherMsSqlDataSource.url=jdbc:sqlserver://SERVER_NAME:1433;databaseName=DATABASE_NAME;trustServerCertificate=true;applicationName=LabKey Server;
context.resources.jdbc.anotherMsSqlDataSource.username=mssqlUSERNAME
context.resources.jdbc.anotherMsSqlDataSource.password=mssqlPASSWORD

Add an additional set of these lines for each external data source in the <CONFIG_FILE>. The additional properties available for the primary data source can also be set for any external data source following the same pattern of customizing the property name with the data source name.

SMTP Mail Server Settings

If you were not using an SMTP mail server to send messages from the system, you can skip this section.

If you were using SMTP, in your <CONFIG_FILE> transfer the corresponding values to these application.properties, uncommenting any lines you require:

mail.smtpHost=@@smtpHost@@
mail.smtpPort=@@smtpPort@@
mail.smtpUser=@@smtpUser@@
#mail.smtpFrom=@@smtpFrom@@
#mail.smtpPassword=@@smtpPassword@@
#mail.smtpStartTlsEnable=@@smtpStartTlsEnable@@
#mail.smtpSocketFactoryClass=@@smtpSocketFactoryClass@@
#mail.smtpAuth=@@smtpAuth@@

GUID

If your <CONFIG_FILE> includes a custom GUID, you can maintain it by uncommenting this property and setting it to your GUID:

context.serverGUID=

The docBase Attribute

The docBase attribute you needed to set in the Context tag of your config file is no longer required.

Translate Tomcat Settings (server.xml and web.xml)

The settings in this section were previously defined in your "server.xml" or "web.xml" files, located in <CATALINA_HOME>/conf.

HTTPS and Port Settings

If you were using HTTPS, set the HTTPS port previously in use (typically 443 or 8443).

server.port=443

If you were not using SSL, i.e. only using HTTP, set the port you were using previously (typically 80 or 8080), then skip the rest of this section, leaving the ssl settings commented out:

server.port=8080

If you were using HTTPS (SSL/TLS), migrate any of the properties below that you have been using from your "server.xml" file. Not all properties are required. Learn more about Spring Boot's port configuration options here .

Example settings are included in the commented out lines provided in the application.properties template which may evolve over time. Be sure to uncomment the lines you use in your configuration:

#server.ssl.enabled=true
#server.ssl.enabled-protocols=TLSv1.3,TLSv1.2
#server.ssl.protocol=TLS
#server.ssl.key-alias=tomcat
#server.ssl.key-store=@@keyStore@@
#server.ssl.key-store-password=@@keyStorePassword@@
## Typically either PKCS12 or JKS
#server.ssl.key-store-type=PKCS12
#server.ssl.ciphers=HIGH:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!kRSA:!EDH:!DHE:!DH:!CAMELLIA:!ARIA:!AESCCM:!SHA:!CHACHA20

Note that you only need to use a key-alias if your previous server.xml configuration file used an alias. If you did not use an alias, leave this line commented out.

@@keyStore@@ must be replaced with the full path including name of the key-store-file, which is now in this location: <LABKEY_HOME>/SSL. Provide that as the full path for server.ssl.key-store. Note that this path uses forward slashes, even on Windows.

We recommend that you use this set of ciphers:

server.ssl.ciphers=HIGH:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!kRSA:!EDH:!DHE:!DH:!CAMELLIA:!ARIA:!AESCCM:!SHA:!CHACHA20

On Linux, 443 is a privileged port, so you may also need to grant access to it in the service file.

Respond to Both HTTP and HTTPS Requests

We leverage Spring Boot’s regular config for the primary server port, which can be either HTTP or HTTPS. If your server needs to respond to both HTTP and HTTPS requests, an additional property enables a separate HTTP port. Uncomment this line to enable responses to both HTTP and HTTPS requests:

context.httpPort=80

Session Timeout

If you need to adjust the HTTP session timeout from Tomcat's default of 30 minutes, you would previously have edited the <CATALINA_HOME>/conf/web.xml, separate from the LabKey webapp. Now you will need to migrate that setting into application.properties, uncommenting this line to make it active and setting the desired timeout:

server.servlet.session.timeout=30m

Learn more about options here: SpringBoot Common Application Properties

Custom Header Size Settings (Uncommon)

If you were previously increasing the default Tomcat header size (or request header size) by customizing either or both of these properties in your server.xml file:

<Connector port="8080" maxHttpHeaderSize="65536" maxHttpRequestHeaderSize="65536"...

You will now set the same values in the application.properties file by adding:

server.max-http-request-header-size=65536

Note that this is not a commonly needed property setting. Learn more about when it could be required in this topic:

• Increase GET Header and Request Header Limits

CORS Filters (Uncommon)

If you were using CORS filters in your web.xml, set one or more of the following properties as needed to support your configuration. These properties would have been in the <filter> definition itself:

server.tomcat.cors.allowedOrigins
server.tomcat.cors.allowedMethods
server.tomcat.cors.allowedHeaders
server.tomcat.cors.exposedHeaders
server.tomcat.cors.supportCredentials
server.tomcat.cors.preflightMaxAge
server.tomcat.cors.requestDecorate

If you had a <filter-mapping> section for those filters defining a <url-pattern>, provide it here:

server.tomcat.cors.urlPattern

Any of the above being set will register a CorsFilter.

More Tomcat Settings (Uncommon)

Additional settings you may have had in your web.xml include the following to override various Tomcat defaults. If you are using one of these, use the corresponding property in the new configuration:

Custom Log4j Logging Configuration (Log4j2.xml) (Uncommon)

If you had previously customized the log4j2.xml file at <LABKEY_HOME>/labkeywebapp/WEB-INF/classes/log4j2.xml, contact your Account Manager to determine whether the customizations are still necessary and if so, how this file may need to change. Customizing this file is not recommended if it can be avoided, as with each future upgrade, you may need to continue to make changes.

At a minimum, any custom version would need to be in a new location such as under <LK_ROOT>/apps (i.e. /labkey/apps/log4j2.xml). The <LABKEY_HOME>/labkeywebapp location will be overwritten during upgrades.

Provide the path to the new location in the application.properties file as follows:

## Use a custom logging configuration
logging.config=/another/path/to/log4j2.xml

Custom Tomcat Access Log Pattern (Uncommon)

If you were previously enabling and using a different pattern for the Tomcat access log, you may need to uncomment and update the pattern in these lines:

## Enable tomcat access log
#server.tomcat.accesslog.enabled=true
#server.tomcat.accesslog.pattern=%h %l %u %t "%r" %s %b %D %S %I "%{Referer}i" "%{User-Agent}i" %{LABKEY.username}s

Note that previously your custom pattern may have needed any double quotes (") to be replaced with '&quot;'. For example, instead of "%r", your pattern would have included &quot;r&quot;. When moving your pattern to the application properties file, replace any '&quot;' with double quotes, as shown in the example.

Extra Webapps

If you deploy other webapps, most commonly to deliver a set of static files, you will provide a context path to deploy into as the property name after the "context.additionalWebapps." prefix, and the value is the location of the webapp on disk in these properties:

context.additionalWebapps.firstContextPath=/my/webapp/path
context.additionalWebapps.secondContextPath=/my/other/webapp/path

Content Security Policy

The application.properties template example for development/test servers includes several example values for:

csp.report=
and
csp.enforce=

Jump directly to the relevant section here.

SAML Authentication (Premium Feature)

If you are using SAML authentication, and were previously using a config file named "ROOT.xml", the ACS URL is unchanged and your configuration will continue to work as before.

If you are using SAML and were previously using a config file named "labkey.xml", you will now be deploying at the root, the ACS URL will no longer include the "labkey" context path. You will need to edit the configuration on your SAML Identity Provider to update the ACS URL to be the same as that shown in the LabKey UI for your SAML authentication configuration.

Learn more in this topic:

• Configure SAML Authentication

LDAP Synchronization (Premium Feature)

If you are using LDAP Synchronization with an external server, these settings must be included, the first two referencing the premium module:

context.resources.ldap.ConfigFactory.type=org.labkey.premium.ldap.LdapConnectionConfigFactory
context.resources.ldap.ConfigFactory.factory=org.labkey.premium.ldap.LdapConnectionConfigFactory
context.resources.ldap.ConfigFactory.host=ldap.forumsys.com
context.resources.ldap.ConfigFactory.port=389
context.resources.ldap.ConfigFactory.principal=cn=read-only-admin,dc=example,dc=com
context.resources.ldap.ConfigFactory.credentials=password
context.resources.ldap.ConfigFactory.useTls=false
context.resources.ldap.ConfigFactory.useSsl=false
context.resources.ldap.ConfigFactory.sslProtocol=TLS

If you are using the OpenLdapSync module, all properties and values match the above list, except use the following value for both the type and factory properties:

org.labkey.ldk.ldap.LdapConnectionConfigFactory

JMS Queue (If using ActiveMQ)

If you are using an ActiveMQ JMS Queue configuration with your pipeline, you also need these lines in your application.properties file. Find the required values in your previous <CONFIG_FILE>:

context.resources.jms.ConnectionFactory.type=org.apache.activemq.ActiveMQConnectionFactory
context.resources.jms.ConnectionFactory.factory=org.apache.activemq.jndi.JNDIReferenceFactory
context.resources.jms.ConnectionFactory.description=JMS Connection Factory
context.resources.jms.ConnectionFactory.brokerURL=vm://localhost?broker.persistent=false&broker.useJmx=false
context.resources.jms.ConnectionFactory.brokerName=LocalActiveMQBroker

Related Topics

• Upgrade on Linux
• Upgrade on Windows
• Set Application Properties
• Service File Customizations
• Troubleshoot Installation and Configuration