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:

• Migrate Configuration to Application Properties

Basic Configuration Covered in this Topic: Start Here

• Customize application.properties File
• Primary Database Settings
• Encryption Key
• GUID
• SSL and Port Settings (HTTP and HTTPS)
• Session Timeout
• Content Security Policy

Topics Covering Other Features Included in application.properties

• Configure Site Access Logs (Recommended)
• SMTP Mail Settings
• External Data Sources

Other Configuration Options

• Service File Customizations: Configure Webapp Memory, and more.

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

General ".properties" formatting expectations apply, such as escaping of backslashes for Windows file paths (e.g. C:\\labkey\\labkey)

Templates:

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

• Generic version of application.properties
• Development and test version of application.properties

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:

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.

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:

• Use HTTPS with LabKey

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

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=

Related Topics

• Migrate Configuration to Application Properties
• Install on Linux
• Install on Windows
• Service File Customizations