This topic explains how to install LabKey on a Windows machine, along with its prerequisites: Java, Apache Tomcat, and a database.
This topic assumes installation onto a clean Windows machine which contains none of the prerequisite components. If you are installing into an established environment, you can skip steps, or adjust them, to use any prerequisites already in place. We also assume that you have super-user/administrator access to the machine.
Directory Set Up
- Setup the directory structure as below. This is the structure that we use internally for our LabKey servers:
C:\labkey\apps - This is where the prerequisite apps live.
C:\labkey\apps\tomcat
C:\labkey\apps\java
C:\labkey\apps\lib - This holds any special scripts or files, like SSL certificates.
C:\labkey\labkey - This is where Labkey gets installed to.
C:\labkey\src\labkey - This is where the downloaded distribution files go before installing.
- In a command line shell, use:
cd C:\
mkdir labkey\apps\tomcat
mkdir labkey\apps\java
mkdir labkey\apps\lib
mkdir labkey\labkey
mkdir labkey\src
Download Components
Java
- Unzip and deploy as follows:
labkey
apps
java
jdk-##.#.#
- Set the JAVA_HOME environmental variable and add it to the PATH as follows:
- Press the Start key, type "env", and click Edit the system environment variables.
- In the System Properties dialog, on the Advanced tab, click Environment Variables.
- Under System Variables click New....
- For Variable name, enter "JAVA_HOME"
- For Variable value, enter the full path to your jdk, for example, "C:\labkey\apps\jdk-##.#.#"
- Click OK to confirm your changes.
- Locate the System Variable named Path.
- Select it, and click Edit...
- Add the following entry: %JAVA_HOME%\bin
- Click OK three times to confirm the stacked dialog boxes.
Tomcat
- Unzip and deploy as follows:
labkey
apps
tomcat
apache-tomcat-#.#.##
- Set the environment variable CATALINA_HOME to C:\labkey\apps\tomcat-#.#.##
- Install Tomcat as a service by running the script service.bat:
C:\labkey\apps\tomcat-#.#.##\bin\service.bat install
- Open the Services panel. Right-click Apache Tomcat 9.0 Tomcat9 and select Properties.
- In the popup dialog, click the tab Log On. If necessary, select Local System account. Click OK.
- On the Services panel, start Tomcat.
- Confirm the Tomcat install, by visting the URL:
- On the Services panel, stop Tomcat before continuing.
PostgreSQL
This topic explains how to install PostgreSQL as part of an installation of LabKey Server.
If you already have PostgreSQL installed, LabKey Server can use that installed instance, provided the version is supported.
To install PostgreSQL on Windows:
- Download and run the Windows PostgreSQL one click installer. When the wizard prompts you to choose where to install PostgreSQL, point it to the apps subdirectory, i.e. C:\labkey\apps\
- Keep track of the PostgreSQL Windows Service account name and password. LabKey Server needs to ask for it so that we can pass it along to the PostgreSQL installer.
- Keep track of the database superuser name and password. You'll need these to initially create the LabKey database, the LabKey database user, and grant that user the owner role.
- We recommend that you install the graphical tool pgAdmin 4.x for easy database administration. Leave the default settings as they are on the "Installation Options" page to include pgAdmin.
- Create the database. Using superuser permissions, do the following:
- Create an empty database.
- Create a PostgreSQL user named 'labkey'.
- Grant the owner role to the labkey user over the database.
- Revoke public permissions from the database.
See the following example PostgreSQL commands:
- Connect to the DB server as the Postgres Super User using the psql command:
- Issue the following commands to create the user, database and revoke public permissions from the database. Use the example below, after substituting your chosen values for LABKEY_USERNAME and PASSWORD_HERE. Retain the single quotes around the password value.
create user labkey password 'PASSWORD_HERE' ;
create database labkey with owner labkey;
revoke all on database labkey from public;
\q
- The username and password you choose above will be used in the main configuration file below.
LabKey Server
- Unzip LabKey####-####-community-bin.zip
- The zip file contains:
bin Windows-specific binary files required by LabKey Server.
labkeywebapp The LabKey Server web application.
modules LabKey Server modules.
pipeline-lib Jars for the data processing pipeline.
tomcat-lib Server library jars.
labkey.xml LabKey Server configuration file.
manual-upgrade.sh For use with existing installations.
README.txt A file pointing you to this documentation.
VERSION A file containing the release number and build number.
Main LabKey Binaries and Libraries
- Copy the following directories:
bin
labkeywebapp
modules
pipeline-lib
Tomcat Libraries
- Go to the tomcat-lib dir in the distribution:
\LabKey####-####-community-bin\tomcat-lib
- Copy the contents of tomcat-lib...
javax.activation.jar
labkeyBootstrap.jar
mail.jar
- ...into CATALINA_HOME\lib:
C:\labkey\apps\apache-tomcat-#.#.##\lib
Main Configuration File: labkey.xml
- Create the directory path
C:\labkey\apps\apache-tomcat-#.#.##\conf\Catalina\localhost
- Copy the file labkey.xml. Find it in the unzipped distribution, and copy this file into the dir path just created, as follows:
C:\labkey\apps\apache-tomcat-#.#.##\conf\Catalina\localhost\labkey.xml
docbase, user, and password
- In labkey.xml, substitute the values for @@...@@ tokens as below:
- @@appDocBase@@ - replace with the full path: C:\labkey\labkey\labkeywebapp
- @@jdbcUser@@ - the same username specified when creating the PosgreSQL db above. In this example 'labkey'.
- @@jdbcPassword@@ - the same password specified when creating the PosgreSQL db above.
Start LabKey Server
- On the Services panel, restart Apache Tomcat
- If you are installing on a local machine, visit the LabKey home page at:
or, if you are installing on a remote server:
- For a new server, you are invited to create the initial user profile, which is a Site Administrator.
Installation Checklist
- (Current Topic) Install on Windows: Main Components
- Installation: Tomcat Configuration
- Installation: SMTP, Encryption, LDAP, and File Roots
- Installation: Third-Party Components
