 |
Installation of GenePattern is typically done using the InstallAnywhere installer that is available from the GenePattern web site (http://www.broad.mit.edu/cancer/software/genepattern). 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:
In addition to the installations, the installer typically customizes the following files for the installation:
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.
The WAR file installation does not provide the option of upgrading from GenePattern 3.0 to GenePattern 3.1. It creates a new GenePattern 3.1 installation.
GenePattern 3.1 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.
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.5.* | http://java.sun.com |
| ant | 1.7.0+ | http://ant.apache.org/ |
| R (optional) | 2.5.0 | http://www.r-project.org/ |
| Web server |
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.
Values you are expected to type are in
Courier – Blue 12pt
Responses and prompts from the ant script are in
Courier New -- Grey 10pt
If R is not installed, GenePattern will still run but you will not be able to install any R-based tasks such as SVM.
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
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.broad.mit.edu)
[input] Host name:
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:
broad.mit.edu
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@broad.mit.edu):
webmaster@broad.mit.edu
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. Change this if a different version of java is to be used to execute GenePattern modules.
[input] JAVA_HOME (default=C:\Program Files\Java\jre1.5.0_13):
Provide the R directory
This is the path to your installation of the R programming environment.
[input] R directory (no default):
PathToR
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):
PathToPerl
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=
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.broad.mit.edu):
7001.ted.computerX.broad.mit.edu
Provide the full path to the gpinstall directory
This is the directory where the GenePattern will have files outside of the web application. This path needs to be a fully qualified path to the directory on the GenePattern server where the contents of the gpinstall folder will be placed. This folder is customized during the running of this ant file. The directory should accessible by the web server as file uploads and log files located here are made available through the web server.
[input] Installation directory (default=C:\Temp\gpinstall):
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.broad.mit.edu
[echo] WebMaster= genepattern@broad.mit.edu
[echo]
[echo] HSQL port= 9001
[echo] Java= C:/Program Files/Java/jre1.5.0_13
[echo] R= C:/Program Files/R/R-2.5.0
[echo] Perl= C:/Perl
[echo]
Job Purge= at
[echo] LSID Authority= 7001.ted.computerX.broad.mit.edu
[echo] Installation directory= C:/Temp/gpinstall
[echo] SMTP Server=imap.broad.mit.edu
[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:Tempgpinstall esources
[war] Building war: C:Tempgp.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 installation directory.
Deploy the WAR file
Your temp directory will also contain a directory named ‘gp’ and a WAR file called gp.war.customized which you can deploy to your web server following the conventions for your web server. Deploying GenePattern requires a few additional steps:
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.
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://localhost: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.
When you have completed and submitted the registration form, the GenePattern Configuration page appears. This page guides you through the final steps of installation:
To test the installation, the following tests are suggested.
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.
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