Welcome to the caIntegrator 1.3 Local Installation Guide.
For any general information about the application, application support, or to report a bug, contact Application Support. |
Topics in this document include:
This caIntegrator v.1.3 Installation Guide provides you with the instructions to install and configure a fresh caIntegrator v.1.3 application. The caIntegrator installation installs and configures a JBoss application server and creates a caIntegrator-specific schema within a pre-existing database on a preinstalled MySQL server.
Directions are given in this document for both Linux and Windows operating systems.
Published caIntegrator v.1.3 development documentation can be found on the caIntegrator page of the NCI wiki |
The process for installing caIntegrator v.1.3 includes the following tasks described in this document:
The caIntegrator v.1.3 installation has been tested on Linux Red Hat Enterprise Linux AS 4 64/32-bit (for AMD chipset) and the Windows XP/2003 environments. While the installation may work in other Linux and Windows environments, it has only been tested in these environments.
For the system userid which will be used to start the caIntegrator application, you should specify permission to open at least 2048 file descriptors. |
Many of the servers and services that make up caIntegrator are automatically installed as part of this caIntegrator v.1.3 installation. However, prior to the installation, you must download and install the following required tools and recommended versions in the order they are listed in the table. The software name, version, description, and URL hyperlinks (for download) are indicated in the table. Complete the directions for installing each, as directed on the corresponding website.
Required Software Name and Version | Description |
---|---|
Java 2 Platform Standard Edition 6.0 Update 18 (J2SE 6.0). Be sure to download the correct Java SDK for your operating environment. For example, for Linux AMD 64, you would download jdk for Linux, | The J2SE Development Kit (JDK) supports creating J2SE applications. |
Apache Ant is a Java-based build tool. | |
MySQL is an open-source database software application. |
As you install each application, record the installation directory path, and the hostname of your MySQL DB server, and the DB admin username/password, if you are going to install UPT. |
When you install the Java SDK, you will be prompted to select the installation directory. Record the path, as this directory will be used when you set the environment variables.
The purpose of setting operating system environment variables is so that the Java SDK and Ant build tool are available to run from anywhere in the system. |
The |
To set the environmental variables in Linux, follow these steps:
/etc/profile
file. A PATH variable should already be created in this file, so be sure to define the JAVA_HOME and ANT_HOME export before the PATH export. Replace <some_path>
with the correct path fragment for Java and Ant installations. export JAVA_HOME=<some_path>/jdk1.6.0_18
export ANT_HOME=<some_path>/apache-ant-1.7.0
export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$PATH
To verify that environment variables have been set correctly, follow these steps:
echo $JAVA_HOME
echo $ANT_HOME
java –version
from a command prompt. You should see java version "1.6.0_18"
. ant –version
from a command prompt. You should see: Apache Ant version 1.7.0 compiled on December 13 2006.
To set the environmental variables in Windows, follow these steps:
The |
JAVA_HOME
. ANT_HOME
.PATH
system environment variable, and select the Edit button. This opens the Edit System Variable dialog box. %JAVA_HOME%\bin;%ANT_HOME%\bin;
To verify the environment variables have been set correctly, follow these steps:
echo %JAVA_HOME%
* echo %ANT_HOME%
* java –version
from a command prompt. You should see java version "1.6.0_18"
.To verify your Ant installation, enter ant –version
Environment variables for caIntegrator and, optionally, UPT are modified and set in those sections of this document: #Installing a New caIntegrator v.1.3 and #Downloading and Installing UPT (Optional). |
A MySQL 5.0.45 server must be downloaded, installed and running in order for the caIntegrator installation to work successfully.
To download and install MySQL, follow the steps outlined on the MySQL website.
You should consult the following three links to successfully set up secure and well-performing MySQL servers, in preparation for installing caIntegrator: |
|
An important component of command-line installation of either caIntegrator or UPT is configuring properties files. Prior to initiating a command-line installation, property variables must be modified. Note the following points about changing or entering variables.
The paths in the *.properties
files should use forward slashes. For example, you would use application.base.path=C:/apps/caIntegrator-app
, not application.base.path=C:\apps\caIntegrator-app
. If you use backslashes, you will experience undesirable results.
You should not specify paths with spaces included as property values. In Windows, note that the C:\Documents and Settings<username>
path contains spaces and should not be used, or anything similar. If you are using Windows, use a path such as C:/apps/caIntegrator
. Spaces are fine for property values which do not represent a path.
In each *.properties
file, any property value marked with uppercase REPLACE_*
must be manually updated with the appropriate value.
*.properties
file, any property value marked with lowercase replace_*
may be optionally updated with the appropriate value.database.system.user
for your MySQL server, you can determine which users have full privileges to create and manage other databases, by executing show grants from a MySQL prompt to determine the correct level of privileges.If you do not already have a User Provisioning Tool (UPT) installed, and you wish to manage user accounts for your caIntegrator application, you must install UPT.
UPT is used to provision users in the caIntegrator application. Each CBIIT application installs with its own Common Security Module (CSM) schema that has sample/default users and a role/permissions structure. To add additional users you must provision the caIntegrator application in the UPT. Then you can assign users to caIntegrator.
You can download UPT 4.2
For instructions on how to install UPT 4.2, refer to the chapter, UPT Installation and Deployment, in the caCORE_CSM_v42_ProgrammersGuide.
UPT 4.2 is backwards compatible to previous versions of CSM. When you provision the application in UPT 4.2, you will be asked to specify the CSM version caIntegrator is using. You should enter version |
To newly install the caIntegrator v.1.3 application and services, follow the steps in these sections:
There must already be a pre-existing MySQL DB and connection username/password for caIntegrator to install into; caIntegrator does not create its own DB. |
To download the caIntegrator v.1.3 files, follow this step:
The various installation files for caIntegrator v.1.3 are between 150-250MB in size. All of the files can be downloaded from the caIntegrator GForge files archive.
caIntegrator_install_1_3.zip
file (around 175MB).caIntegrator_upgrade_1_3.zip
file (about 175 MB).caIntegrator_gui_distribution_1_3.jar
file (about 207 MB).Remember the download location, as you will be using this file to run the installation in the steps that follow.
These server components are installed and configured as part of the caIntegrator v.1.3 installation. You do not need to do anything further to download or install these components.
|
You can perform a new installation of caIntegrator v.1.3 using either of these two methods:
For detailed information on all of the GUI installer fields, refer to the BDA Properties page.
For performing an installation using the GUI Installer, follow these steps:
caIntegrator_gui_distribution_1_3.jar
. Enter this command to invoke the GUI installer: java –jar caIntegrator_gui_distribution_1_3.jar
.localhost
25
<user home>/.installer-caintegrator/caintegrator_installer/install.properties
file for the correct values.<user home>/.installer-caintegrator/caintegrator_installer/install.properties
file in a different directory for future reference.*When you do a command-line installation of caIntegrator for the first time, you will work with install.properties
file included in the caIntegrator_distribution_1_3.zip
.
*If you are upgrading by command-line from a previous version of caIntegrator, you will work with the upgrade.properties
file included in the caIntegrator_upgrade_1_3.zip
.
Verify that default port values defined in install.properties
files are not in use on your system by running netstat –a
from the command line. If the ports are in use prior to installation, you will likely experience problems with your installation.
You may receive an error such as Exception in thread "main" java.lang.NoClassDefFoundError: org/jboss/Shutdown
. This should not be a problem, as the installer attempts to stop previously installed servers to prevent problems during the installation. If this is your first time installing caIntegrator, you may receive and disregard this error message.
To install a new instance of caIntegrator using the command-line, follow these steps:
caIntegrator_distribution_1_3.zip
described in Downloading caIntegrator v.1.3 files, unzip the Files, using one of these two methods: unzip -q caIntegrator_distribution_1_3.zip
. You must have a ZIP tool installed. This location will be referred to as the <installer_directory>
henceforth.Use WinZip or a similar utility to unzip the files to a temporary location. This location will be referred to as the <installer_directory>
henceforth.
Example: <installer directory>
= C:\caIntegrator_installer
Setting the property values is an important step in the installation process. Before you complete steps 2 & 3, review #Working with Properties Files. |
<installer_directory>/install.properties
file, modify the values for your environment and save the file. For the latest details about configuring the properties for your environment, refer to the BDA Properties wiki page.Record the property values you have set.
You should not need to modify the other default values as we have chosen unique ports to reduce the risk of other applications using the same values. However, be sure to verify that the ports in this file are not being used by other applications. |
<installer_directory>/
(Example:cd C:\caIntegrator_2_0_installer
), and type ant
. This initiates the installation process. The anticipated duration is anywhere from 1-15 minutes, depending on your system's speed, power and memory. <installer_directory>/install.properties
file for the correct values. Enter manager as the user and manager as the password.<installer_directory>/install.properties
file in a different directory for future reference.This section describes how to upgrade your product from caIntegrator 1.2 to caIntegrator 1.3. The instructions in this section apply only if you have already installed a caIntegrator version 1.2.
You can perform an upgrade installation of caIntegrator v.1.3 using either of these two methods:
|
If you are performing a new installation, go directly to #Installing caIntegrator v.1.3 Application and Services.
The directions in this section presume that you have a valid and functioning caIntegrator 1.2. It also assumes that Java SDK, Apache Ant and MySQL have all been successfully uploaded and installed, as described on pages #Required Software--Not Included in caIntegrator.
When you installed the previous version of caIntegrator 1.2, you configured the install.properties
file. To complete the upgrade to caIntegrator 1.3, you must use some of the values from the original install.properties
to configure values in the upgrade installer wizard GUI, or the upgrade.properties
file if you are doing a command-line method of upgrade.
See steps 3 & 4 in #Upgrade Using Command Line Installer for more information.
For detailed information on all of the GUI installer fields, refer to the BDA Properties page.
To perform an upgrade to caIntegrator 1.3 using the GUI Installation Wizard, follow these steps:
Because of the application name change in v.1.3, in the JBOSS home directory, locate the war file containing the previous release of caIntegrator2 and delete it. For example, find this file: JBOSS_HOME/server/default/deploy/caintegrator2.war
and delete the file named caintegrator2.war
.
In this same directory, there may be a different file named |
caIntegrator_gui_distribution_1_3.jar
and invoke the GUI installer using this: java –jar caIntegrator_gui_distribution_1_3.jar
.ldaps://myldaphost.mydomain.com:636
.install.properties
for the correct jboss.server.hostname
and jboss.server.port
values.To perform an upgrade to caIntegrator 1.3 using the command-line, follow these steps:
Because of the application name change in v.1.3, in the JBOSS home directory, locate the war file containing the previous release of caIntegrator2 and delete it. For example, find this file: JBOSS_HOME/server/default/deploy/caintegrator2.war
and delete the file named caintegrator2.war
.
In this same directory, there may be a different file named |
Open a command prompt and use it to extract this file to a temporary location. For example, you may enter a command such as unzip -q caIntegrator_upgrade_1_3.zip
. You must have a ZIP tool installed.
It is recommended that you use a new directory for the unzipped files, rather than the one you used to unzip the installer for the previous version(s) of caIntegrator. This location will be referred to as the |
<upgrade_installer directory>
henceforth <upgrade_installer directory> = C:\caintegrator2_1_2_upgrade_installer
Edit the default properties in the <upgrade_installer_directory>/upgrade.properties
file. Before doing so, review #Working with Properties Files.
To do so, open both properties files, the one you configured originally when you installed the previous version of caIntegrator. (<install. properties file>
)and the <upgrade_installer_directory>/upgrade.properties
file.
For the latest details about configuring the properties for your updated environment, refer to the BDA Properties page.
The |
Record these property values.
You shouldn't need to modify the other default values as we have chosen unique ports to reduce the risk of other applications using the same values. However, be sure to check the |
<upgrade_installer_directory>/
(Example:cd C:\caIntegrator_upgrade_installer), and type ant . This initiates the upgrade process. The anticipated duration is anywhere 1-15 minutes depending on your system's speed, power and memory. jboss.server.hostname
and jboss.server.port
values.You must modify your JBoss 4.0.5 configuration to increase the amount of available memory for the caIntegrator application. Directions for doing this in Windows are in the following step 1. |
To configure JBoss in Windows, follow these steps.
Modify the following entry to the JBoss run.bat file which is located at <application_root_directory>/jboss-4.0.5.GA/bin/run.bat
. Find the line that begins with set JAVA_OPTS= -Dbda=bda -Dprogram.name=%PROGNAME% -server
and modify the "-Xms256m -Xmx512m"
to read "-Xms4096m -Xmx4096m"
.
If 4096m is higher than the physical memory on the machine, then performance could be severely impacted with performance degradation and errors. 4096m of physical memory is recommended. |
Be careful when copying and pasting from this installation guide. No spaces must come before and after the columns. A safe way to ensure that the text has no unwanted space and unwanted characters is to copy the text into a blank text editor such as NotePad first. Then you can correct the spacing and copy-paste back into the run.bat file. |
run.bat
under $JBOSS_HOME/bin
. Refer to the publicly available JBoss user's guide for more information.MySQL and the JBoss server that make up caIntegrator, and the JBoss server optionally installed for UPT, must run continually as services. The instructions in this section cover all of these scenarios. For a caIntegrator deployment, there are at least three servers, and if UPT is installed, four servers:
|
The default caIntegrator installation runs JBoss as a command line process using the user currently logged on. Therefore, when you log out as this user, JBoss will no longer be available for caIntegrator. For that reason, it is recommended that you configure your JBoss servers to run as a Linux or Windows service. The instructions are contained in this section. |
Before starting the caIntegrator JBOSS server, change the default location for user data. User data consists of various files that are saved by caIntegrator during the deployment and querying of studies. The default location for user data should be changed via the Djava.io.tmpdir
jvm parameter in the Jboss run.conf
file.
Example jvm parameter: -Djava.io.tmpdir=/local/content/caintegrator/jvmtmp
To run JBoss as a service, follow these steps:
See http://wiki.jboss.org/wiki/Wiki.jsp?page=StartJBossOnBootWithLinux.
To run an existing JBoss command line installation as a service, follow the directions for creating a user-defined service at http://support.microsoft.com/kb/137890/EN-US/. You need to have access to the Windows Resource Kit.
It is assumed that your MySQL server was installed as a service. If it was not, follow these recommendations for installing this server as a service. |
To run MySQL as a service, follow these steps:
When installing MySQL server on Windows, choose the option to run MySQL as a Windows service.
To add and administer caIntegrator users in the UPT, refer to the caIntegrator 1.3 User's Guide
The following users are provided by default by the caIntegrator installer.
CBIIT Application Support | Application Support |