The LabKey Server configuration file contains settings required for LabKey Server to run on Tomcat, including SMTP, Encryption, LDAP, and file roots. By default, it is named labkey.xml, but it may also be ROOT.xml This topic describes enhancements and extensions of the server that involve modifications to labkey.xml.
After editing the configuration file, make sure to pick up the changes by running "gradle pickMSSQL" or "gradle pickPg" as appropriate for your database.

Configuration File Name Determines Context Path

The name of the configuration file determines what the context path in the URL will be. The context path is a variable part of the URL between the server name and the project and folder path. For example, if you name the file "labkey.xml" you will access the home project with a URL like:

If you name the file "ROOT.xml", the context path is omitted (or a "/" which will be ignored), i.e. you'd access the same home project using:

Learn more about the context path in this topic: LabKey URLs

Securing the LabKey Configuration File

The LabKey configuration file contains user name and password information for your database server, mail server, and network share. For this reason you should secure this file within the file system, so that only designated network administrators can view or change this file.

Modifying Configuration File Settings

You can edit the configuration file with your favorite text or XML editor. You will need to modify the LabKey Server configuration file if you are manually installing or upgrading LabKey Server, or if you want to change any of the following settings.

  • The docBase attribute, which indicates the location of the web application in the file system
  • Database settings, including server type, server location, username, and password for the database superuser.
  • SMTP settings, for specifying the mail server LabKey Server should use to send email to users.
  • Encryption Key - Configure an encryption key for the encrypted property set.
Note that in our template labkey.xml file, the placeholder values for these settings are highlighted with "@@", i.e "@@jdbcPassword@@", to make them easier to find in the file. Replace the full placeholder (including the bracketing "@@") with the correct password. The final result should resemble:

<?xml version='1.0' encoding='utf-8'?>
<Context docBase="C:\\labkey\\labkey\\labkeyWebapp" reloadable="true" crossContext="true">
<Resource name="
jdbc/labkeyDataSource" auth="Container"

The docBase Attribute

The docBase attribute of the Context tag must be set to point to the directory where you have extracted or copied the labkeywebapp directory. For example, if the directory where you've copied labkeywebapp is /usr/local/labkey/labkey, you would change the initial value to "/usr/local/labkey/labkey/labkeywebapp".

Database Settings

The username and password attributes must be set to a user name and password with admin rights on your database server. Both the name and password attribute are found in the Resource tag named "jdbc/labkeyDataSource". If you are running a local version of PostgreSQL as your database server, you don't need to make any other changes to the database settings in labkey.xml, since PostgreSQL is the default database choice.

The following is a template resource tag for PostgreSQL:

<Resource name="jdbc/labkeyDataSource" auth="Container"
validationQuery="SELECT 1"

If you are running LabKey Server against Microsoft SQL Server, you should comment out the Resource tag that specifies the PostgreSQL configuration, and add a Resource tag for the Microsoft SQL Server configuration. A template Resource tag for MS SQL Server is available in this topic: Install Microsoft SQL Server.

If you are running LabKey Server against a remote installation of a database server, you will also need to change the url attribute to point to the remote server; by default it refers to localhost.

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.

GUID Settings

By default, LabKey Servers periodically communicate back to LabKey developers whenever the server has experienced an exception. LabKey rolls up this data and groups it by the GUID of each server. You can override the Server GUID stored in the database with the one specified in labkey.xml. This ensures that the exception reports sent to LabKey Server developers are accurately attributed to the server (staging vs. production) that produced the errors, allowing swift delivery of fixes. For details, see Tips for Configuring a Staging Server.

SMTP Settings

LabKey Server uses an SMTP mail server to send messages from the system, including email to new users when they are given accounts on LabKey. Configuring LabKey Server to connect to the SMTP server is optional; if you don't provide a valid SMTP server, LabKey Server will function normally, except it will not be able to send mail to users.

At installation, you will be prompted to specify an SMTP host, port number, user name, and password, and an address from which automated emails are sent. Note that if you are running Windows and you don't have an SMTP server available, you can set one up on your local computer.

The SMTP settings are found in the Resource tag named "mail/Session".

  • Set to the name of your organization's SMTP mail server.
  • mail.smtp.user Specifies the user account to use to log onto the SMTP server.
  • mail.smtp.port Set to the SMTP port reserved by your mail server; the standard mail port is 25. SMTP servers accepting a secure connection may use port 465 instead.
SMTP Authentication and Secure Connections: Many LabKey installations run an SMTP server on the same machine as the LabKey web server, which is configured for anonymous access from the local host only. Since only local applications can send mail, this ensures some amount of security without the hassle of using a central, authenticated mail server. If you choose instead to use an external authenticated server, you'll need to add the following:
  • mail.smtp.from This is the full email-address that you are would like to send the mail from. It can be the same as mail.smtp.user, but it doesn't need to be.
  • mail.smtp.password This is the password.
  • mail.smtp.starttls.enable When set to "true", configures the connection to use Transport Level Security (TLS).
  • mail.smtp.socketFactory.class When set to "", configures the connection to use an implementation that supports SSL.
  • mail.smtp.auth= When set to "true", forces the connection to attempt to authenticate using the user/password credentials.
When LabKey Server sends administrative emails, as when new users are added or a user's password is reset, the email is sent with the address of the logged-in user who made the administrative change in the From header. The system also sends emails from the Issue Tracker and Announcements modules, and these you can configure using the mail.from attribute so that the sender is an aliased address. The mail.from attribute should be set to the email address from which you want these emails to appear to the user; this value does not need to correspond to an existing user account. For example, you could set this value to "".

Notes and Alternatives

  • If you do not configure an SMTP server for LabKey Server to use to send system emails, you can still add users to the site, but they won't receive an email from the system. You'll see an error indicating that the email could not be sent that includes a link to an HTML version of the email that the system attempted to send. You can copy and send this text to the user directly if you would like them to be able to log into the system.
  • If you are running on Windows and you don't have a mail server available, you can configure the SMTP service. This service is included with Internet Information Server to act as your local SMTP server. Follow these steps:
    • From the Start menu, navigate to Control Panel | Add or Remove Programs, and click the Add/Remove Windows Components button on the left toolbar.
    • Install Internet Information Services (IIS).
    • From Start | Programs | Administrative Tools, open the Windows Services utility, select World Wide Web Publishing (the name for the IIS service), display the properties for the service, stop the service if it is running, and set it to start manually.
    • From Start | Programs | Administrative Tools, open the Internet Information Services utility.
    • Navigate to the Default SMTP Virtual Server on the local computer and display its properties.
    • Navigate to the Access tab, click Relay, and add the address for the local machine ( to the list of computers which may relay through the virtual server.

Troubleshooting SMTP

  • Begin by double checking that your labkey.xml file entries for the SMTP parameters (host, user, port, password) are correct. You can validate this by using them to log into the SMTP server directly.
  • If you are using gmail as your own email host, you may need to configure your gmail security settings to allow other applications to use it to access the server.
  • LabKey Server development source code includes a module named Dumbster to be used as a dummy SMTP server for testing purposes. See the testAutomation GitHub repository. It provides a Mail Record web part, which you can use to test outgoing email without sending actual email. If you are seeing unexpected SMTP configuration values, such as mail.smtp.port set to 53937 when you go to the Test Email Configuration link on the Admin Console, check the Admin Console's list of deployed modules for the Dumbster module. If it is present, you may need to disable the capture of email via the Mail Record web part to enable SMTP to send email. Learn more here.

Encryption Key

LabKey Server deployments 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 labkey.xml; LabKey will refuse to save credentials if an encryption key is not configured.

Specify an encryption key as follows:

<Parameter name="EncryptionKey" value="@@encryptionKey@@" />

Replace @@encryptionKey@@ with 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.

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

LDAP Synchronization (Premium Feature)

If you wish to synchronize with the user and groups on an LDAP server, and are using a premium edition of LabKey Server, add an appropriate <Resource> tag to the labkey.xml file.

An example configuration to a public LDAP test service:

<Resource name="ldap/ConfigFactory" auth="Container"

Since this is an XML file, you will need to follow XML escaping for special characters such as using "&lt;" for less than.

The following optional properties are also supported:

  • useTls: true/false, defaults to false.
  • useSsl: true/false, defaults to false. You may only opt into TLS or SSL, not both.
  • sslProtocol: SSL, SSLv2, or SSLv3 to restrict which versions of the SSL protocol is to be used.
Learn more about LDAP synchronization in this topic: LDAP User/Group Synchronization

Set File Roots

If you want to update the server so the files directory is pointing to a SAN, NFS, or another mounted drive, see the following topics:

Installation Checklist

  1. Install on Linux: Main Components OR Install on Windows: Main Components
  2. Installation: Tomcat Configuration
  3. (Current Topic) Installation: SMTP, Encryption, LDAP, and File Roots
  4. Installation: Third-Party Components

Related Topics


Was this content helpful?

Log in or register an account to provide feedback

expand all collapse all