This topic provides step-by-step instructions for acquiring the LabKey Server source code, installing required components, and building LabKey Server from source. The instructions are written for a Windows machine; use in conjunction with the topic Notes on Setting up OSX for LabKey Development
, to set up development on an OSX or Linux machine.
A checklist, guiding you through the setup process, is available for download: LabKey_Development_Server_Checklist.xlsx
Obtain the LabKey Source Files
The LabKey source files are stored in two repositories: (1) the core modules are stored in an SVN repository and (2) additional modules are stored on GitHub.
The following instructions apply to Windows machines. To install SVN on non-Windows machines see Enlist in the Version Control Project
- Download the latest version of TortoiseSVN.
- Install TortoiseSVN on your local computer.
- On the list of features to install, include the command line client tools.
- Add the TortoiseSVN/bin directory to your PATH (if it was not automatically added).
Checkout LabKey Source Files
- Create a new directory in the Windows file system for the source files, for example, C:\dev\labkey\trunk
- In Windows Explorer, right-click the new directory and select SVN Checkout.
- Enter the URL for the LabKey repository:
- No username/password is required.
- Click OK to checkout the source files. At this point, all the LabKey source files, tests, and sample data will be copied to your computer.
Install Required Prerequisites
Install a Database
- Install one of the following database servers: PostgreSQL or Microsoft SQL Server. Find supported versions in this topic.
- Platform-specific installation instructions:
Node.js and npm
The LabKey build depends on Node.js and the node package manager (npm). The build process automatically downloads and installs the versions of npm and node that it requires. You should not install npm and node yourself. For details on the Node.js dependency see Node.js Build Dependency
Note that you do not
need to install Gradle and should resist the urge to do so. LabKey uses the gradle wrapper to make updating version numbers easier. The gradle wrapper script (either gradlew or gradlew.bat) is included in the SVN sync and is already in the <LABKEY_HOME> directory.
Create a gradle properties file to contain information about global settings for your gradle build following these steps:
- Create a ".gradle" directory in your home directory (e.g., /Users/<you>/.gradle on OSX or C:\Users\<you>\.gradle on Windows). Note: the Windows file explorer may not allow you to create a folder beginning with a period. To solve this navigate to C:\Users\<you>\ in the command prompt and type mkdir .gradle.
- Create a gradle.properties file in the .gradle directory:
- Copy and rename <LABKEY_HOME>/gradle/global_gradle.properties_template. Note: depending on how you create this file on Windows, an extra .txt extension may silently be attached to it. Be sure to remove the extra extension if it is there. Gradle will not recognize the file with the .txt extension and your properties will not be read.
- Substitute your <CATALINA_HOME> directory (the location of your Tomcat installation), including the specific version number, for the value after systemProp.tomcat.home. On Windows, use forward slashes, not backslashes, for the Tomcat path. For example:
Environment Variables and System PATH
- Create or modify the system environment variable JAVA_HOME so it points to your JDK installation location (for example, C:\java\jdk-##.#.#). Note: If you've already set the JAVA_HOME variable to point to your installation of the JRE, you should modify it to point to the JDK.
- Create or modify the system environment variable CATALINA_HOME so that it points to your Tomcat installation (for example, C:\apache\tomcat-#.#.##).
- Add the following location to your system PATH, where <LABKEY_HOME> is the root of your SVN enlistment. This directory won't exist yet, but add it to the path anyway.
For example, C:\dev\labkey-trunk\build\deploy\bin.
On OSX, for example, you would place the environment variables in your .bash_profile:
export JAVA_HOME=`/usr/libexec/java_home -v 1.11`
GWT Browser Settings (Optional)
The default developer build is optimized for Chrome but the target browser can be controlled through either a command line parameter or by setting the 'gwtBrowser' property in the gradle.properties file. Available settings are: gwt-user-chrome (the default value), gwt-user-firefox, or gwt-user-ie.
Open the LabKey Project in IntelliJ
The LabKey development team develops LabKey using IntelliJ IDEA. You can use the licence-free Community Edition of this tool if you are planning on modifying or extending the LabKey source code.
Below we describe how to configure the IntelliJ development environment; we recommend employing the same general principles if you are using a different development environment. Some developers have experimented with Eclipse as the IDE and you can find some set up details on the Developer Message Board
- Download and install the latest version of IntelliJ IDEA. Either the Community or Ultimate Editions will work.
Configure the LabKey Project in IntelliJ
- Create the workspace.xml file.
- Copy the file <LABKEY_HOME>/.idea/workspace.template.xml. Rename the copy to create a file called <LABKEY_HOME>/.idea/workspace.xml
- This file configures the debug information for LabKey project. To review the debug settings go to Run > Edit Configurations in IntelliJ.
- Open the LabKey project.
- Launch IntelliJ.
- If your IntelliJ install is brand new, you will see the "Welcome to IntelliJ" pop up screen. Click Open. If you have previously installed IntelliJ, select File > Open.
- Select the LabKey IntelliJ project directory: <LABKEY_HOME>
- If asked about an "Unlinked Gradle project", DO NOT "Import Gradle project" in the default way from IntelliJ. See the troubleshooting section Starting Over with Gradle + IntelliJ for more information.
- Set CATALINA_HOME
- Select File > Settings > Appearance & Behavior > Path Variables. (On a Mac, the menu path is IntelliJ IDEA > Preferences > Appearance & Behavior > Path Variables).
- Click the green plus icon in the upper right. Set the CATALINA_HOME path variable to <CATALINA_HOME>, the root directory of your Tomcat installation, for example, C:\labkey\apps\apache\apache-tomcat-#.#.##.
- Click OK to close the Settings window.
- Configure the Target JDK
- In IntelliJ, select File > Project Structure.
- Under Project Settings, click Project.
- Under Project SDK click New and then click JDK.
- Browse to the path of your JDK, for example, (C:\java\jdk-##.#.#), and click OK.
- Click Edit. Change the name of the JDK to "labkey".
- Click Ok to close the Project Structure window.
- Configure the Gradle build tool
- Select File > Settings > Build, Execution, Deployment > Build Tools > Gradle
- Ensure that the checkbox next to "Create separate module per source set" is checked
- Ensure that the radio button next to "Use default gradle wrapper" is on
- Open the Gradle tool window at View > Tool Windows > Gradle.
- Click the refresh icon. This will take as much as 15-30 minutes. You should start seeing messages about its progress. If not, something is probably hung up. Wait for this sync to complete before progressing with further IntelliJ configuration steps.
- Edit configuration options as follows:
- Select Run > Edit Configurations. (If the menu is greyed-out, wait until IntelliJ finishes indexing the project files.)
- Open the Application node in the left panel and select LabKey Dev.
- VM options: Confirm that the path separators are appropriate for your operating system. On Windows, ensure that the paths to the jar files are separated by semicolons. For example: "./bin/bootstrap.jar;./bin/tomcat-juli.jar;C:/Program Files (x86)/JetBrains/IntelliJ IDEA 2016.3.3/lib/idea_rt.jar". For Macs, the paths should be separated by a colon.
- Confirm that Working Directory points to your current Tomcat installation (i.e. to CATALINA_HOME).
- Confirm that the dropdown labeled Use classpath of module is set to api_main.
- Click OK, to close the Run/Debug Configurations window.
- Be sure that IntelliJ has enough heap memory. The default max is OK if you’re just dealing with the core modules, but you will likely need to raise the limit if you’re adding in customModules, optionalModules, etc. 3GB seems sufficient.
Build and Run LabKey
Configure the Appropriate .properties File
The LabKey source includes two configuration files, one for use with PostgreSQL (pg.properties
) and one for use with Microsoft SQL Server (mssql.properties
), each specifying JDBC settings, including URL, port, username, password, etc.
- If using PostgreSQL, open the file <LABKEY_HOME>/server/configs/pg.properties
- If using MS SQL Server, open the file <LABKEY_HOME>/server/configs/mssql.properties
- Edit the appropriate file, adding your values for the jdbcUser and jdbcPassword. (This password is the one you specified when installing PostgreSQL or MS SQL Server. If your password contains an ampersand or other special XML characters, you will need to escape it in the .properties file, as the value will be substituted into an XML template without encoding. For example, if your JDBC password is "this&that", then use the escaped version "this&that".)
Run pickPg or pickMSSQL
- In a command window, go to the directory <LABKEY_HOME>
- Run "gradlew pickPg" or "gradlew pickMSSQL" to configure labkey.xml with the corresponding database settings.
- You may need to manually create the directory <CATALINA_HOME>/conf/Catalina/localhost.
When you build LabKey, the values that you've specified in the mssql.properties
file are copied into the LabKey configuration file, labkey.xml, overwriting previous values. This file is then copied into <CATALINA_HOME>/conf/Catalina/localhost
To learn more about the build process, the various build targets available, and how the source code is transformed into deployed modules, see Build LabKey from Source
- On the command line, go to the <LABKEY_HOME> directory, and invoke the gradle build target:
To control which modules are included in the build, see Customize the Build
Run LabKey Server
To run and debug LabKey:
- Select Run > Debug 'LabKey Dev' in IntelliJ.
- If Tomcat starts up successfully, navigate your browser to http://localhost:8080/labkey to begin debugging (assuming that your local installation of Tomcat is configured to use the Tomcat default port 8080).
While you are debugging, you can usually make changes, rebuild, and redeploy LabKey to the server without stopping and restarting Tomcat. Occasionally you may encounter errors that do require stopping and restarting Tomcat.
Run the Basic Test Suite
- Run the command 'gradlew :server:test:uiTest -Psuite=DRT' from within your <LABKEY-HOME> directory, to initiate automated tests of LabKey's basic functionality.
Note that 'R' must first be configured
for these tests to run. Other automated tests are available. For details, see Run Automated Tests
Modules on GitHub
Many optional modules are available from the LabKey repository on GitHub
. To include these modules in your build, install a Git client and clone individual modules into the LabKey Server source.
Install a Git Client
- Install GitHub, or another Git client:
Clone Modules from LabKey's GitHub Repository
- To add a GitHub module to your build, clone the desired module into trunk/labkey/server/optionalModules. For example, to add the 'workflow' module:
Note that you can get the URL by going to the module page on GitHub (for example, https://github.com/LabKey/workflow
), clicking Clone or Download
, and copying the displayed URL.
Manage GitHub Modules via IntelliJ
Once you have cloned a GitHub module, you can have IntelliJ handle any updates:
To add the GitHub-based module to IntelliJ (and have IntelliJ generate an .iml file for the module):
- Edit your settings.gradle file to include the new module
- In IntelliJ, open the Gradle tool window at View > Tool Windows > Gradle.
- Refresh the Gradle window by clicking the arrow circle in the upper left of the Gradle window
To update the GitHub-based module using IntelliJ:
- To have IntelliJ handle source updates from GitHub, go to File > Settings (or Intellij > Preferences).
- Select Version Control.
- In the Directory panel, scroll down to the Unregistered roots section, select the module, and click the Plus icon in the lower left.
- In the Directory panel, select the target module and set its VCS source as Git, if necessary.
- Note that IntelliJ sometimes thinks that subdirectories of the module, like module test suites, have their sources in SVN instead of Git. You can safely delete these SVN sources using the Directory panel.
- To sync to a particular GitHub branch: in IntelliJ, go to VCS > Git > Branches. A popup menu will appear listing the available Git modules. Use the popup menu to select the branch to sync to.
If you have added a new module to your enlistment, be sure to customize the build
to include it in your Gradle project and then refresh the Gradle window to incorporate it into IntelliJ, as described above.
Install Optional Components
Mass Spec and Proteomics Tools
LabKey Server's mass spectrometry and proteomics binaries are provided as a separate (and optional) enlistment. To add these binaries, follow the instructions in the topic: Add the Proteomics Binaries