Table of Contents

  1. Acquire the VM
    1. VMX Image
    2. OVF Image
  2. Configure the VM
    1. Network Configuration
    2. VMWare Tools Configuration
    3. Change System Passwords
    4. Reboot the VM
  3. Build caTissueSuite Web Application
    1. Post Install
    2. Start the Web App JBoss Container
    3. Access the Web App
  4. Build caTIES
  5. Build caTissueSuite Data Service
    1. Build caGrid-1.2
    2. Install caTissueSuite Data Service
    3. Advertising the Grid Service
    4. Start the Data Service JBoss Container
    5. Access the Data Service
    6. Diagnostics Checks for Grid Services
  6. References

caTissueSuite Production VM Release Notes

The following steps describe how to install the caTissueSuite production virtual machine.

Acquire the VM

  • Download the vm image tarball to the VM image hosting location on your platform. There are two VM formats to choose from. One is a compressed form of the .vmx, (caTissueSuite-Production-01-VMX.tar.gz), which has to be converted to ESXi compatible with VMware-Converter Client. Another has already been converted from .vmx to .ovf (CaTissueSuite-Production-01-OVF.tar.gz), which is ESXi compatible. This version can be extracted and directly deployed on the ESXi server.

VMX Image

  • Download the .vmx format vm 
    wget http://138.26.125.70/vm/caTissueSuite-Production-01-VMX.tar.gz
  • Unpack the .vmx image 
    tar -xzf caTissueSuite-Production-01-VMX.tar.gz
  • This will create a directory caTissueSuite-Production-01 that contains the VM description file CaTissueSuite-Production-01.vmx.
  • Convert the .vmx to ESXi compatible with VMware-Converter
  • Add this to your VM collection by opening the vmx file via your VM console interface

OVF Image

  • Download the .ovf format vm 
    wget http://138.26.125.70/vm/caTissueSuite-Production-01-OVF.tar.gz
  • Unpack the .ovf image 
    tar -xzf caTissueSuite-Production-01-OVF.tar.gz
  • This will create a directory caTissueSuite-Production-01-OVF that contains the VM description file caTissueSuite-Production-01-OVF.ovf.
  • Add this to your VM collection by opening the ovf file via your VM console interface

Configure the VM

In order to configure the VM, it's necessary to first boot into single user mode in order to customize the IP address and host name configuration for your environment.

  • Start the newly loaded VM
  • At the Grub boot prompt press ESC to stop the default boot process
    • Press e to edit the selected (default) boot entry
    • Scroll to the line that begins with kernel and press e to edit the boot parameters
    • Add the word single, just after rhgb and not at the end of the boot arguments
    • Press enter to save the changes
    • Press b to begin the boot process
  • The VM will complete the boot into single user mode and present a command-line for root. It is now ready for the following configuration steps.

Network Configuration

Change the IP address and host name at the following locations

  • /etc/hosts (ip addr + hostname). Replace the second line in /etc/hosts with your new ip address and host name such as: 
    123.45.67.89          catissue.uabgrid.uab.edu catissue
  • /etc/sysconfig/network-scripts/ifcfg-eth0 (ip addr).
  • /etc/sysconfig/network (hostname). Change the value of HOSTNAME to your host name.

The host firewall is pre-configured with the following ports open to support the production services of the VM. You need to ensure that other network firewalls are configured to reflect this port profile.

  • Standard system service ports
    • 5353 (DNS)
    • 123 (NTP)
    • 22 (SSH)
  • End-user web application for caTissueSuite
    • 38080
  • caGrid data service of caTissueSuite for the production caGrid environment (this is the interfaces accessed from caBIG).
    • 18080

After making sure the firewall is configured, need to bring up the machine with the network service on. Building the services without the network connection results in a build failure. A bug on this failure has been documented here.

Boot the machine at this point in multi user mode,. which will bring up the network service. 

init 3

VMWare Tools Configuration

Sync the VM time with the ESXi Server Time

  • From the ESXi Server GUI, select the caTissueSuite VM, right-click, and select Install VMware Tools
  • Open the VM console and login as root
  • Mount the virtual cdrom device 
    mount /dev/cdrom /mnt
  • Install the VMWare Tools 
    rpm -ivh /mnt/VMWareTools.........rpm
  • Execute the vmware tools script and change/keep the guest x resolution 
    vmware-config-tools.pl
  • The script adds the vmware tools as a system service and starts the service. Check for the service 
    chkconfig --list | grep -i vm

Change System Passwords

Before starting the VM you should change the default passwords delivered with the VM. The passwords for root, catissue, and the JBoss containers should be changed at this point.

  • System passwords 
    passwd root
passwd catissue
  • Jboss container passwords - edit the following files to change the passwords contained in those files (Note: these passwords are maintain in clear text so simply replace the password values with the new ones
    • For caTissueSuite WebApp: 
      /home/catissue/apps/catissue/jboss-4.2.2.GA/server/default/conf/props/jmx-console-users.properties 
/home/catissue/apps/catissue/jboss-4.2.2.GA/server/default/conf/props/jbossws-users.properties
    • For caTissueSuite data service: 
      /home/catissue/apps/catissue/jboss-4.0.4.GA/server/default/conf/props/jmx-console-users.properties 
/home/catissue/apps/catissue/jboss-4.0.4.GA/server/default/conf/props/jbossws-users.properties

Reboot the VM

The VM is now ready to be brought into full operation. Enter reboot at the command prompt and wait for the machine to enter full operation.

Build caTissueSuite Web Application

  • Change to the caTissue account 
    su - catissue
cd src/caTissueSuite_11_installer
  • Edit caTissueInstall.properties and mention your blazer ID here, 
    email.administrative.emailAddress=
email.sendEmailFrom.emailAddress=

first.admin.emailAddress=
  • password (can be anything of your choice) here 
    first.admin.password=
  • and host name here 
    jboss.server.host=
  • Do not change the rest of the details such as, Jboss location, database details.
  • Now, we are ready to build the caTissueSuite (the first deploy takes considerable time ~20 min) 
    ant -f deploy.xml deploy_all

Post Install

  • Config Jboss log output to reduce the size of log files 
    su - catissue
cd apps/catissue/jboss-4.2.2.GA/server/default/catissuecore-properties/
  • Open file log4j.properties. This file contains caTissue specific logging settings. Change the values of following properties to WARN as shown below to avoid debug statements in the logger files to reduce the size of the log file. 
    log4j.rootCategory=WARN, CONSOLE
log4j.appender.CONSOLE.Threshold=WARN
log4j.appender.LOGFILE.Threshold=WARN
log4j.appender.HIBERNATE.Threshold=WARN
log4j.logger.org.hibernate=WARN,HIBERNATE
log4j.logger.edu.wustl.catissuecore=WARN, LOGFILE

Start the Web App JBoss Container

  • Init script for caTissueSuite web application is /etc/init.d/jboss-catissue-webapp. Add this as a system service by logging in as root. 
    chkconfig --add jboss-catissue-webapp

chkconfig jboss-catissue-webapp on
  • Start the service 
    service jboss-catissue-webapp start
  • When catissue is started the first time, it usually takes 7-20 minutes for the complete application to be deployed (the dynamic extensions loading will consume a great amount of time). Track the log file and check for any errors. You can stop tracking the log file at any time with Ctrl+c. 
    su - catissue
tail -f var/log/jb-422.log

Access the Web App

  • With the machine in full operation you will be able to access the caTissueSuite application via your browser at 
    http://your.new.hostname:38080/catissuecore
  • The first time you login, the application prompts you to change password. Change the password. Note down the changed password, as this will have to be updated in many other service configuration files like caTIES and caGrid services.
  • Create a common user, catissue_user@xyz.edu, to which the caGrid users can be mapped to.
    1. Click User on the Administrative Data tab.
    2. Enter the E-mail Address as catissue_user@xyz.edu
    3. Enter other details such as Last Name, and so on to add a new user.
    4. Create an Institution University of Alabama at Birmingham by clicking on the Add New link beside the field.
    5. Create Department NeuroSurgery by clicking on the Add New link beside the field.
    6. Create Cancer Research Group UAB Brain Tumor SPORE by clicking on the Add New link beside the field.
    7. Select the Role as Scientist to assign to the new user.
    8. Select the default Site
    9. Privilege for the Scientist role will be automatically selected
    10. Click Add Privilege to assign the selected privileges to the user.
    11. The Summary section displays the details of the privileges assigned to the user.
    12. Click Submit to save the user privileges
    13. After creating, the above user details along with the password will be sent as an e-mail to your blazer ID. Note the password for this user, as we will need this when building the caTissueSuite Data Service.

Build caTIES

  • cancer Text Information and Extraction System loads the surgical pathology reports and associates them to the Participants and Specimen collection groups in the Suite database.
  • caTIES will be deployed on a stand-alone machine, different from the caTissueSuite machine. This machine need not have a publicly addressable IP address, since the services offered by caTIES will only be accessible to the Systems Administrator managing the caTissueSuite web application.
  • Although caTIES can be installed on the same machine as that of caTissueSuite, the motivation to install caTIES on a separate machine was to increase performance
  • We have seen that caTIES on the same machine as of caTissueSuite, greatly increases the load average, thereby decreasing the overall performance of the machine
  • Please follow these steps to configure and build caTIES on a separate machine

Build caTissueSuite Data Service

Build caGrid-1.2

  • Installation of caGrid-1.2 requires an X window session. Hence should login to your caTissueSuite host as follows: 
    ssh -X catissue@your.host.name
  • Build caGrid 
    cd src/caGrid_12_installer
java -jar caGrid-installer-1.2.jar
  • When the installer starts, do the following steps:
    • Agree to the License
    • In the select installation type, make sure that you only check Install caGrid and the rest are unchecked.
    • Mention the directory to install ant, tomcat, globus, and caGrid as /home/catissue/src/caGrid_12_installer/
    • Select the target grid as Current NCI Production Grid
    • The installer takes about 30-45 minutes to install the above components and exits with the paths of ant, globus and caGrid installed locations. Set the paths for the same in /home/catissue/.bashrc as 
      export ANT_HOME=/path/given/by/the/installer
export PATH=$ANT_HOME/bin:$PATH

export GLOBUS_LOCATION=/path/given/by/the/installer
export PATH=$GLOBUS_LOCATION/bin:$PATH

export CAGRID_LOCATION=/path/given/by/the/installer
export PATH=$CAGRID_LOCATION:$PATH
  • Source bashrc 
    source ~/.bashrc
  • Open file $CAGRID_LOCATION/antfiles/jboss/jboss.xml and perform the following changes
    • Search for string: <target name="deployJBoss"
    • Update the defaultPort to 18080, for the caGrid service
    • After editing, the section should look like as follows: 
      <target name="deployJBoss" description="Deploy GT4 into JBoss. Must specify -Djboss.dir=&lt;JBoss root&gt;">
                <property name="defaultProtocol" value="http" />
                <property name="defaultPort" value="18080" />
                <property name="webapp.dir" value="${jboss.dir}/server/default/deploy/${webapp.name}.war" />
  • To deploy the Globus on JBoss run the following commands: 
    cd $CAGRID_LOCATION/antfiles/jboss
ant -f jboss.xml deployJBoss -Djboss.dir=/home/catissue/apps/catissue/jboss-4.0.4.GA

Install caTissueSuite Data Service

  • change directory to 
    su - catissue

pushd src/caTissueSuite_11_installer/CaTissueSuite_caGrid_Service
  • Open file credentials.properties and mention Username catissue_user@xyz.edu as given in Step2 and Password in Step13 above.
  • Leave the keystoreFilePath blank. Save the file and copy the saved file as /home/catissue/catissueservice/credentials.properties.
  • Open file service.properties from the same directory and update host as the host name given to the caTissueSuite VM and port as 38080 i.e., after editing, it should look like this: 
    cqlQueryProcessorConfig_appserviceUrl=http\://your.new.host.name\:38080/catissuecore/http/remoteService
  • From this folder, run the following commands: 
    ant clean

ant all

ant deployJBoss
  • Detailed install steps for caTissue Data Service can be found in Chapter 6 of caTissueSuite Deployment Manual

Advertising the Grid Service

popd

pushd apps/catissue/jboss-4.0.4.GA/server/default/deploy/wsrf.war/WEB-INF
  • Check web.xml from the above location. The web.xml file contains the port and protocol the caTissueSuite grid service will be advertised as. It should have the following: 
    <init-param>
<param-name>defaultPort</param-name>
<param-value>18080</param-value>
</init-param>
<init-param>
<param-name>defaultProtocol</param-name>
<param-value>http</param-value>
</init-param>


popd

pushd apps/catissue/jboss-4.0.4.GA/server/default/deploy/wsrf.war/WEB-INF/etc/globus_wsrf_core/
  • Make sure your container is publishing the right host name. Add the following lines to the file server-config.wsdd at the above location 
    <parameter name="logicalHost" value="your.new.host.name"/>
<parameter name="publishHostName" value="true"/>
  • Add the correct point of contact information after building the caTissue data service.
  • Change directory to the caTissueSuite JBoss grid container 
    popd

pushd apps/catissue/jboss-4.0.4.GA/server/default/deploy/wsrf.war/WEB-INF/etc/cagrid_CaTissueSuite
  • Edit serviceMetadata.xml to contain the following point of contact information 
      <ns1:hostingResearchCenter>
  <ns15:ResearchCenter displayName="UAB Comprehensive Cancer Center" shortName="UAB-CCC" xmlns:ns15="gme://caGrid.caBIG/1.0/gov.nih.nci.cagrid.metadata.common">
   <ns15:Address country="US" locality="Birmingham" postalCode="35233" stateProvince="AL" street1="1802 6th Avenue South" street2=""/>
   <ns15:pointOfContactCollection>
    <ns15:PointOfContact affiliation="Staff" email="John.Sandefur@ccc.uab.edu" firstName="John" lastName="Sandefur" phoneNumber="205-996-5236" role="Information Systems Manager/caBIG Deployment Lead"/>
    <ns15:PointOfContact affiliation="Staff" email="bebrake@.uab.edu" firstName="Bobby" lastName="Brake" phoneNumber="205-934-4980" role="Assistant Director, Infrastructure Services"/>
   </ns15:pointOfContactCollection>
  </ns15:ResearchCenter>
 </ns1:hostingResearchCenter>
  • Check for service registration 
    popd

pushd apps/catissue/jboss-4.0.4.GA/server/default/deploy/wsrf.war/WEB-INF/etc/cagrid_CaTissueSuite
  • The caTissueSuite service is targeted to the caGrid Production Index Server. Check for the following URL in the file CaTissueSuite_registration.xml at the above location 
    <wsa:Address>http://cagrid-index.nci.nih.gov:8080/wsrf/services/DefaultIndexService</wsa:Address>

Start the Data Service JBoss Container

  • Init script for caTissueSuite data service is /etc/init.d/jboss-catissue-datasvc. Add this as a system service by logging in as root. 
    chkconfig --add jboss-catissue-datasvc

chkconfig jboss-catissue-datasvc on
  • Start the service 
    service jboss-catissue-datasvc start
  • Track the log file and check for any errors. You can stop tracking the log file at any time with Ctrl+c. 
    su - catissue
tail -f var/log/jb-404.log

Access the Data Service

  • You can verify that the grid service has been successfully deployed by typing the following URL in the browser: 
    http://your.new.host.name:18080/wsrf/services/cagrid/CaTissueSuite

Diagnostics Checks for Grid Services

Once the grid services for caArray/caTissue/Labkey are configured and their respective publish containers started, we can perform some diagnostics checks.

From the cagrid Portal:

  • Go to the caGrid Services tab
  • At the Service Diagnostics section, type the url in the Service URL field
  • For caTissueSuuite, the service url is: 
    http://your.host.name:18080/wsrf/services/cagrid/CaTissueSuite

From command line, using Globus commands. All the below commands are from caBig Portal Troubleshoot Guide 

su - catissue
  • Verify your Grid service is registering with the Index service 
    $GLOBUS_LOCATION/bin/wsrf-query -a -z none -s http://cagrid-index.nci.nih.gov:8080/wsrf/services/DefaultIndexService | grep "<ns8:Address xmlns:ns8" | cut -d'>' -f2 | cut -d'<' -f1 | sort > all_grid_services.txt
  • grep for uab in the output file all_grid_services.txt
  • Make sure the service's metadata is accessible 
    $GLOBUS_LOCATION/bin/wsrf-get-property -a -z none -s http://your.host.name:18080/wsrf/services/cagrid/CaTissueSuite {gme://caGrid.caBIG/1.0/gov.nih.nci.cagrid.metadata}ServiceMetadata
  • Make sure the service's Domain Model is accessible (if the service is a Data Service) 
    $GLOBUS_LOCATION/bin/wsrf-get-property -a -z none -s http://your.host.name:18080/wsrf/services/cagrid/CaTissueSuite {gme://caGrid.caBIG/1.0/gov.nih.nci.cagrid.metadata.dataservice}DomainModel
  • Verify that the Index service is seeing your service 
    $GLOBUS_LOCATION/bin/wsrf-query -a -z none -s http://cagrid-index.nci.nih.gov:8080/wsrf/services/DefaultIndexService / | grep uab

References