Migrate Configuration to Application Properties


This topic is specifically for users upgrading to version 24.3 of LabKey Server, using an embedded installation of Tomcat for the first time. If you are installing LabKey Server for the first time, learn about setting application.properties in this topic:

In previous releases, 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

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.
  • server.xml and web.xml: These are located under <CATALINA_HOME>/conf.
As a general best practice, review these older files side by side with the new application.properties to make it easier to selectively migrate necessary settings and values. Note that if you were not using a particular setting previously, you do not need to add it now, even if it appears in our defaults.

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
Replace necessary placeholders (removing any bracketing characters like "@@" or "<>") with the correct values for your unique installation. Note also that in some previous configuration settings, values were surrounded by double quotes, which are not used in the application.properties file. General ".properties" formatting expectations apply, such as escaping of backslashes for Windows file paths (e.g. C:\\labkey\\labkey).

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):


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

<Resource name="jdbc/labkeyDataSource" auth="Container" type="javax.sql.DataSource"

This section in the application.properties file would be:


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

If you have been using Microsoft SQL Server as your primary database with the jTDS driver (i.e. a driverClassName of "net.sourceforge.jtds.jdbc.Driver"), you will need to perform intermediate LabKey version upgrades prior to upgrading to 24.3. Learn more about switching drivers here.

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.


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:


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

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:


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:


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

<Resource name="jdbc/anotherMsSqlDataSource" auth="Container" type="javax.sql.DataSource"
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.url=jdbc:sqlserver://SERVER_NAME:1433;databaseName=DATABASE_NAME;trustServerCertificate=true;applicationName=LabKey Server;

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.

If you have been using Microsoft SQL Server as an external data source with the jTDS driver (i.e. a driverClassName of "net.sourceforge.jtds.jdbc.Driver"), you will need to perform intermediate LabKey version upgrades prior to upgrading to 24.3. Learn more about switching drivers here.

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:



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


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).


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:


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:

## Typically either PKCS12 or JKS

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:


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:


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:


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:


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

Custom 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

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.pattern=%h %l %u %t "%r" %s %b %D %S %I "%{Referrer}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:


Content Security Policy

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


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:

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:


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:


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.description=JMS Connection Factory

Related Topics

Was this content helpful?

Log in or register an account to provide feedback

expand allcollapse all