This topic is under construction for the 24.11 (November 2024) release. For the previous documentation of this feature, click here.

This topic covers using the application.properties file to configure LabKey Server using embedded Tomcat. If you are upgrading from a prior version, a detailed guide for migrating from prior configuration methods is provided here:

If you are installing LabKey Server for the first time, this topic will help you customize the application.properties file.

Basic Configuration Covered in this Topic: Start Here

Topics Covering Other Features Included in application.properties

Other Configuration Options

Customize application.properties File

Your distribution includes an application.properties file which must be customized with values appropriate to your installation and desired server configuration.

Comments:

Comments in the file itself are your best resource for populating it. Be aware that a leading # means a line is commented out and won't be applied.

Replace Placeholders:

As you provide the necessary values in this file, look for @@ markers, i.e: @@replaceme@@. This style marks some items to replace, such as the location of your KeyStore. Replace the entire string including the @@ delimiters.

Note that in earlier versions of the template, there were different ways that a value you need to be provide might be called out:

  • <replaceme>: This style marks other items where you should supply your own values, such as the username and password for accessing external data sources.
  • /fake/path/to/something: Use the actual path.
Format Values Correctly:

General ".properties" formatting expectations apply.

Templates:

You can find generic templates for this file in the public GitHub repository here:

Primary Database Settings

All deployments need a labkeyDataSource as their primary database. Complete these lines at a minimum, and customize any other properties listed in the template as needed:

PropertyDescription
context.resources.jdbc.labkeyDataSource.driverClassNameDatabase driverClassName
(org.postgresql.Driver for Postgres
com.microsoft.sqlserver.jdbc.SQLServerDriver for SQLServer)
context.resources.jdbc.labkeyDataSource.urlDatabase URL
context.resources.jdbc.labkeyDataSource.usernameDatabase Username
context.resources.jdbc.labkeyDataSource.passwordDatabase Password

The default template, assuming a PostgreSQL database, looks like:

context.resources.jdbc.labkeyDataSource.type=javax.sql.DataSource
context.resources.jdbc.labkeyDataSource.driverClassName=org.postgresql.Driver
context.resources.jdbc.labkeyDataSource.url=jdbc:postgresql://localhost:5432/labkey
context.resources.jdbc.labkeyDataSource.username=<username>
context.resources.jdbc.labkeyDataSource.password=<password>
context.resources.jdbc.labkeyDataSource.maxTotal=50
context.resources.jdbc.labkeyDataSource.maxIdle=10
context.resources.jdbc.labkeyDataSource.maxWaitMillis=120000
context.resources.jdbc.labkeyDataSource.accessToUnderlyingConnectionAllowed=true
context.resources.jdbc.labkeyDataSource.validationQuery=SELECT 1
#context.resources.jdbc.labkeyDataSource.logQueries=true
#context.resources.jdbc.labkeyDataSource.displayName=Alternate Display Name

Notes:

  • The connection pool size (maxTotal) of 50 is a default recommendation. Learn more about pool sizes in this topic: Troubleshoot Installation and Configuration
  • The maxWaitMillis parameter is provided to prevent server deadlocks. Waiting threads will time out when no connections are available rather than hang the server indefinitely.

Encryption Key

LabKey Server can be configured to authenticate and connect to external systems to retrieve data or initiate analyses. In these cases, LabKey must store credentials (user names and passwords) in the primary LabKey database. While your database should be accessible only to authorized users, as an additional precaution, LabKey encrypts these credentials before storing them and decrypts them just before use. This encryption/decryption process uses an "encryption key" that administrations set in the application.properties file. LabKey will refuse to save credentials if an encryption key is not configured and the administrator will see a warning banner.

context.encryptionKey=<encryptionKey>

The encryption key should be a randomly generated, strong password, for example, a string of 32 random ASCII characters or 64 random hexadecimal digits. Once a key is specified and used, the server will use it to encrypt/decrypt credentials; changing it will cause these credentials not to decrypt correctly. Different LabKey Server deployments should use different encryption keys, however, servers that use copies of the same database (for example, most test, staging, and production server combinations) need to use the same encryption key.

The encryption key is validated at every LabKey Server startup. If LabKey determines that the encryption key has changed then a warning is shown with additional detail and recommendations.

Premium Feature Available

Administrators of servers running a premium edition of LabKey Server can later change the encryption key following the guidance in this topic:


Learn more about premium editions

GUID

LabKey Servers may communicate any generated exceptions back to LabKey for analysis, using the server GUID as identification. If you are running a different server on a clone of another server's database, such as when using a staging server, you can override the GUID stored in the database with a new one. This ensures that the exception reports sent to LabKey Server developers are accurately attributed to the server (staging vs. production) that produced the errors.

To set a custom GUID, uncomment this property and provide your GUID:

#context.serverGUID=

SSL and Port Settings (HTTP and HTTPS)

If you are using TLS/SSL, i.e. configuring for HTTPS, provide values for the properties in the ssl section. Learn more and see specific recommendations for property settings in this topic:

If you are not using SSL, just set the port. It could be 80, 8080, or something unique to the current server:
server.port=8080

For servers that need 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 the default of 30 minutes, uncomment this line to make it active and set the desired timeout:

server.servlet.session.timeout=30m

Learn more about options here: SpringBoot Common Application Properties

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

Content-Security-Policy HTTP headers are a powerful security tool, successor to several previous mechanisms such as X-Frame-Option and X-XSS-Protection. To set one, include it in the application.properties file.

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

csp.report=
and
csp.enforce=

CORS Filters (Uncommon)

To use CORS filtering, set one or more of the following properties as needed to support your configuration:

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
server.tomcat.cors.urlPattern

More Tomcat Settings (Uncommon)

Additional Tomcat configuration settings you may be interested in have defaults as shown in the table below. You do not need to set any of these properties to use the default. If you want to change the behavior, set to the other boolean value.

PropertyDefault
server.tomcat.useSendfiletrue
server.tomcat.disableUploadTimeoutfalse
server.tomcat.useBodyEncodingForURIfalse

Related Topics

Was this content helpful?

Log in or register an account to provide feedback


previousnext
 
expand allcollapse all