Topic: caArray Installation and Upgrade
Release: caArray v2.4.1.1 and higher
Date entered: 01/17/2012
Below is a step-by-step illustrated tutorial on how to build the application from source. It covers the following:
The tutorial is designed for use in a Windows environment, but can easily be adapted to work in Linux as well.
|
Due to recent changes in the NCI caArray source code repository, the process described in this tutorial only applies to v2.4.1.1, which is the latest version as of this writing. |
|
This tutorial is based on the readme.txt file in the NCI caArray source code repository at https://ncisvn.nci.nih.gov/svn/caarray2/tags/2.4.1.1/. |
1) Before proceeding to check out the code, ensure that the following are already installed on your machine:
http://download.oracle.com/otn/java/jdk/1.5.0_22/jdk-1_5_0_22-windows-i586-p.exe
|
The build process described in this tutorial only works with version 1.5 of the JDK; it will not work with any other versions, earlier or later. |
http://mirrors.ibiblio.org/apache//ant/binaries/apache-ant-1.8.3-bin.zip
http://filehippo.com/download/file/3518c972e6317bff1a5caacae83b83cf1057fceca08180ebd44ad9a0ba01444b/
http://www.open.collab.net/servlets/OCNDirector?id=CSVN1.7.4WINC32 (registration required)
2) Once all the above are installed, ensure they are configured as follows:
C:\Program Files\Java\jdk1.5.0_22\bin
C:\ant
C:\Program Files\CollabNet Subversion Client
To begin checking out the caArray source code from the NCI repository, first create a new folder (i.e., C:\source), then open up a command-line window, navigate to that folder, and enter the following:
svn checkout https://ncisvn.nci.nih.gov/svn/caarray2/tags/2.4.1.1/ |
The source files will then begin downloading from the repository server into the folder you created. Depending on the speed of your Internet connection, it may take over half an hour for the checkout to complete, as the source contains thousands of files distributed over hundreds of folders.
You'll know when the checkout is complete when the command-line window shows a message stating, 'Checked out revision x', where x is the revision number, as shown in the screenshot below:
It is possible to have Ant automatically generate the empty database schema required for the caArray installation. However, it is preferred to create these schema manually via the MySQL command line client.
Before doing so, you will need to derive a name for the database caArray will use to store genomic data, as well as a username and password for the user who is granted access to that database. In this example, the database name is db1, the username is user1, and the password name is password1.
Now, log into the client using the root password you set when installing the database server, then enter the following SQL commands line-by-line, substituting your own database name, username, and password as needed:
CREATE DATABASE db1 DEFAULT CHARACTER SET latin1; GRANT ALL ON db1.* TO 'user1'@'localhost' IDENTIFIED BY 'password1' WITH GRANT OPTION; GRANT ALL ON db1.* TO 'user1'@'%' IDENTIFIED BY 'password1' WITH GRANT OPTION; |
|
The single quotes around the username and password in the code snippet above are not optional and can not be omitted -- they are part of the MySQL syntax. |
The client will respond with a confirmation that the issued queries were successful, as shown in the screenshot below:
The caArray installation settings are mainly specified by a source file, install.properties, whose path is:
$CAARRAY_HOME/software/master_build/install.properties
where $CAARRAY_HOME represents the root folder into which the caArray source was checked out (C:\source in this example).
A second file, local.properties, specifies additional settings. This file is not included in the repository -- you must manually create it yourself by opening a plain text editor and saving a blank file with the filename local.properties to the following path:
$CAARRAY_HOME/software/build/local.properties
These files must be customized with the settings specific to your local environment before starting the build process. These settings include:
The install.properties file contains several other properties aside from the ones listed above, but these others do not need to be customized and can be left at their default values.
The blank local.properties file you created previously must be populated with all the properties listed above and their respective values, plus an additional field, jboss.home, which specifies the name of the subfolder within the root installation folder to which the JBoss server will be installed. The value of the jboss.home property is derived from the value of the application.base.path property in install.properties, with the text '\jboss-4.0.5.GA' appended. For example, if the value of the application.base.path property is C:\caArray, then the corresponding value of the jboss.home property would be C:\caArray\jboss-4.0.5.GA.
Refer to the screenshot below for an example of how the local.properties file should be configured:
|
The install.properties file contains additional properties which pertain to grid services. These are not covered here, as configuring caArray to utilize a grid service is beyond the scope of this tutorial. For more information, please refer to this KB article:
|
Now that you've checked out the source code, created the database schema, and configured the properties files, you're now ready to start the actual build process. First, open a command-line window and navigate to the following path:
$CAARRAY_HOME/software/master_build
Then, enter the following command:
ant -Dproperties.file=<absolute path to install.properties file> deploy:local:install |
For example, if the path to the install.properties file is:
C:\source\2.4.1.1\software\master_build\install.properties
Then the command is:
ant -Dproperties.file=C:\source\2.4.1.1\software\master_build\install.properties deploy:local:install |
The amount of time needed for the build process to complete can vary anywhere from 30 minutes to several hours depending on your hardware configuration. For reference, on a Dell Optiplex 765 Windows XP Professional workstation with a Core 2 Quad 6600 CPU running at 2.40 Ghz and approximately 1.75 GB of memory available at the time of the build, the process took 4 hours, 16 minutes and 51 seconds. The screenshot below shows the command line window after the build process has completed successfully.
|
Even if the command line window shows a 'BUILD SUCCESSFUL' message at the end, it is still possible that the build process did not complete successfully. The build process launches several sub-processes, each of which must complete successfully in order for the entire build to complete successfully. If any one of these sub-processes fails, it will display its own 'BUILD FAILED' error message, but the overall build process may still display the 'BUILD SUCCESSFUL' message at the end. The screenshot below illustrates such a case in which a sub-process failed due to an incorrect version of the JDK installed; note the indented 'BUILD FAILED' error message (highlighted in red) several lines above the 'BUILD SUCCESSFUL' message (highlighted in yellow) at the bottom. |
Please leave your comment in the caArray End User Forum.