Configure LabKey Server to use the Enterprise Pipeline

Documentation
Before performing the tasks below, you must: Install Prerequisites for the Enterprise Pipeline.

This page explains how to

  • Configure the LabKey Server to use the Enterprise Pipeline
  • Create the LabKey Tool directory (which contains the MS1 and MS2 analysis tools to be run on the cluster execution nodes)

Assumptions

The Enterprise Pipeline does not support all possible configurations of computational clusters. It is currently written to support a few select configurations. The following configurations are supported

  • Use of a Network File System: The LabKey web server, LabKey Conversion server and the cluster nodes must be able to mount the following resources
    • Pipeline directory (location where mzXML, pepXML, etc files are located)
    • Pipeline Bin directory (location where third-party tools (TPP, Xtandem, etc) are located.
  • MS1 and MS2 analysis tools will be run on either a PBS or SGE based cluster.
  • Java 8 or greater is installed on all cluster execution node
  • You have downloaded or built from the subversion tree the following files
    • LabKey Server Enterprise Edition v8.3 or greater
    • Labkey Server v8.3 Enterprise Pipeline Configuration files

Verify the Version of your LabKey Server.

The Enterprise Pipeline is supported in the LabKey Server Enterprise Edition v8.3 or greater.

To verify if you are running the Enterprise Edition follow the instructions below

  1. Log on to your LabKey Server using a Site Admin account
  2. Open the Admin Console
  3. Under the Module Information section verify that the following modules are installed
    • BigIron
If the BigIron module is not installed on your server, then please send an email to support@labkey.com requesting an upgrade to the Enterprise Edition.

Enable Communication with the ActiveMQ JMS Queue.

You will need to add the following settings to the LabKey configuration file (labkey.xml). This is typically located at <CATALINA_HOME>/conf/Catalina/localhost/labkey.xml

<Resource name="jms/ConnectionFactory" auth="Container"
type="org.apache.activemq.ActiveMQConnectionFactory"
factory="org.apache.activemq.jndi.JNDIReferenceFactory"
description="JMS Connection Factory"
brokerURL="tcp://@@JMSQUEUE@@:61616"
brokerName="LocalActiveMQBroker"/>

You will need to change setting for brokerURL to point to the location of your ActiveMQ installation. (i.e. replace @@JMSQUEUE@@ with the hostname of the server running the ActiveMQ software)

Note: If this is a new installation of the LabKey server and are not an upgrade of the current installation, then the XML above will be located in the labkey.xml file, but will be commented out. Uncomment out the XML in the file instead of performing at cut and paste of the text above.

Set the Enterprise Pipeline configuration directory (Optional)

By default, the system looks for the pipeline configuration files in the following directory: LABKEY_HOME/config.

To specify a different location, add the following parameter to the LabKey configuration file (labkey.xml, typically located at <CATALINA_HOME>/conf/Catalina/localhost/labkey.xml), for example:

<Parameter name="org.labkey.api.pipeline.config" value="C:/path-to-config"/>

Set this to the location of your Enterprise Pipeline configuration directory.

Note: If this is a new installation of the LabKey server and not an upgrade of the current installation, then the XML above will be located in the labkey.xml file, but will be commented out. Uncomment out the XML in the file instead of performing at cut and paste of the text above.

Create the Enterprise Pipeline Configuration Files for the Web Server.

  1. Unzip LabKey Server Enterprise Pipeline Configuration distribution and copy the webserver configuration files to the Pipeline Configuration directory specified in the last step (ie <LABKEY_HOME>/config)
  2. Configuration files.
    • ms2config.xml: This is used to configure
      • where MS2 searches will be performed (on the cluster, on a remote server or locally)
      • where the Conversion of raw files to mzXML will occur (if required)
      • which analysis tools will be executed during a MS2 search
    • ms1config.xml: This is used to configure
      • where MS1 searches will be performed (on the cluster, on a remote server or locally)
      • which analysis tools will be executed during a MS1 search
  1. Edit the file ms2Config.xml
    • Documentation is under development.
  1. Edit the file ms1Config.xml
    • Documentation is under development.

Restart the LabKey Server

In order for the LabKey Server to use the new Enterprise Pipeline configuration settings, the Tomcat process will need to be restarted.

Once the server has been restarted. You will want to ensure that the server the server started up with no errors.

  1. Log on to your LabKey Server using a Site Admin account
  2. Open the Admin Console: Admin -> Site -> Admin Console.
  3. In the Diagnostics Section click on view all site errors
  4. Check to see that no errors have occurred after the restart

Create the LABKEY_TOOLS Directory that will be Used on the Cluster.

The <LABKEY_TOOLS> directory will contain all the files necessary to perform the MS2 searches on the cluster execution nodes. This directory must be accessible from all cluster execution nodes. We recommend that the directory be mounted on the cluster execution nodes as well as the Conversion Server. The directory will contain

  • Required LabKey software and configuration files
  • TPP tools
  • XTandem search engine
  • msInspect
  • Additional MS1 and MS2 analysis tools

Create the <LABKEY_TOOLS> Directory

Create the <LABKEY_TOOLS> directory.

  • This directory must be accessible from all cluster execution nodes.
  • We recommend that the directory created on Shared File System which will be mounted on the cluster nodes as well as the Conversion Server.

Download the Required LabKey Software

  1. Unzip the LabKey Server Enterprise Edition distribution into the directory <LABKEY_TOOLS>/labkey/dist
  2. Unzip the LabKey Server Pipeline Configuration distribution into the directory <LABKEY_TOOLS>/labkey/dist/conf
NOTE: For the next section you will need to know path to the <LABKEY_TOOLS>/labkey directory and the <LABKEY_TOOLS>/external directory on the cluster execution nodes.

Install the LabKey Software into the <LABKEY_TOOLS> Directory

Copy the following to the <LABKEY_TOOLS>/labkey directory

  • The directory <LABKEY_TOOLS>/labkey/dist/LabKey<VERSION>-Enterprise-Bin/labkeywebapp
  • The directory <LABKEY_TOOLS>/labkey/dist/LabKey<VERSION>-Enterprise-Bin/modules
  • The directory <LABKEY_TOOLS>/labkey/dist/LabKey<VERSION>-Enterprise-Bin/pipeline-lib
  • The file <LABKEY_TOOLS>/labkey/dist/LabKey<VERSION>-Enterprise-Bin/tomcat-lib/labkeyBootstrap.jar
Expand all modules in the <LABKEY_TOOLS>/labkey/modules directory by running:

cd <LABKEY_TOOLS>/labkey/
java -jar labkeyBootstrap.jar

Install Enterprise Pipeline Configuration Files into the <LABKEY_TOOLS> Directory

Copy the following to the <LABKEY_TOOLS>/labkey/config directory

  • All files in the directory <LABKEY_TOOLS>/labkey/dist/LabKey8.3-xxxxx-PipelineConfig/cluster

Create the Enterprise Pipeline Configuration Files for use on the Cluster

  1. There are 3 configuration files.
    • Description of configuration files is under development.
  1. Edit the file pipelineConfig.xml
    • Documentation is under development.
  1. Edit the file ms2Config.xml
    • Documentation is under development.
  1. Edit the file ms1Config.xml
    • Documentation is under development.

Install the MS1 and MS2 Analysis Tools on the Cluster

These tools will be installed in the <LABKEY_TOOLS>/bin directory.

Documentation is under development

Test the Configuration

There are a few simple tests that can be performed at this stage to verify that the configuration is correct. These tests are focused on ensure that a cluster node can perform an MS1 or MS2 search

  1. Can the cluster node see the Pipeline Directory and the <LabKey_Tools> directory
    • Test under development
  1. Can the cluster node execute Xtandem
    • Test under development
  1. Can the cluster node execute the java binary
    • Test under development
  1. Can the cluster node execute a Xtandem search against an mzXML file located in the Pipeline Directory?
    • Test under development
  1. Can the cluster node execute a PeptideProphet search against the resultant pepXML file
    • Test under development
  1. Can the cluster node execute the Xtandem search again, but this time using the LabKey java code located on the cluster node
    • Test under development
Once all these test are successful, you will have a working Enterprise Pipeline. The next step is to configure a new Project on your LabKey Server and configure the Project's pipeline to use the Enterprise Pipeline.

Discussion

previousnext
 
expand all collapse all