C3PR Installation Guide

From CTMS_WIKI

Introduction

Background

The Cancer Center Participant Registry (C3PR) is a web-based application used for end-to-end registration of patients to clinical trials. This includes capturing the consent signed date, eligibility criteria, stratification, randomization, and screening. Clinical workflows are enabled by both subject- and study-centric views into the registration process. C3PR can be run in a standalone mode where study definitions, investigators, study personnel, and sites are entered into the system, or C3PR can be run in an integrated mode with the caBIG Clinical Trials Suite (CCTS). C3PR also enables multi-site clinical trials where registration information is entered locally at affiliate sites and the registration is completed by call-out to the coordinating site.

Throughout the development of C3PR, a number of elaborator and adopter sites are actively being engaged to help define requirements and test the application. Our primary elaborators include Duke, Wake Forest, Mayo, Westat, CALGB, CCR, and the Coalition of Cooperative Groups. Our primary adopters include Duke and Wake Forest with engagement of Georgetown and CCR.

C3PR release 1 was developed by Nortel Solutions and released in 2006. Release 2 was developed by Duke Cancer Center in collaboration with SemanticBits, LLC and was released in March, 2008. We are currently in the next phase of development with releases slated for the end of September, 2008 and March, 2009.

Scope

This installation guide outlines the supported configurations and installing, setting up and configuring the application and databases for the Cancer Central Clinical Participant Registry version 2.5 (C3PRv2.5).

This document is designed to meet the needs of administrators who will be deploying C3PR. To perform the tasks outlined in this document, you should be familiar/knowledgeable with running command-line utilities, running web applications in application containers, and configuring databases. Ideally, the person performing these functions should be someone who is an experienced system administrator.

Note: C3PRv2.5 is a component of the caBIG Clinical Trials Suite (CCTS). Installation instructions and other documentation related to CCTS can be found at https://wiki.nci.nih.gov/display/CTMS/CCTS+Installation+Guide

Note: Configuring security is not part of the installation guide. See the C3PRv2.5 administration guide for instructions on this: http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/c3prv2/documentation/design/c3prv2_administration_guide.doc?cvsroot=c3prv2

C3PR Team

C3PR is a highly collaborative project made up of domain and technical experts from Duke Cancer Center, SemanticBits, Wake Forest Cancer Center, Mayo Clinic, CALGB, and Westat.

Contact and Support

Related Documents

C3PR Software and Technology Requirements

Hardware Requirements

There are no stringent hardware requirements because C3PR is a lightweight web application not intended to have a very large code base. However, you may use the following for guidance on hardware requirements:

Software Requirements

You must download and install the required software that is not included with the C3PRv2. The software name, version, description, and URL hyperlinks (for download) are indicated in the table below:

* Either Oracle OR PostGreSQL (not both) is required as an RDBMS for C3PR application. Note that C3PRv2 doesn't support SQL Server (which had been supported by C3PRv1)

** Included with the Graphical installer

 Note - Drivers for Oracle 9i/10g and PostGreSQL are included with the C3PR. 
 If you are using a different version of Oracle, you must obtain the 
 appropriate drivers.  JDBC drivers can be downloaded from the Sun Developer 
 Network at http://developers.sun.com/product/jdbc/drivers/index.html, or 
 from the individual vendors’ sites (for example, the Oracle 9i driver 
 classes12.zip can be downloaded from 
 http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/htdocs/ 
 jdbc817.html). These drivers should be placed in the {project_home}/lib 
 directory and the {CATALINA_HOME}/common/lib directory to enable connection 
 to the appropriate database.  In addition, some manual modification of the 
 Hibernate configuration files may be necessary.  Hibernate is a set of 
 libraries included with C3PR.

Installing C3PR

C3PRV2.5 has been tested with the operating systems and hardware specified previously in this guide. We cannot guarantee C3PRV2.5 will work if you are using variations of these operating systems and/or hardware.

C3PRV2.5 has a graphical installer to ease the installation process. The following are the steps to install C3PRV2.5 using the graphical installer.

 Note: for CCTS installation, ensure all pre-requisite software has been 
 installed  in accordance with the CCTS Installation Guide.  As per the CCTS 
 Installation Guide, the following environment variables should already be 
 established on the application server where C3PR will be installed:
   * CATALINA_HOME
   * ANT_HOME
   * JAVA_HOME
   * GLOBUS_LOCATION

 Note: if the installation is being performed on a Linux server, a GUI 
 Emulator tool must be installed to allow GUI windows to be presented for the 
 Graphical Installer.  See the CCTS Installation Guide for instructions on 
 setting up a GUI Emulator.

Step 1

Download the latest version of the installer at: https://cabig-kc.nci.nih.gov/CTMS/KC/index.php/C3PR#Installation

Note: There are two versions of the GUI installer – Online and Offline

The Online version is very compact in size (<2MB) but requires that you be connected to the Internet during the installation. The online installer downloads required software during the install process. The online installer will also download the latest release of C3PRv2.5

The offline installer packages all the required software and is fairly large download, but can be used in situations where Internet connection is not available or is severely limited (firewall). The offline installer will have to be downloaded for each new release of C3PRv2.5

The online GUI installer is recommended.

Example download for a Linux system:

  %> cd $HOME
  %> mkdir C3PRv2.5
  %> cd C3PRv2.5
  %> wget http://gforge.nci.nih.gov/frs/download.php/3096/c3prv2.5-installer-offline-1.0.jar

Step 2

OPTIONAL. If a previous version of C3PR was installed, delete your existing c3prv25 web application. This will usually mean deleting $CATALINA_HOME/webapps/c3prv2.5 directory

Step 3

Download the Globus (version and download URL provided in Table 2) and Unzip the downloaded archive into a local folder (henceforth referred to as <globus_root_folder>.

Step 4

 Note for CCTS installation: this step is handled once before any installations are performed and can be skipped.

Verify that the following environment variables are set:

• JAVA_HOME (pointing to the root directory of the Java installation)
• GLOBUS_LOCATION (pointing to <globus_root_folder>)

Also, ensure that your PATH statement includes the locations of the Java binaries. Optionally, set CATALINA_HOME if you wish to use an existing tomcat installation. Otherwise, the installer will install one for you.

To set environment variables in Windows:

1. Right-click My Computer > Properties (from the shortcut menu) > Advanced tab.
2. Click the Environment_Variables button.
3. In the New System Variable dialog box, add the Variable and Variable Value.

Examples:

• Variable = JAVA_HOME
• Value = C:\j2sdk1.5.0_11
• Variable=GLOBUS_LOCATION;
• Value=C:\ws-core-4.0.3;

To do this in Unix/Mac:

  $ export JAVA_HOME=/usr/java..1.5
  $ export GLOBUS_LOCATION=/usr/local/ws-core-4.0.3
  $ export CATALINA_HOME =/usr/apache-tomcat-5.0.28

Step 5

Launch the C3PR installer by running the following command (applies to any OS):

  java –jar c3prv2.5-installer-1.0.jar

This will launch the graphical installation wizard.

 Note: Do not launch the jar using Java Jar Launcher tool (double clicking 
 on the file). This does not use the environment variables you set in Step 4

Step 6

Follow the installation wizard to configure and install C3PR. Most screens during the installation process are self explanatory.

Step 7

Welcome to the C3PRV2.5 Installer Program

On the welcome page, Click Next

Step 8

License Agreement

You can either accept or reject the license. The license needs to be accepted to proceed with installation, if the license is rejected the installation will be aborted. Click Next to continue.

Step 9

Installation directory

You can let the installer select the installation directory(C:\Program Files\c3prv2.5) or can select a different directory of your choice using the “Select Folder”.This is where the application will be installed. Click Next to continue and it will confirm for the creation of the selected directory click yes to accept.

Step 10

Install Tomcat

You can let the installer deploy and configure tomcat or choose an existing installation of tomcat on your system. If you choose to use an existing tomcat, see Tomcat SSL How To web page for information on configuring the tomcat server for the HTTPS protocol (C3PRV2.5 uses SSL to secure client server interaction). Click Next to continue.

Step 11

Select Directory to install Tomcat

You can let the installer select the directory(C C:\Program Files\c3prv2.5\apache-tomcat-5.5.23) or can select a different directory of your choice using the “Select Folder”.This is where the Tomcat will be installed. Click Next to continue and it will confirm for the creation of the selected directory click yes to accept.

Step 12

Components to Install

Choose the components that you want to install and click Next

Step 13

Configure Tomcat

If you chose “Choose Existing” in the Install Tomcat Section follow the instructions to configure the Tomcat..

 Note: Ignore these instructions if you are using the installer to 
 install a new tomcat.

Step 14

Select Log File name

You can let the installer deploy and configure tomcat

Step 15

Configure CSM

Select to configure CSM and click Next.

Step 16

Select to Enable/Disable Authorization

Select to enable or disable Authorization and click Next

Step 17

Select Database

Select the Database you want to use and click Next

Step 18

Database Properties Specify the Database URL ,Username and Password

 Note: An empty database must already exist.

Step 19

C3PRV2.5 Installation Process

Click Install to start the installation process. This will initiate the installation and display the installation's status.

After navigating through the GUI screens, the install process will run through to completion. C3PRv2.5 install is complete.

Running C3PR

If you selected to install a new tomcat then set your CATALINA_HOME environment variable .

Open command prompt, change directory to <CATALINA_HOME>\bin

Run the following command to start tomcat server:

  startup.bat (windows)
  startup.sh (unix)

After your web application server has completely finished starting, open the browser with the following URL: http://localhost:9080/c3pr

C3PR Login page should be displayed with successful installation.To login use the default Username:c3pr_admin and Password:c3pr_admin

 Note: The installer’s version of tomcat runs on port 9080. Your existing 
 tomcat might be on a different URL/Port.  Replace localhost:port with the 
 correct hostname/port assignment.  The port assignment will be the Tomcat 
 container that has been configured for the application server.
 Example:
   http://cbvapp-q1009.nci.nih.gov:8080/c3pr
   To login, use the default userid: cctsdemo1@nci.nih.gov
   Password: cctsdemo1

Configuring C3PR

See the C3PR Administration Guide for configuring C3PR:

 Note: for CCTS installation, you will have to configure WebSSO integration.  
 See the administration guide for more details.

Troubleshooting

Problem: My installation failed with the message “class sun.tools.javac.Main not on the classpath. Perhaps JAVA_HOME does not point to the JDK. Its currently set to c:/Program Files/Java/jre_1.5.0_11”

Solution: This can happen when installing in the Microsoft Windows Operating system. First, try running the installer from the command prompt (as described in step5).

If the above solution does not work then copy the tools.jar file from $JAVA_HOME/lib/ to c:/Program Files/Java/jre_1.5.0_11/lib/ext directory. If the $JAVA_HOME/jre/lib/ext does not exist then go ahead and create it. Re-run the installer after doing this.

 Note: c:/Program Files/Java/jre_1.5.0_11 can be different on your system

Problem: My installation failed at the final step with the message “edu.northwestern.bioinformatics.bering.Migration’?

Solution: This means the database create/update scripts did not work. Please check the database URL you entered in the installer. Also, make sure that an empty database is available to the installer. The installer can created the tables etc. but not create a database.

Problem: My installation failed at the final step with the message: “FATAL ERROR: c3pr_dev datbase does no exist”

Solution: This implies that you do not have an empty database created as instructed in Step 8 of the Graphical Installer chapter.

Appendix A. Glossary