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.
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:
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:
Note as you populate necessary values in application.properties, you may need to remove the leading # to uncomment lines you need to activate.
The application properties in this section were previously defined in your <CONFIG_FILE>, i.e. "ROOT.xml", "labkey.xml", or similar.
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.
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:
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.
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.
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@@
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 you needed to set in the Context tag of your config file is no longer required.
The settings in this section were previously defined in your "server.xml" or "web.xml" files, located in <CATALINA_HOME>/conf.
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.
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
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
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:
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
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 '"'. For example, instead of "%r", your pattern would have included "r". When moving your pattern to the application properties file, replace any '"' with double quotes, as shown in the example.
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
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.
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:
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
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
| previousnext |
| expand allcollapse all |
