This topic explains how to install LabKey on a Windows machine, along with its prerequisites: Java JDK and a database. Apache Tomcat is now embedded with the LabKey Server distribution.
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 may need to adjust or skip some steps below. We also assume that you have super-user/administrator access to the machine.
Installation Steps:
Determine Supported Versions
Before beginning, identify the versions of Java and your database that will be compatible with the version of LabKey you are installing. Learn more in this topic:
Create Folder Structure
We recommend using the directory structure described here, which will make our documentation and any support needed much easier to follow. Create this folder hierarchy:
Directory | Description |
---|
C:\labkey | This is the top level, referred to in the documentation as <LABKEY_ROOT> |
C:\labkey\labkey | This is where LabKey Server gets installed, known as <LABKEY_HOME> in the documentation. |
C:\labkey\src | This is where the downloaded distribution files go before installing. |
C:\labkey\apps | This holds the prerequisite apps and other utilities. |
C:\labkey\backupArchive | Use this to hold backups as needed. |
C:\labkey\labkey\labkey-tmp | A directory for temp files that LabKey's embedded Tomcat produces while running. |
Install Java
Download the latest
supported version of Java for your platform and store it in C:\labkey\src.
Unzip the downloaded distribution and deploy under your apps location:
C:\labkey\apps\java\jdk-##.#.#
Set the JAVA_HOME environmental variable and add it's bin subdirectory to the PATH.
- Open the editor for Environment Variables on your machine.
- Under System Variables, click New... and add a variable named "JAVA_HOME" with the full path to your JDK as the value. For example, "C:\labkey\apps\java\jdk-##.#.#"
- Click OK to confirm your changes.
- Select the System Variable named Path and click Edit...
- Add: %JAVA_HOME%\bin
- Click OK to confirm the stacked dialog boxes.
Install the Database (PostgreSQL)
This section explains how to install PostgreSQL for 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 for the latest supported version. When the wizard prompts you to choose where to install PostgreSQL, point it to 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 PostgreSQL.
- 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
Notes
Download the LabKey Distribution
Download the binaries:
- Premium Edition users can download their custom distribution from the Server Builds section of their client support portal.
- Community Edition users can register and download the distribution here: Download LabKey Server Community Edition.
Download the current binary tar.gz distribution into the C:\labkey\src directory, then unpack it in that location.
It will contain:
- The "labkeyServer.jar" file
- A VERSION text file that contains the version number of LabKey
- A bin directory that contains various DLL and EXE files
- A config directory, containing an application.properties template
- An example Windows service install script named "install_service.bat"
- An example systemd unit file for Linux (Not needed for installation on Windows)
Deploy the LabKey Components
Copy the following from the unpacked distribution into <LABKEY_HOME>.
- The labkeyServer.jar
- The config directory
- The bin directory
Create this directory to contain logs that will be written when the server is running:
Customize the application.properties File
In the <LABKEY_HOME>\config folder you just copied, you need to edit your application.properties file to provide settings and configurations including, but not limited to:
- Your database configuration and credentials
- The port and TLS/SSL settings (HTTP and HTTPS access information)
- Other details and customizations you may need
Learn about customizing this file in:
Configure the LabKey User and Service
1. Confirm where your labkey-tmp directory is located. It might be <LABKEY_HOME>\labkey-tmp. If not, you'll need to edit the service file.
2. Create the 'labkey' user, making it a SYSTEM user.
- Confirm that this user has Full Control permissions under the Security tab of the properties for all files and folders under <LABKEY_HOME>.
3. Download the Apache Commons Daemon and unzip it. <LABKEY_ROOT>\apps is a good place to store the download.
4. Copy the "prunsrv.exe" file to your <LABKEY_HOME> directory.
- Note: There is an AMD64 version in a separate folder, so make sure you copy the correct one based on your CPU architecture. Failing to use the correct one will prevent the service from installing correctly and will require it to be deleted and recreated again.
5. Copy the new "install_service.bat" file from your unpacked LabKey distribution tar.gz to <LABKEY_HOME>.
- Edit this new <LABKEY_HOME>\install_service.bat file to customize any paths or other settings that do not match the template.
6. To install your Windows Service, open a Command Prompt and navigate to the <LABKEY_HOME> directory. Both "install_service.bat" and "prunsrv.exe" are in this directory. Then run the following command:
install_service.bat install
Start LabKey Server
Go to the Windows Services console and start your service. The server will start and begin generating logs under <LABKEY_HOME>\logs.
You can now access the running server, and as the first user, you are invited to create the initial user profile, as a Site Administrator.
Installation Checklist
- (Current Topic) Install on Windows
- Set Application Properties
- Install Third-Party Components