This topic covers using the 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 file.

Basic Configuration Covered in this Topic: Start Here

Topics Covering Other Features Included in

Other Configuration Options

Customize File

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


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 there are different ways that a value you need to be provide might be called out:

  • @@replaceme@@: This style marks some items to replace, such as the location of your KeyStore. Replace the entire string including the @@ delimiters.
  • <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, such as escaping of backslashes for Windows file paths (e.g. C:\\labkey\\labkey)


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:

context.resources.jdbc.labkeyDataSource.driverClassNameDatabase driverClassName
(org.postgresql.Driver for Postgres 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.validationQuery=SELECT 1
#context.resources.jdbc.labkeyDataSource.displayName=Alternate Display Name


  • 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 file. LabKey will refuse to save credentials if an encryption key is not configured and the administrator will see a warning banner.


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


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:


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:

should not list this as a standard config option per Trey management.server.port | Server port deemphasized per Josh server.ssl.ciphers | A list of the SSL ciphers that you're currently using, converted from command/newline-delimited to colon-delimited server.ssl.protocol | A list of the SSL protocols that are currently enabled

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


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:


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:


Learn more about options here: SpringBoot Common Application Properties

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

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

Related Topics

Was this content helpful?

Log in or register an account to provide feedback

expand allcollapse all