Assumptions

This documentation will describe how to configure the LabKey Server Enterprise Pipeline to convert native instrument data files (such as .RAW) files to mzXML using the msconvert software that is part of ProteoWizard.

• The Conversion Server can be configured to convert from native acquisition files for a number of manufacturers.
• Use of a Shared File System: The LabKey Conversion server must be able to mount the following resources
• Pipeline directory (location where mzXML, pepXML, etc files are located)
• A version of Java compatible with your LabKey Server version is installed
• You have downloaded (or built from the Subversion source control system) the following files
• LabKey Server
• Labkey Server Enterprise Pipeline Configuration files

Download and Expand the LabKey Conversion Server Software

1. Create the <LABKEY_HOME> directory (LabKey recommends you use C:\labkey\labkey )
2. Unzip the LabKey Server distribution into the directory <LABKEY_HOME>\dist
3. Unzip the LabKey Server Pipeline Configuration distribution into the directory <LABKEY_HOME>\dist

Install the LabKey Software

Copy the following to the <LABKEY_HOME> directory:

• The directory <LABKEY_HOME>\dist\LabKeyX.X-xxxxx-Bin\labkeywebapp
• The directory <LABKEY_HOME>\dist\LabKeyX.X-xxxxx-Bin\modules
• The directory <LABKEY_HOME>\dist\LabKeyX.X-xxxxx-Bin\pipeline-lib
• The file <LABKEY_HOME>\dist\LabKeyX.X-xxxxx-Bin\tomcat-lib\labkeyBootstrap.jar

• All files in the directory <LABKEY_HOME>\dist\LabKeyX.X-xxxxx-PipelineConfig\remote

cd <LABKEY_HOME>
java -jar labkeyBootstrap.jar

In the System Control Panel, create the LABKEY_ROOT environment variable and set it to <LABKEY_HOME>. This should be a System Variable.

Create the Tools Directory

This is the location where the Conversion tools (msconvert.exe, etc) binaries are located. For most installations this should be set to <LABKEY_HOME>\bin

• Place the directory <LABKEY_HOME>bin directory on the PATH System Variable using the System Control Panel
• Copy the conversion executable files to <LABKEY_HOME>bin

Edit the Enterprise Pipeline Configuration File (pipelineConfig.xml)

The pipelineConfig.xml file enables communication with: (1) the the JMS queue, (2) the RAW files to be converted, and (3) the tools that perform the conversion.

An example pipelineConfig.xml File

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">

    <bean id="activeMqConnectionFactory" class="org.apache.activemq.ActiveMQConnectionFactory">
        <constructor-arg value="tcp://localhost:61616"/>
        <property name="userName" value="someUsername" />
        <property name="password" value="somePassword" />
    </bean>

    <bean id="pipelineJobService" class="org.labkey.pipeline.api.PipelineJobServiceImpl">
        <property name="workDirFactory">
            <bean class="org.labkey.pipeline.api.WorkDirectoryRemote$Factory">
                <!--<property name="lockDirectory" value="T:/tools/bin/syncp-locks"/>-->
                <property name="cleanupOnStartup" value="true" />
                <property name="tempDirectory" value="c:/temp/remoteTempDir" />
            </bean>
        </property>
        <property name="remoteServerProperties">
            <bean class="org.labkey.pipeline.api.properties.RemoteServerPropertiesImpl">
                <property name="location" value="mzxmlconvert"/>
            </bean>
        </property>

        <property name="appProperties">
            <bean class="org.labkey.pipeline.api.properties.ApplicationPropertiesImpl">
                <property name="networkDriveLetter" value="t" />
                <property name="networkDrivePath" value="\\someServer\somePath" />
                <property name="networkDriveUser" value="someUser" />
                <property name="networkDrivePassword" value="somePassword" />

                <property name="toolsDirectory" value="c:/labkey/build/deploy/bin" />
            </bean>
        </property>
    </bean>
</beans>

Enable Communication with the JMS Queue

<bean id="activeMqConnectionFactory" class="org.apache.activemq.ActiveMQConnectionFactory">
   <constructor-arg value="tcp://@@JMSQUEUE@@:61616"/>
</bean>

and change @@JMSQUEUE@@ to be the name of your JMS Queue server.

Configure the WORK DIRECTORY

The WORK DIRECTORY is the directory on the server where RAW files are placed while be converted to mzXML. There are 3 properties that can be set

• lockDirectory: This config property helps throttle the total number of network file operations running across all machines. Typically commented out.
• cleanupOnStartup: This setting tells the Conversion server to delete all files in the WORK DIRECTORY at startup. This ensures that corrupted files are not used during conversion
• tempDirectory: This is the location of the WORK DIRECTORY on the server

<property name="workDirFactory">
  <bean class="org.labkey.pipeline.api.WorkDirectoryRemote$Factory">
    <!-- <property name="lockDirectory" value="T:/tools/bin/syncp-locks"/> -->
    <property name="cleanupOnStartup" value="true" />
    <property name="tempDirectory" value="c:/TempDir" />
  </bean>
</property>

Configure the Application Properties

There are 2 properties that must be set

• toolsDirectory: This is the location where the Conversion tools (msconvert.exe, etc) are located. For most installations this should be set to <LABKEY_HOME>\bin
• networkDrive settings: These settings specify the location of the shared network storage system. You will need to specify the appropriate drive letter, UNC PATH, username and password for the Conversion Server to mount the drive at startup.

Change all values surrounded by "@@...@@" to fit your environment:

• @@networkDriveLetter@@ - Provide the letter name of the drive you are mapping to.
• @@networkDrivePath@@ - Provide a server and path to the shared folder, for example: \\myServer\folderPath
• @@networkDriveUser@@ and @@networkDrivePassword@@ - Provide the username and password of the shared folder.
• @@toolsDirectory@@ - Provide the path to the bin directory, for example: C:\labkey\bin

<property name="appProperties">
	<bean class="org.labkey.pipeline.api.properties.ApplicationPropertiesImpl">

		<!-- If the user is mapping a drive, fill in this section with their input -->
		<property name="networkDriveLetter" value="@@networkDriveLetter@@" />
		<property name="networkDrivePath" value="@@networkDrivePath@@" />
		<property name="networkDriveUser" value="@@networkDriveUser@@" />
		<property name="networkDrivePassword" value="@@networkDrivePassword@@" />

		<!-- Enter the bin directory, based on the install location -->
		<property name="toolsDirectory" value="@@toolsDirectory@@" />
	</bean>
</property>

Edit the Enterprise Pipeline MS2 Configuration File (ms2Config.xml)

The MS2 configuration settings are located in the file <LABKEY_HOME>\config\ms2Config.xml

An example configuration for running msconvert on a remote server named "mzxmlconvert":

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">

    <bean id="ms2PipelineOverrides" class="org.labkey.api.pipeline.TaskPipelineRegistrar">
        <property name="factories">
            <list>
                <!-- This reference and its related bean below enable RAW to mzXML conversion -->
                <ref bean="mzxmlConverterOverride"/>
            </list>
        </property>
    </bean>

    <!-- Enable Thermo RAW to mzXML conversion using msConvert. -->
    <bean id="mzxmlConverterOverride" class="org.labkey.api.pipeline.cmd.ConvertTaskFactorySettings">
        <constructor-arg value="mzxmlConverter"/>
        <property name="cloneName" value="mzxmlConverter"/>
        <property name="commands">
            <list>
                <ref bean="msConvertCommandOverride"/>
            </list>
        </property>
    </bean>

    <!-- Configuration to customize behavior of msConvert -->
    <bean id="msConvertCommandOverride" class="org.labkey.api.pipeline.cmd.CommandTaskFactorySettings">
        <constructor-arg value="msConvertCommand"/>
        <property name="cloneName" value="msConvertCommand"/>
        <!-- Run msconvert on a remote server named "mzxmlconvert" -->
        <property name="location" value="mzxmlconvert"/>
    </bean>
</beans>

Install the LabKey Remote Server as a Windows Service

LabKey uses procrun to run the Conversion Service as a Windows Service. This means you will be able to have the Conversion Service start up when the server boots and be able to control the Service via the Windows Service Control Panel.

Set the LABKEY_ROOT Environment Variable.

In the System Control Panel, create the LABKEY_ROOT environment variable and set it to <LABKEY_HOME> (where <LABKEY_HOME> is the target install directory). This should be a System Environment Variable.

Install the LabKey Remote Service

• Copy *.exe and *.bat from the directory <LABKEY_HOME>\dist\LabKeyX.X-xxxxx-PipelineConfig\remote to <LABKEY_HOME>\bin
• For 32-bit Windows installations, install the service by running the following from the Command Prompt:

set LABKEY_ROOT=<LABKEY_HOME>
<LABKEY_HOME>\bin\installServiceWin32.bat

• For 64-bit Windows installations, install the service by running the following from the Command Prompt:

set LABKEY_ROOT=<LABKEY_HOME>
<LABKEY_HOME>\bin\installServiceWin64.bat

where <LABKEY_HOME> is the directory where labkey is installed. For example, if installed in c:\labkey\labkey, then the command is

set LABKEY_ROOT=c:\labkey\labkey

If the command succeeded then it should have created a new Windows Service named LabKeyRemoteServer

How to Uninstall the LabKey Remote Pipeline Service

• For 32-bit Windows installations, run the following:

<LABKEY_HOME>\bin\service\removeServiceWin32.bat

• For 64-bit Windows installations, run the following:

<LABKEY_HOME>\bin\service\removeServiceWin64.bat

To Change the Service:

• Uninstall the service as described above.
• Reboot the server.
• Edit <LABKEY_HOME>\bin\service\installServiceWin32.bat or <LABKEY_HOME>\bin\service\installServiceWin64.bat as appropriate, and make the necessary changes and run

<LABKEY_HOME>\bin\service\installService.bat

How to Manage the LabKey Remote Windows Service

How to start the service:

From the command prompt you can run

net start LabKeyRemoteServer

How to stop the service:

From the command prompt you can run

net start LabKeyRemoteServer

Where are the Log Files Located

All logs from the LabKey Remote Server are located in <LABKEY_HOME>\logs\output.log

NOTE: If running Windows, this service cannot be run as the Local System user. You will need to change the LabKey Remote Pipeline Service to log on as a different user.