The LabKey Server configuration file contains settings required for LabKey Server to run on Tomcat. By default it is named labkey.xml. The template version of labkey.xml is included with the LabKey Server distribution described in the Install Required Components help topic. During the installation process, you should have moved the labkey.xml file to the <tomcat-home>/conf/Catalina/localhost directory, as instructed in the Configure the Web Application help topic.

The Configuration File Name

The name of the LabKey Server configuration file determines the URL address of your LabKey Server application. This means that the default URL for your LabKey Server installation is http://<servername>/labkey. You can change the name of the configuration file from labkey.xml to something else if you wish to access your LabKey Server application with a URL other than the default. It's best to do this when you first install LabKey Server, rather than on subsequent upgrades, as changing the name of the configuration file will cause any external links to your application to break. Also, since Tomcat treats URLs as case-sensitive, external links will also break if you change the case of the configuration file name.

Note that if you name the configuration file something other than labkey.xml, you will also need to edit the context path setting within the configuration file, 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 path attribute, which specifies the application context path used in the application's URL address
• 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
• Mapped network drive settings

Note: 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 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 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. Th database superuser password is one of three types of passwords used by LabKey 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.

If you are running LabKey Server against Microsoft SQL Server, you should comment out the Resource tag that specifies the PostgreSQL configuration, and uncomment the tag which provides the Microsoft SQL Server configuration. Then replace the default attribute values with your SQL Server user name and password.

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

SMTP Settings (Optional)

LabKey Server uses an SMTP mail server to send messages from the system. 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.

The SMTP settings are found in the Resource tag named "mail/Session". The mail.smtp.host attribute should be set to the name of your organization's SMTP mail server. The mail.smtp.user specifies the user account to use to log onto the SMTP server. The mail.smtp.port attribute should be set to the SMTP port reserved by your mail server; the standard mail port is 25.

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:

• 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.
• Tomcat versions 5.5.17 through 5.5.23 contain a bug which renders the web server unable to send mail from any mail server other than one running on localhost (the computer on which Tomcat is installed). Apache has provided a patch for this bug, which is available at http://issues.apache.org/bugzilla/show_bug.cgi?id=40668. Please download this patch if you are running Tomcat 5.5.17 or later. The patch is a zip file containing .class files in a package structure starting at a folder named "org". Unzip these folders and files under the <tomcat-home>/common/classes/ directory, then restart Tomcat.