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> is 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 Logging Configuration (Log4j2.xml)
• Extra Webapps
• Content Security Policy
• 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

In the application.properties template included with your distribution, there are 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

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

@@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

If you were using HTTPS, set the HTTPS port previously in use (typically 443 or 8443). If you were only using HTTP, set that port instead (typically 80 or 8080):

server.port=443

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 Logging Configuration (Log4j2.xml)

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

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

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