Before you begin, register with LabKey Corporation if you haven't done so already such that you can download the installable LabKey Server files provided by LabKey Corporation. Note that you'll still need to download the third-party components required by LabKey Server separately, as described below.

Before installing these components, think about where you want them to reside in the file system. For example, you may want to create a LabKey Server folder at the root level and install all components there, or on unix systems, you may want to install them to /usr/local/labkey or some similar place.

Note: The only restriction on where you can install LabKey Server components is that you cannot put the LabKey Server web application files beneath the <tomcat-home>/webapps directory.

Note: We provide support only for the versions listed for each component, and so we strongly recommend that you install that version. These are the versions that have proven themselves over many months of testing and deployment. Some of these components may have more recent releases, but we have not tested or configured the system to work with them.

Install the Java Runtime Environment

1. Download the Java Runtime Environment (JRE) 1.6 from http://java.sun.com/javase/downloads/index.jsp.
2. Install the JRE to the chosen directory. On Windows the default installation directory is C:\Program Files\Java. On Linux a common place to install the JRE is /usr/local/jre<version>. We suggest creating a symbolic link from /usr/local/java to /usr/local/jre<version>. This will make upgrading the JRE easier in the future.

• The JDK includes the JRE, so if you have already installed the JDK, you don't need to also install the JRE.
• If you are planning on building the LabKey Server source code, you should install the JDK 1.6 and configure JAVA_HOME to point to the JDK. For more information, see Building the Source Code.
• If you are installing LabKey on a Mac, you do not need to install the JRE. The JRE comes with the operating system. You should check to make sure that the JRE version included with the OS is a sufficiently recent version of the JRE. For example, Tiger 10.4.10 comes with the JRE 1.5, which is fine.

Install the Apache Tomcat Web Server, Version 5.5.x

LabKey Server supports Tomcat versions 5.5.9 through 5.5.25 and version 5.5.27. Tomcat 5.5.27 is the recommended version of Tomcat for LabKey Server 9.1. For details on supported Tomcat versions, see Supported Tomcat Versions.

1. Download Tomcat 5.5.x from http://tomcat.apache.org/download-55.cgi. Note that this link leads you to the most recent version of Tomcat. For version 5.5.27, see http://tomcat.apache.org/download-55.cgi#5.5.27.
2. Install Tomcat. On Linux, install to /usr/local/apache-tomcat<version>, then create a symbolic link from /usr/local/tomcat to /usr/local/apache-tomcat<version>. We will call this directory <tomcat-home>.
3. Configure Tomcat to use the JRE installed in the first step. 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, <tomcat-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 <tomcat-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

You can run LabKey Server against the following database servers:

• PostgreSQL 8.3.x
• Microsoft SQL Server 2005 or 2008

Install PostgreSQL on Windows

1. Download and run the Windows PostgreSQL installer (http://www.postgresql.org/ftp/binary/).
2. Install PostgreSQL as a Windows service. Keep track of the Postgres Windows service account name and password. LabKey Server doesn't really care what this password is set to, but we need to ask for it so that we can pass it along to the Postgres installer. This password is one of the three password types used on LabKey Systems.
3. Also keep track of the database superuser name and password. You'll need these to configure LabKey Server. For more information, see Modify the Configuration File. LabKey Server uses this password to authenticate itself to Postgres. It is one of three types of passwords used on LabKey Server.
4. Select the PL/pgsql procedural language for installation when prompted by the installer.
5. We recommend that you install the graphical tool pgAdminIII for easy database administration. Leave the default settings as they are on the "Installation Options" page to include pgAdminIII.
6. If you have chosen to install pgAdminIII, enable the Adminpack contrib module when prompted by the installer.
7. Please read the notes below to forestall any difficulties with the PostgreSQL installation.

• You can only install one instance of PostgreSQL on your computer. If you already have PostgreSQL installed, LabKey Server can use your installed instance.
• You may need to disable your antivirus or firewall software before installing PostgreSQL, as the PostgreSQL installer conflicts with some antivirus or firewall software programs. (see http://pginstaller.projects.postgresql.org/faq/FAQ_windows.html for more information).
• On Windows you may need to remove references to Cygwin from your Windows system path before installing PostgreSQL (see http://pginstaller.projects.postgresql.org/faq/FAQ_windows.html for more information).
• If you uninstall and reinstall PostgreSQL, you may need to manually delete the data directory in order to reinstall. By default the data directory on a Windows computer is C:\Program Files\PostgreSQL\8.x\data.
• On Vista, you may need to run 'cmd.exe' as administrator and run the installer .msi from the command line.

Install PostgreSQL on Linux, Unix or Macintosh

1. From http://www.postgresql.org/ftp/ download the PostgreSQL binary RPM package if your system supports RPM, or download and build the source otherwise. If you download a source package ending in .gz, unpack it with the command tar xfz <download_file>. Follow the instructions in the INSTALL file.
2. Please read the notes below to forestall any difficulties with the PostgreSQL installation.

• You can only install one instance of PostgreSQL on your computer. If you already have PostgreSQL installed, LabKey Server can use your installed instance.
• If you uninstall and reinstall PostgreSQL, you may need to manually delete the data directory in order to reinstall.

• Increase the join collapse limit.

# join_collapse_limit = 8

to

join_collapse_limit = 10

If you do not do this step, you may see the following error when running complex queries: org.postgresql.util.PSQLException: ERROR: failed to build any 8-way joins

Or

Install Microsoft SQL Server 2005 or 2008

1. If you don't have a licensed version of Microsoft SQL Server, you can download SQL Server 2008 Express for free from http://www.microsoft.com/express/sql/download/. You will likely want to download a version that includes the SQL Server Management Studio graphical database management tool.
2. Keep track of the user name and password you specify for the administrative account. You have now specified the password for the database superuser. LabKey Server uses this password to authenticate itself to SQL Server. It must be provided in plaintext in labkey.xml and is one of three types of passwords used on LabKey Server.
3. To run LabKey Server against SQL Server, you'll need to edit the LabKey Server configuration file. See Modify the Configuration File for instructions.
4. After you've installed SQL Server, you'll need to configure it to use TCP/IP. Follow these steps:

• Launch the SQL Server Configuration Manager.
• Under the SQL Server Network Configuration node, select Protocols for <servername>.
• In the right pane, right-click on TCP/IP and choose Enable.
• Right-click on TCP/IP and choose Properties.
• Switch to the IP Addresses tab.
• Under the IPAll section, clear the value next to "TCP Dynamic Ports" and set the value for "TCP Port" to 1433 and click OK. By default, SQL Server will choose a random port number each time it starts, but the JDBC driver expects SQL Server to be listening on port 1433.
• Restart the service by selecting the "SQL Server Services" node in the left pane, selecting "SQL Server <edition name>" in the right pane, and choosing Restart from the Action menu (or use the Restart button on the toolbar).

• LabKey Server must be configured to use the jTDS JDBC driver for Microsoft SQL Server, which is included in the LabKey Server archive distribution. The template configuration for running against SQL Server with the jTDS driver is included in the LabKey Server configuration file. Documentation for this driver is available on SourceForge. Other JDBC drivers for Microsoft SQL Server have not been tested.
• If you are installing LabKey Server to run against an existing SQL Server database, you may want to set up a new login for LabKey Server to use:
• Run SQL Server Management Studio. Under Security->Logins, add a new login, and type the user name and password.
• Edit the database resource in the LabKey Server configuration file and specify the new user name and password (see Modify the Configuration File).

Install the LabKey Server System Components

1. Download the current binary zip distribution if you are installing on a Windows system, or the current binary tar.gz distribution file if you are installing on a Unix-based system.
2. Unzip the LabKey Server components to a directory on your computer. On Unix-based systems, the command tar xfz LabKey Server-bin.tar.gz will unzip and untar the archive. You will move these components later, so the directory you unpack them to is unimportant. After unpacking the directory should contain these files and directories:

• bin: binary files required by LabKey Server
• common-lib: required common library jars
• labkeywebapp: the LabKey Server web application
• modules: LabKey Server modules
• server-lib: required server library jars
• labkey.xml: LabKey Server configuration file
• README.txt: a file pointing you to this documentation.
• upgrade.sh: Linux upgrade script