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> 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
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.
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
Replace necessary placeholders (removing any the bracketing "@@" 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.
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
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:
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 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 "myMSsqlDataSource" included these lines:
<Resource name="jdbc/myMSsqlDataSource" 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.myMSsqlDataSource.driverClassName=com.microsoft.sqlserver.jdbc.SQLServerDriver
context.resources.jdbc.myMSsqlDataSource.url=jdbc:sqlserver://SERVER_NAME:1433;databaseName=DATABASE_NAME;trustServerCertificate=true;applicationName=LabKey Server;
context.resources.jdbc.myMSsqlDataSource.username=mssqlUSERNAME
context.resources.jdbc.myMSsqlDataSource.password=mssqlPASSWORD
Add an additional set of these lines for each external data source in the <CONFIG_FILE>.
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:
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.
SSL and Port Settings
If you were using SSL, migrate any of the properties below that you have been using from your "server.xml" file. Not all properties are required. Learn more about SpringBoot's port configuration options
here .
Example settings are included in the commented out lines provided in the application.properties template. Be sure to uncomment the lines you use in your configuration:
#server.ssl.enabled=true
#server.ssl.enabled-protocols=TLSv1.3,TLSv1.2,TLSv1.1
#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:!ADH:!EXP:!SSLv2:!SSLv3:!MEDIUM:!LOW:!NULL:!aNULL
@@keyStore@@ should be replaced with a full path including name of the key-store-file, which was likely originally under <CATALINA_HOME>. In the upgrade instructions for any platform, we direct you to move it it to <LABKEY_HOME>/SSL, so that is the full path to provide in the application.properties.
If you were
not using SSL, set the port previously in use. It could be 80, 8080, or something unique to the current server:
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 when SSL is in use. 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:
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, you need to move the custom version to a new location. Otherwise it 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=SSLv3
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