Installing GenePattern from a WAR File


Installation of GenePattern is typically done using the InstallAnywhere installer that is available from the GenePattern web site (http://genepattern.org/download). For some installations, this is not an option however such as when the platform is not supported (anything other than Windows, Linux and Macintosh) or if the desire is to install into an existing web server and not use the Apache Tomcat installation created by the installer. In these situations, an alternative is to install GenePattern from a WAR file (Web ARchive). WAR files are a standard distribution mechanism for web applications. Since GenePattern typically installs more than just the web application and since it needs to perform tasks beyond those typical of a web application, installing GenePattern from a web-archive involves several additional steps beyond deploying the WAR file.

The GenePattern installer typically installs the following components onto a computer:

  • Apache Tomcat web server
  • R programming language Environment (Windows, Mac)
  • Perl interpreter (Windows)

In addition to the installations, the installer typically customizes the following files for the installation:

  • GenePatternServer/resources/genepattern.properties
  • GenepatternServer/resources/omnigene.properties
  • GenePatternServer/Tomcat/webapps/gp/WEB-INF/web.xml
  • GenePatternServer/Tomcat/webapps/gp/WEB-INF/classes/log4j.properties

Finally, the installer also creates applications to start and stop the GenePattern server and optionally creates shortcuts to these applications as well as to the web applications home page in the users selected directory.

When installing GenePattern from a WAR file, it is necessary to make these installations and customizations to the contents of the WAR file before it can be usefully installed into an existing web server. Shortcuts and Start/Stop applications will need to be created by hand if they are desired and do not already exist for the web server the WAR file is installed into.

At runtime, the GenePattern server must launch processes running java, Perl and R. In order to do this, the server requires information about the local file system beyond what is packaged in the WAR file.

To simplify the task of customizing the WAR file, an ant build script is provided with the WAR file that will perform the file customizations based on values provided by the installing user.

Upgrading a Current Installation

The WAR file installation does not provide the option of upgrading from a current GenePattern installation. It creates a new GenePattern installation.

  • To preserve GenePattern configuration settings from your current installation, create backup copies of the following GenePattern configuration files: genepattern.properties, permissionMap.xml, and userGroups.xml configuration files. After installing the new version of GenePattern, compare the backup files with the newly installed files and modify the new files as necessary. Do not replace the newly installed configuration files with the backup copies.
  • To preserve custom pipelines, suites, and modules, export them from your current GenePattern installation. After installing the new version of GenePattern, install the exported pipelines, suites and modules. Pipelines, suites and modules installed from the GenePattern module repository do not need to be exported. You can install them from the GenePattern module repository after installing the new version of GenePattern.

Note: GenePattern 3.1 and later uses R2.5. GenePattern 3.0 used R2.0.1. To ensure that you have access to GenePattern modules written for either R2.0.1 or R2.5, install R2.5 without overwriting your R2.0.1 installation. For a list of the R-based GenePattern modules, see GenePattern 3.1 Release Notes.

Requirements

Before customizing and installing the GenePattern WAR file into an existing web server, the following applications and libraries must be installed on the target computer:

Component Version Web site
Perl 5.8.8+ http://www.activestate.com/Products/ActivePerl/
Java JRE 1.6.* http://java.sun.com
ant 1.7.0+ http://ant.apache.org/
R (optional) 2.5.0 http://www.r-project.org/
Tomcat (if necessary) 5.5+ http://tomcat.apache.org/

Before running the customization script, you must have the Java and ant executables on your path.

You will also need the WAR file, gp_war.zip.

Typographical Conventions

Values you are expected to type are in

Courier – Blue 12pt

Responses and prompts from the ant script are in

Courier New -- Grey 10pt

Installation Overview

  1. Install Perl.
  2. Install Java JRE.
  3. Install R (optional).

If R is not installed, GenePattern will still run but you will not be able to install any R-based tasks such as SVM.

  1. Install (if necessary) the web server into which you will deploy GenePattern. If you are using Apache Tomcat, you can use the base distribution; Tomcat does not need to installed as a service.
  2. Customize the WAR file (see the “Customizing GenePattern” section below).
  3. Deploy the GenePattern install directory.
  4. Deploy the WAR file or customized gp directory into your web server following the instructions for the web server you are using.
  5. Install tasks.
  6. Test the installation.

Customizing GenePattern

Customization of GenePattern will be performed by an ant build file customizeWar.xml, that is provided in the gp_war.zip file.

Unzip gp_war.zip into a temporary directory

> cp gp_war.zip tempdir

> cd tempdir

> unzip gp_war.zip

Test that ant is installed and has the necessary version

>ant –version

Apache Ant version 1.7.0 compiled on December 13 2006

Run the customizing ant build file

>ant –buildfile customizeWar.xml

C:\Temp\war>ant -buildfile customizeWar.xml

Buildfile: customizeWar.xml

 

getLocalValues:

 

This will begin running an ant task that will query you for the information necessary to customize GenePattern to your environment. At the end of data entry, you will be given an opportunity to accept or cancel the installation before any files are modified. If you accept the changes and later wish to change something, you will either need to edit the GenePattern configuration files by hand or return to a freshly unzipped version of the WAR file as the ant script can only be run on an unmodified version of the WAR file.

For any prompts that present a default value, you may hit return to accept the default value without changing it.

Provide the hostname

Ant will prompt you for the hostname of the computer. Enter just the name and not the full canonical hostname of the computer (e.g. computerX not computerX.broadinstitute.org)

[input] Host name: (name only, don't include full domain)

ComputerX

Provide the Domain name

Enter the domain of this computer or this site. This value will be used for later properties such as the webmaster email address and LSID Authority.

 

[input] Domain:

broadinstitute.org

Provide the WebMaster email address

This is the email address that will be notified of problems in the GenePattern server. It is displayed on several pages in the web application. Hitting return without entering anything will accept the default value.

[input] webmaster username (default=ted@broadinstitute.org):

webmaster@broadinstitute.org

 

Provide the WebServer port

GenePattern will use this to construct URLs. Use the port for the web server you into which you will deploy. For most installations the default of 8080 can be accepted.

[input] webserver port (default=8080):

8080

Provide the HSQL port

This is the port used by GenePattern’s HSQL database. For most installations the default of 9001 can be accepted.

[input] HSQL port (default=9001):

9001

Provide the Java home path

This will default to the java VM used to run ant. For GenePattern, the JAVA_HOME variable must point to a Java 1.6 installation such as JDK1.6.0.

[input] JAVA_HOME (default=C:\Program Files\Java\jre1.6.0_21\jre):

c:/program files/java/jre1.6.0_21

Provide the R directory

This is the path to your installation of the R programming environment.

[input] R directory (no default):

c:/r/r-2.5.0

Provide the Perl directory

This is the path to the installation of Perl GenePattern should use to execute perl-based modules.

[input] Perl directory (no default):

c:/perl/bin

Set the purge jobs delay

This is the number of days that files created during execution of a task will be kept on the server. When files are older than this number of days they will be deleted to save space on the server.

[input] # days to hold data before purging (default=7):

7

Set the purge time

This is the time of day that the files will be purged. Format is HH:MM using the 24 hour clock.

[input] time of day to run job purge (default=23:00):

23:00

Set the LSID Authority

The LSID authority is a unique name used to identify any modules that are created or modified on this server. It must be unique for each GenePattern server instance. It is highly recommended that you accept the default value for this which is a combination of the port, username and fully specified computer name.

[input] LSID Authority (default=7001.ted.computerX.broadinstitute.org):

7001.ted.computerX.broadinstitute.org

Provide the full path to the gpinstall directory

This is the directory where the GenePattern will have files outside of the web application. Do not use the default value, which is the temporary directory. Enter a fully qualified path to a directory on the GenePattern server. This folder is customized during the running of this ant file and must be accessible by the web server.

[input] GenePattern Server root directory (default=C:\Temp\gpinstall):

C:/GenePatternFiles

Provide a SMTP mail server

This is the server GenePattern will use to e-mail to users; for example, on request, GenePattern sends an e-mail notification to the user when a job completes.

[input] SMTP Mail Server (default=autodetect at runtime):

Review the information

The values you have entered will be presented to you for review before proceeding. If you accept them (‘y’) the WAR file will be customized. If you reject them (‘n’) the installation will be cancelled without changing any files.

echoLocalValues:

[echo] =========================================

[echo] Customized values:

[echo]

[echo]

[echo] Host=ComputerX.broadinstitute.org

[echo] WebMaster= genepattern@broadinstitute.org

[echo] Webserver Port= 8080

[echo] HSQL port= 9001

[echo] Java= c:/program files/java/jre1.6.0_21

[echo] R= c:/r/r-2.5.0

[echo] Perl= c:/perl/bin

[echo] Job Purge= at 23:00 after 7 days

[echo] LSID Authority= 7001.ted.computerX.broadinstitute.org

[echo] GenePattern Server root directory= C:/GenePatternFiles

[echo] SMTP Server=imap.broadinstitute.org

[echo]

[echo] =========================================

confirmLocalValues:

[input] Accept these values and continue? (y,n)

Y

Customization performed

unzip:

[unzip] Expanding: C:\Temp\war\gp.war into C:\Temp\war\gp

customizeWar:

[copy] Copying 1 file to C:\Temp\war\gpinstall\resources

addSmtpServer:

[copy] Copying 1 file to C:\Temp\gpinstall\resources

[war] Building war: C:\Temp\gp.war.customized

BUILD SUCCESSFUL

Deploy GenePattern install directory

At this point, your temp directory will contain a directory named ‘gpinstall’. The contents of this directory must be moved to the location provided as the GenePattern Server root directory.

Deploy the WAR file

Your temp directory will also contain a directory named ‘gp’ and a WAR file called gp.customized.war which you can deploy to your web server following the conventions for your web server. Deploying GenePattern requires a few additional steps:

  1. Unzip the WAR file into the webapps directory. GenePattern cannot be run directly from the WAR file; it must be unzipped. For example, if you are using Tomcat, unzip the WAR file into the Tomcat/webapps/gp directory:

    > cd Tomcat\webapps

    > mkdir gp

    > cd gp

    > jar xvf c:\tempdir\gp.customized.war

  2. Copy the commons-codec-1.3.jar and commons-httpclient-3.0.1.jar from the Tomcat/webapps/gp/WEB-INF/lib/ folder to the Tomcat/webapps/gp/downloads/ folder. Both .jar files must be in both directories.
  3. If your web server is Tomcat 6, remove the following three libraries from the Tomcat/webapps/gp/WEB-INF/lib folder: el-api.jar, xercesImpl.jar, and xml-apis.jar.
  4. Update the files required by visualizer modules by copying the following files from the GenePattern public server to the Tomcat/webapps/gp/downloads/ folder:

    http://genepattern.broadinstitute.org/gp/downloads/runVisualizer.jar
    http://genepattern.broadinstitute.org/gp/downloads/commons-codec-1.3.jar
    http://genepattern.broadinstitute.org/gp/downloads/commons-httpclient.jar
    http://genepattern.broadinstitute.org/gp/downloads/GenePattern.zip
    http://genepattern.broadinstitute.org/gp/downloads/GenePatternMatlab.zip
    http://genepattern.broadinstitute.org/gp/downloads/GenePattern_1.0.2.tar.gz
    http://genepattern.broadinstitute.org/gp/downloads/GenePattern_1.0.2.tgz
    http://genepattern.broadinstitute.org/gp/downloads/GenePattern_1.0.2.zip

  5. Edit the genepattern.properties file (e.g. C:/GenePatternFiles/resources/genepattern.properties).
    1. Add the following command:

      redirect.to.fq.host=false
    2. Find and edit the following settings using the hostname (e.g. ComputerX) and domain (e.g. broadinstitute.org) that you specified when customizing the build file:

      GenePatternURL=http://ComputerX.broadinstitute.org:8080//gp//
      #fullyQualifiedHostName=ComputerX
      #fqHostName=ComputerX
    3. To correctly run modules implemented in R, edit the webappDir and run_r_path variables. Set the webappDir variable to the full path of the gp folder on your web server. Set the run_r_path variable to the value shown below.

      webappDir=c\:/program files/Tomcat/webapps/gp
      run_r_path=/WEB-INF/classes/
  6. Start the web server. If you are using Tomcat, start the Tomcat server from the working directory rather than the bin subdirectory. For example:

    > cd Tomcat

    > bin\tomcat6

Set canonical host name (optional)

If you will be accessing a GenePattern server that is referenced by more than one hostname (for example, www.myhost.com:8080/gp and myhost:8080/gp), modify the $GenePatternServer$/resources/genepattern.properties file, as described in FAQ 3.5. This enables successful login to the GenePattern server from hosts that are in different domains or subdomains, where the simple server name (eg. "myhost") is not a local host name.

Register

Once the WAR file is deployed to your web server, complete the installation by connecting to the GenePattern web application at the installFrame.jsp page:

http://ComputerX.broadinstitute.org:8080/gp/installFrame.jsp

The first time the GenePattern server is launched, the GenePattern Registration page will appear in your browser. Fill out the registration form, read the license agreement, and click the I Agree button at the bottom of the form.

Install Tasks

When you have completed and submitted the registration form, the GenePattern Configuration page appears. This page guides you through the final steps of installation:

  1. View the server installation report. Note: The screen indicates that the log file cannot be found because the WAR file installation does not have a server installation log.
  2. Install modules.
  3. Install the Desktop Client (optional). You may want to skip this step. You can easily install the Desktop Client later from the GenePattern Web Client (simply click Downloads>Install Desktop Client).
  4. Download sample datasets.
  5. Login and begin using GenePattern.

Test the Installation

To test the installation, the following tests are suggested.

  1. Login and view the home page.
  2. Run a java task (e.g. PreprocessDataset).
  3. Run a visualizer (e.g. HeatMapViewer).
  4. Run a perl task (e.g. ConvertLineEndings).
  5. Run an R task (if R is installed) (e.g. SVM).
  6. View a pipeline.
  7. Edit/Create a pipeline.
  8. Run a pipeline.

Once the installation has been completed and tested you are done. If you choose to move folders or locations in the future, you may do so by editing the file paths in the install directory/resources or by re-running the ant task.

Appendix A: Rerunning the WAR customization utility

The first time you run the customizeWar.xml ant file, it will create a properties file containing the values you provided. Should you need to run it subsequently you may skip the data entry portion by editing the file customizeWar.properties to your new values and providing it to and using the –propertyfile flag.

e.g.

>ant –buildfile customizeWar.xml –propertyfile customizeWar.properties