The LabKey Server configuration file, labkey.xml by default, contains settings required for LabKey Server to run on Tomcat. This topic describes modifications you may need to make to that file. The
previous step included moving it to
<tomcat-home>/conf/Catalina/localhost.
Configuration File Name
The default URL for your LabKey Server installation is http://<servername>/labkey, so the configuration file name is
labkey.xml.
If you wish to rename the default URL path to include something else in the place of "labkey", you can change the name by renaming the labkey.xml file. If you do this, you should do it when you first install LabKey Server, as changing the name later will cause any external links to your application to break. Note that Tomcat treats URLs as case-sensitive.
Note that if you rename the configuration file, you will also need to edit the context path setting within it, as described below.
If you wish for your LabKey Server application to run at the server root, you can rename labkey.xml to ROOT.xml. In this case, you should set the context path to be "/". You would then access your LabKey Server application with an address like http://<servername>/.
Securing the LabKey Configuration File
Important: 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 appdocbase 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, 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 with the correct password. Do not include the "@@" surrounding it.
Many other LabKey Server settings can be set in the Admin Console of the web application. For more information, see
Site Settings.
The path Attribute
The
path attribute of the Context tag specifies the context path for the application URL. The context path identifies this application as a unique application running on Tomcat.
The context path is the portion of the URL that follows the server name and port number. By default, the context path is set to "labkey".
Note that the name of the configuration file must match the name of the context path, including case, so if you change the context path, you must also change the name of the file.
The appDocBase Attribute
The
appDocBase 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 C:\Program Files\LabKey Server on a Windows machine, you would change the initial value to "C:\Program Files\LabKey Server\labkeywebapp".
Database Settings
The
username and
password attributes must be set to a user name and password with admin rights on your database server. The user name and password that you provide here can be the ones that you specified during the PostgreSQL installation process for the
database superuser. 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 template resource tag for PostgreSQL applies to Tomcat 8 and above:
<Resource name="jdbc/labkeyDataSource" auth="Container"
type="javax.sql.DataSource"
username="postgres"
password="sa"
driverClassName="org.postgresql.Driver"
url="jdbc:postgresql://localhost:5433/labkey162"
maxTotal="20"
maxIdle="10"
maxWaitMillis="120000"
accessToUnderlyingConnectionAllowed="true"
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 at:
Install Microsoft SQL Server.
Notes:LabKey Server does not use Windows authentication to connect to Microsoft SQL Server; you must configure Microsoft SQL Server to accept SQL Server authentication.
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 (Optional, Recommended)
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".
- mail.smtp.host 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 "javax.net.ssl.SSLSocketFactory", 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 "labkey@mylab.org".
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 XP or a later version of 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 (127.0.0.1) to the list of computers which may relay through the virtual server.
Troubleshooting
- 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.
Master 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 a "master encryption key" that administrations set in labkey.xml; LabKey will refuse to save credentials if an encryption key is not configured.
Specify a master encryption key as follows:
<Parameter name="MasterEncryptionKey" value="@@masterEncryptionKey@@" />
Replace @@masterEncryptionKey@@ 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 key can't be changed, otherwise the existing values will be irretrievable. 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.
LDAP Synchronization
If you wish to synchronize with the user and groups on an LDAP 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"
type="org.labkey.premium.ldap.LdapConnectionConfigFactory"
factory="org.labkey.premium.ldap.LdapConnectionConfigFactory"
host="ldap.forumsys.com"
port="389"
principal="cn=read-only-admin,dc=example,dc=com"
credentials="password"
/>
Related Topics
Next Step in Manual Installation
