Step-by-Step Installation Documentation

In case of errors or other problems when installing and starting LabKey Server, first review installation basics and options linked on the Install LabKey page.

Step-by-step instructions for each mode of installation are available on these pages:

Developer Mode

Running a server in "devmode" provides enhanced logging, enables the MiniProfiler, and provides resource reloading without the need to restart or rebuild the server. To run the server in devmode:

  • Open a command prompt.
  • Go to the CATALINA_HOMEbin directory, for example:
C:\Program Files (x86)\LabKey Server\apache-tomcat-7.0.xx\bin
  • Execute the tomcat7w.exe program:
tomcat7w.exe //ES//LabKeyTomcat7
  • The command will open a program window. Click the Java tab.
  • In the Java Option box, scroll to the bottom of the properties. Add the following property at the bottom of the list:
  • Close the program window and restart the server.
  • To confirm that the server is running in devmode, go to Admin > Site > Admin Console. Click System Properties. Locate the devmode property, and confirm that its value is 'true'.

Which version of LabKey Server Is Running?

  • Find your version number at Admin -> Site -> Admin Console.
  • Under Module Information, locate the Core module. The version shown here, is the version number for your installation of LabKey Server.

Common Issues

Conflicting Applications

Before installing LabKey Server, you should shut down all other running applications. If you have problems during the installation, try additionally shutting down any virus scanning application, internet security applications, or other applications that run in the background.

Compatible Component Versions

Confirm that you are using the supported versions of the required components, as detailed in the Supported Technologies Roadmap. It is possible to have multiple versions of some software, like Java, installed at the same time. Check that other applications, such as Tomcat, are configured to use the correct versions.

Postgres Installation

You can only install one instance of PostgreSQL on your computer at a time.

  • If you already have PostgreSQL installed for another purpose, LabKey can use your installed instance; however, you will need to install LabKey manually.
  • The Windows Graphical Installer will attempt to install a new instance of PostgreSQL for you.
    • If you have previously installed Postgres (whether as part of prior LabKey server installation or not), first manually uninstall the program. You may also need to manually delete the PostgreSQL data directory.
    • You may also need to remove references to Cygwin from your Windows system path before installing LabKey, due to conflicts with the PostgreSQL installer. The PostgreSQL installer also conflicts with some antivirus or firewall software programs. (see for more information).
    • If you are upgrading an existing LabKey server installation using the Windows Graphical Installer, have tried the above and still have problems installing postgres, you may need to manually stop a running LabKey_pgsql-## service.

Non-English Versions of Windows

If you are running a non-English version of Windows, please use the manual install process, not the Windows Graphical Installer.

Tomcat Failure to Start

If installation fails to start tomcat (such as with an error like "The specified service already exists."), you may need to manually stop or delete a failing Tomcat service.

To stop the service on Windows, open Control Panel > Administrative Tools > Services; click LabKey Server Apache Tomcat 7.0; click Stop.

To delete, from the command line (may need to run as administrator):

sc delete LabKeyTomcat7

Java 8 Upgrade Note

When you upgrade to Java 8, be sure to remove the setting of MaxPermSize. If your CATALINA_OPTS or other configuration files include something like "-XX:MaxPermSize=256M" you may have errors when starting your server.

Restart Installation from Scratch

If you have encountered prior failed installations, don't have any stored data you need to keep, and want to clean up and start completely from scratch, the following process may be useful:

  • Delete the Tomcat service (if it seems to be causing the failure):
    • From the command line (may need to run as administrator):
sc delete LabKeyTomcat7
  • Uninstall Postgres using their installer.
    • Control Panel > Programs and Features
    • Select Postgres program (PostgreSQL9.2 or similar).
    • Click Uninstall.
  • Delete the entire LabKey installation directory:
C:\Program Files\LabKey Server
  • Run the LabKey Installer again.

Error Messages

Please see Installation Error Messages.

Community Forums

You can search for problems resolved through community support in the LabKey Community Support Forums.

If you don't see your issue listed there, you can post a new question. If the install seems successful, it is often helpful to submit debugging logs for diagnosis.

If the install failed to complete, please include the install.log and install-debug.log from your selected LabKey install directory (Note: you may wish to sanitize the logs of any database login information you provided to the installer). PostgreSQL logs its installation process separately. If the installer indicates that PostgreSQL installation/upgrage failed, please locate and include the postgres install logs as well.





expand all collapse all