Before manually installing or upgrading LabKey Server, you'll need to install the correct versions of all of the required components. We recommend only using the versions we have tested and approved, even if they are not the most recent editions. Find details in the topic:
Supported Technologies. This topic outlines the installation process for the components, using # to represent the specific version numbers.
Create Folder Structure
For simplicity, we recommend using the directory structure described here, particularly whenever you are creating a new LabKey installation from scratch.
First create a "labkey" directory at the root level. On Windows, "
C:\labkey"; on Mac or Linux, "
/usr/local/labkey". This directory is known as
<LABKEY_ROOT>. Within this directory, create the following subdirectories. For simplicity, our documentation uses the / slash directory separator; keep in mind that your machine may use \ backslashes:
- apps: This subfolder will hold the third party components: Tomcat, PostgreSQL, OpenJDK.
- labkey: This subfolder (i.e. C:\labkey\labkey) is where your actual LabKey installation will go. This location is known as <LABKEY_HOME>.
- backups: This subfolder will store database and file backups as needed.
- src: This subfolder will house binaries and source code.
- src/labkey: Within the "src" directory, create another subdirectory "labkey". This where you will place the downloaded binaries for LabKey Server.
Install Java
Install the
latest supported release of
OpenJDK.
- Download the binary to the <LABKEY_ROOT>/src directory you created.
- From this directory, unzip the contents to the <LABKEY_ROOT>/apps/ directory. On Windows, for example: C:\labkey\apps\jdk-##. Our documentation refers to this location as <JAVA_HOME>.
- On Windows, set the environment variable JAVA_HOME (no angle brackets) to this location.
- Add the /bin subdirectory of this new location to your PATH. Ex: C:\labkey\apps\jdk-##\bin
- To test this installation on Windows, open a new command window and type:
- It should print the version number of the JDK you just installed. If it does not, check your path and JAVA_HOME variable setting.
On Linux, create a symbolic link from
/usr/local/java to your <JAVA_HOME> location (for example,
/usr/local/labkey/apps/jdk-##). This will make it easier to upgrade in the future.
Install the Apache Tomcat Web Server
We recommend running LabKey Server with the latest approved version of Tomcat. For the specific version to download for your platform, see
Supported Tomcat Versions.
Install Tomcat
1. Download the binaries to
<LABKEY_ROOT>/src2. Install to
<LABKEY_ROOT>/apps/apache-tomcat-#.#.##. We will call this directory
<CATALINA_HOME>. Note that if you were to install Tomcat using their package manager, files and directories such as /lib may be placed in different locations.
- On Linux, create a symbolic link from /usr/local/tomcat to this location (for example, /usr/local/labkey/apps/apache-tomcat-#.#.##).
3. Configure Tomcat to use the JDK you installed above: You can do this either by creating a JAVA_HOME environment variable under the user account that will be starting tomcat, or by adding that variable to the tomcat startup scripts,
<CATALINA_HOME>/bin/startup.sh on Linux or startup.bat on Windows. For example, on Linux add this line to the beginning of the tomcat's startup.sh file:
Export JAVA_HOME=/usr/local/java
4. Start Tomcat. On Linux run
<CATALINA_HOME>/bin/startup.sh. If you want Tomcat to start up automatically when you restart your computer see the Tomcat documentation.
5. Test your Tomcat installation by entering "http://<machine_name or localhost or IP_address>:8080" in a web browser. If your Java and Tomcat installations are successful you will see the Tomcat success page.
Install the Database Server
Install one of the following database servers:
Platform-specific installation instructions:
Install the LabKey Server System Components
1.
Click Here to Register and Download LabKey Binaries. Choose either:
- The current binary zip distribution (LabKey##.#.#-#####-bin.zip)
- The current binary tar.gz distribution (LabKey##.#.#-#####-bin.tar.gz)
Place the binaries in the
<LABKEY_ROOT>/src/labkey directory.
2. Unzip the LabKey Server components in this same folder location. You will move these components later, but unpacking them in a subdirectory of the
<LABKEY_ROOT>/src/labkey directory will help you find them later.
- On Linux or OSX systems, the following command will unzip and untar the archive.
tar xfz LabKey##.#.#-#####-bin.tar.gz
After unpacking the directory should contain these files and directories:
- bin: Binary files required by LabKey Server (only in Windows distributions).
- labkeywebapp: The LabKey Server web application.
- modules: LabKey Server modules.
- pipeline-lib: Jars for the data processing pipeline.
- tomcat-lib: Required server library jars.
- labkey.xml: LabKey Server configuration file.
- manual-upgrade.sh: Manual upgrade script for OSX and non-supported Linux installations.
- README.txt: A file pointing you to this documentation.
- VERSION: A file containing the release number and build number.
Next Steps
After you've downloaded and installed all components, you'll configure the LabKey Server web application to run on Tomcat. See
Configure the LabKey Web Application.
Related Topics
