Page History

h1. {page-info:title}

{panel:title=Contacting Application Support}
* [Application Support Webpage|http://ncicb.nci.nih.gov/NCICB/support]
* Telephone: 301-451-4384
* Toll free: 888-478-4423
{panel}

{children:depth=2}
{info:title=To Get Support}For any general information about the application, application support, or to report a bug, contact [Application Support|http://ncicb.nci.nih.gov/NCICB/support].
\\
*To Print the Guide*
\\
You can create a PDF of the guide. For instructions refer to the tip [How do I print multiple pages?|WikiTrainFAQsTips:How do I print multiple pages?] If you want to print a single page, refer to [How do I print a page?|WikiTrainFAQsTips:How do I print a page?]

{info}

Welcome to the _caIntegrator 1.4 Local Installation Guide_. Topics in this document include:
{toc:minLevel=2}

h2. Introduction

This _caIntegrator v.1.4 Installation Guide_ provides you with the instructions to install and configure a fresh caIntegrator v.1.4 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.
{info:title=caIntegrator documentation} Published caIntegrator v.1.4 development documentation can be found on the [caIntegrator page of the NCI wiki|https://wiki.nci.nih.gov/x/JgUuAQ]{info}

h2. Overview of caIntegrator Installation

The process for installing caIntegrator v.1.4 includes the following tasks described in this document:
# Downloading and installing required software
\\
# Setting environment variables
\\
# Downloading caIntegrator v.1.4 distribution files
\\
# Installing
\\
## GUI Installer Method
\\
## Command-Line Method
\\
# Configuring JBoss servers and MySQL server to run as a service
# Post-Installation Tasks
\\
## Using UPT to Add caIntegrator Users

h2. caIntegrator v.1.4 Software and Technology Requirements

h3. Operating System

The caIntegrator v.1.4 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.

{info:title=File descriptors} For the system userid which will be used to start the caIntegrator application, you should specify permission to open at least 2048 file descriptors.{info}

h3. Required Software---Not Included in caIntegrator

Many of the servers and services that make up caIntegrator are automatically installed as part of this caIntegrator v.1.4 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 31 (J2SE 6.0)|http://java.sun.com/products/archive/j2se/6u18/index.html]. Be sure to download the correct Java SDK for your operating environment. For example, for Linux AMD 64, you would download jdk for Linux, {{linux-amd64-rpm.bin}}. For Windows, you might download jdk for Windows,{{windows-i586-p.exe}}. | The J2SE Development Kit (JDK) supports creating J2SE applications. |
| [Apache Ant, 1.8.2|http://archive.apache.org/dist/ant/binaries/apache-ant-1.8.2-bin.zip] | Apache Ant is a Java-based build tool. |
| [MySQL, 5.1.x|http://downloads.mysql.com/archives.php?p=mysql-5.1] | MySQL is an open-source database software application. |

{info:title=Important} 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.{info}

h3. Java SDK Installation

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.

h3. Apache Ant Installation

* Unzip the Apache Ant distribution files using a command line unzip tool or a zip utility, such as WinZip.

* After extracting the zip, you must set the environment variables, described in the following section, so that Ant is available in the system PATH.

h4. Apache Ant Environment Variables

{info:title=Reason for setting 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. {info}

h5. Linux
{info:title=Variables in Linux} The {{JAVA_HOME}}, {{ANT_HOME}} and {{PATH}} environment variables are set in {{/etc/profile}}. You may need to create the variables, or modify them if they already exist.{info}

To set the environmental variables in Linux, follow these steps:

# As the root user, enter the following in the {{/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_31_*}}
{{*_export ANT_HOME=<some_path>/apache-ant-1.8.2_*}};
{{*_export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$PATH_*}}
\\
# Log out and log back in so that the system recognizes your changes.

h5. Verifying the Environment Variables in Linux

To verify that environment variables have been set correctly, follow these steps:
# From the command line, enter:
\\
{{{*}{_}echo $JAVA_HOME{_}{*}}}
{{{*}{_}echo $ANT_HOME{_}{*}}}
Both of these commands should return the location where you installed these tools.
# To verify your Java SDK installation, enter {{{*}{_}java \--version{_}{*}}} from a command prompt. You should see {{java version "1.6.0_31"}}.
# To verify your Ant installation, enter: {{{*}{_}ant \--version{_}{*}}} from a command prompt. You should see: {{Apache Ant version 1.8.2}}
\\

h5. Windows

To set the environmental variables in Windows, follow these steps:
{info:title=Variables in Windows} The {{JAVA_HOME}}, {{ANT_HOME}} and {{PATH}} environment variables are set in the system properties.{info}
# In Windows, select *Control Panel*, then select the *System* application. In the System Properties window, select the *Advanced* tab.
# On the *Advanced* tab, click the *Environment Variables* button. To add a new system variable, select the *New* button.
\\
## In the *Variable* *{+}n{+}{*}{*}ame* text box, enter {{{*}{_}JAVA_HOME{_}{*}}}.
## In the *Variable* *{+}v{+}{*}{*}alue* text box, enter the location of your Java installation.
# Click the *New* button again.
\\
## In the *Variable name* text box, enter {{{*}{_}ANT_HOME{_}{*}}}.
## In the *Variable value* text box, enter the location of your Ant installation.
# Select the {{PATH}} system environment variable, and select the *Edit* button. This opens the Edit System Variable dialog box.
# In the Variable value text box, prepend the following text in front of the text that already exists in the *Variable Value* field.
{{{*}_%JAVA_HOME%\bin;%ANT_HOME%\bin;_{*}}}
# Click *OK*.

h5. Verifying the Environment Variables in Windows

To verify the environment variables have been set correctly, follow these steps:
# From the command line, enter:
\\
{{{*}{_}echo %JAVA_HOME%_{*}}}\*
{{{*}{_}echo %ANT_HOME%_{*}}}\*
Both of these commands should return the location where you installed these tools.
# To verify your Java SDK installation, enter {{{*}{_}java \--version{_}{*}}} from a command prompt. You should see {{java version "1.6.0_31"}}.
# To verify your Ant installation, enter {{{*}{_}ant \--version{_}{*}}}
{info:title=Other environment variables} Environment variables for caIntegrator and, optionally, UPT are modified and set in those sections of this document: [#Installing a New caIntegrator v.1.4] and [#Downloading and Installing UPT (Optional)].{info}

h2. MySQL Installation and Configuration

A MySQL 5.1 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|http://downloads.mysql.com/archives.php?p=mysql-5.1] {multi-excerpt-include:wikicontent:Exit Disclaimer to Include|name=ExitDisclaimer|nopanel=true}.

{tip:title=Tip} You should consult the following three links to successfully set up secure and well-performing MySQL servers, in preparation for installing caIntegrator:
\\
* [MySQL Security Guide|http://dev.mysql.com/doc/refman/5.1/en/security-guidelines.html] {multi-excerpt-include:wikicontent:Exit Disclaimer to Include|name=ExitDisclaimer|nopanel=true}\\
* Performance
** [InnoDB engine performance tuning|http://dev.mysql.com/doc/refman/5.1/en/innodb-tuning.html] {multi-excerpt-include:wikicontent:Exit Disclaimer to Include|name=ExitDisclaimer|nopanel=true}{tip}

{tip:title=More Tips}
* Record the MySQL root username/password chosen during the MySQL installation process, as you will need to use this as your {{database.system.user/ database.system.password}} later in the UPT installation process, should you choose to install UPT.
\\
* Note the MySQL port chosen during the MySQL installation process, as you will need to use this as your {{database.port}} later in both the caIntegrator and UPT (if installing UPT) installation processes.{tip}

h2. Working with Properties Files

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.

h4. Paths in Properties Files

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.

h4. Spaces in Path Property Values

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.

h4. More About Property Values

In each {{\*.properties}} file, any property value marked with +uppercase+ {{REPLACE_\*}} must be manually updated with the appropriate value.
\\
* In each {{\*.properties}} file, any property value marked with +lowercase+ {{replace_\*}} may be optionally updated with the appropriate value.
\\
* If there is reference to a {{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.

h2. Downloading and Installing UPT (Optional)

If you wish to manage user accounts for your caIntegrator application, you *must* install UPT.

h3. Overview of 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.3|https://gforge.nci.nih.gov/frs/download.php/9690/UPT_4.2.3_Installation_Instructions_v2.zip] and installation instructions.

{info:title=UPT and CSM} UPT 4.2.3 is backwards compatible to previous versions of CSM. When you provision the application in UPT 4.2.3, you will be asked to specify the CSM version caIntegrator is using. You should enter version {{*_4.2.3_*}}.{info}

h2. Installing caIntegrator v.1.4 Application and Services

To newly install the caIntegrator v.1.4 application and services, follow the steps in these sections:
* [#Downloading caIntegrator v.1.4 Files]
* [#Installing a New caIntegrator v.1.4]
** [#GUI Installer Method of Installation]
** [Command-Line Method of Installation|#Command-Line Method of Installation]
* [#Configuring JBoss]
** [#Configuring JBoss Servers and MySQL Server to Run as Services]
* [Post-Installation Tasks|#Post-Installation Tasks]
** [#Using UPT to Administer caIntegrator Users]

{note:title=BEFORE YOU BEGIN} 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. {note}

h3. Downloading caIntegrator v.1.4 Files

To download the caIntegrator v.1.4 files, follow this step:

The various installation files for caIntegrator v.1.4 are between 150-200MB in size. All of the files can be downloaded from the [caIntegrator distribution folder|https://gforge.nci.nih.gov/frs/?group_id=507].
* For a new command-line installer or command-line upgrade installer, download the {{caintegrator2-install-1.4.zip}} file (around 165MB).
\\
* For a GUI installer that you can use to do a fresh caIntegrator installation, download the {{caintegrator2_gui_distribution_1.4.jar-201207171753.jar}} file (about 190 MB).
\\

Remember the download location, as you will be using this file to run the installation in the steps that follow.

{tip:title=Server components in caIntegrator v.1.4} These server components are installed and configured as part of the caIntegrator v.1.4 installation. You do not need to do anything further to download or install these components.
\\
* JBoss 5.1.0 (hosts the caIntegrator application){tip}

h3. Installing a New caIntegrator v.1.4

You can perform a new installation of caIntegrator v.1.4 using either of these two methods:
* A GUI Installation wizard. Instructions for this method start in the following section.
* A command-line installation. For instructions, see [Command-Line Method of Installation|#Command-Line Method of Installation].

h4. GUI Installer Method of Installation

For detailed information on all of the GUI installer fields, refer to the [BDA Properties page|https://wiki.nci.nih.gov/x/NAUuAQ].

For performing an installation using the GUI Installer, follow these steps:
# Open a command prompt in the directory where you downloaded the {{caintegrator2_gui_distribution_1.4.jar-201207171753.jar}}. Enter this command to invoke the GUI installer: {{{*}{_}java \--jar caintegrator2_gui_distribution_1.4.jar-201207171753.jar{_}{*}}}.
# The Installation Wizard opens to facilitate the installation process. Click *Next* to proceed through the pages of the wizard, beginning with progressing past the Welcome page.
# Review the release notes.
# You must accept the license agreement.
# Select the *Install* installation type. For a new installation, select *Install*.
# Select *Browse* to navigate to the directory where you would like to install caIntegrator. The directory then displays in the text box. If the folder does not yet exist, click *OK* in the dialog box to indicate that you want the folder to be created.
# Select the type of installation you would like to perform. You can install everything, or just specific components (JBoss or Database only). The remaining sections in this guide assumes you chose to install everything.
# Continue walking through the pages of the installer. Configure the caIntegrator JBoss server on the next two pages of the installation wizard. The screen shots show example values. The port values which are specified are the defaults and can be used unless you want to reconfigure the values because of values already in use.
\\  !jboss config1.png|alt="Jboss configuration page; example fields shown"!
# JBoss Installation Options
!jboss config2.png|alt="Jboss configuration page; example fields shown"!
# JBoss SSL requires that you have requested and retrieved certificates already. If this does not apply to your installation, leave the values as false and continue.
\\  !jboss config3.png|alt="Jboss configuration page; example fields shown"!
# If your JBoss is externally accessible then fill out the JBoss External Hostname Configuration page. Otherwise, leave it blank and continue.
# For a standard installation of caIntegrator, do not use SSO.
# Specify the authentication type that caIntegrator should use. Database is the most likely choice if you aren't sure what to select here.
# If you selected LDAP in the previous step (authentication type), enter the appropriate configuration information for LDAP: the LDAP URL and the LDAP Search Back DN.
# If the authentication type is database, specify the following data base configuration information:
\\
#* The Database Host Name
#* The Database Port _Example_: 3306
#* Database name of the *pre-existing* database where the caIntegrator schema will be installed
#* The *pre-existing* Database Application User to be used by caIntegrator to connect to its database.
\\
Error messages inform you if the following occurs:
#** If the specified database host cannot be reached, or the field is blank.
\\
#** If the specified database does not already exist, or the caIntegrator DB user's credentials are wrong.
# Specify SMTP mail server connection information so that caIntegrator can send emails from users with new account requests. You must provide the following
#* Mail Server Host _Example:_ {{localhost}}
#* Mail Server Port Number _Example_: {{25}}
#* Mail Server Authentication: default is *false*.
#* Mail Server starttls: default is *false*.
# If jar signing is necessary for the installation, then enable it on the Jar Signing Configuration page. This step is optional and can be skipped.
# Review the summary of the information you entered.
\\
# Review the selected installation type and the installation destination.
\\
After you click *Next* from reviewing the installation destination, the installer runs. The installation wizard displays the installation progress and completion.
# When you are informed that the process is finished, click *Done* in the lower right corner of the wizard to close the installer.
# To verify caIntegrator installation:
\\
## Open your web browser to installed instance. The URL follows this format: http://<jboss.server.hostname>:<jboss.server.port>/caintegrator/workspace.action.
## Enter *{_}ncimanager{_}* as the user and *{_}changeme{_}* as the password. Refer to the {{<user home>/.installer-caintegrator/caintegrator_installer/install.properties}} file for the correct values.
# After successfully installing caIntegrator, make a backup of the {{<user home>/.installer-caintegrator/caintegrator_installer/install.properties}} file in a different directory for future reference.

h4. Command-Line Method of Installation


h5. About Properties

An important component of command-line installation is configuring properties.
{tip:title=Overview of command-line installer properties files}* When you do a command-line installation of caIntegrator for the first time, you will work with {{install.properties}} file included in the {{caIntegrator_install_1_4.zip}}.
* If you are upgrading by command-line from a previous version of caIntegrator, you will work with the {{install.properties}} file included in the {{caIntegrator_install_1_4.zip}} as well as the existing {{install.properties}} file.{tip}

See also [#Working with Properties Files].

{tip:title=caIntegrator Port Usage} 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.{tip}

{tip:title=JBoss Errors During 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.{tip}

h5. Command-line Installation Steps

To install a new instance of caIntegrator using the command-line, follow these steps:
# From the directory where you downloaded the {{caintegrator2-install-1.4.zip}} described in \[[#Downloading caIntegrator v.1.4 Files], unzip the Files, using one of these two methods:
\\
## 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 caintegrator2-install-1.4.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}}
{info:title=About setting property values} Setting the property values is an important step in the installation process. Before you complete steps 2 & 3, review [#Working with Properties Files].{info}
# Open the {{<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|https://wiki.nci.nih.gov/x/NAUuAQ|https://wiki.nci.nih.gov/x/NAUuAQ].
# *Record the property values you have set*.
{info:title=Other default values} 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.{info}
# From the command line, navigate to {{<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.
\\
The installer installs the caIntegrator schema in the specified *pre-existing* database on your MySQL server, and installs, configures, and starts the JBoss server for the caIntegrator application.
# To verify caIntegrator installation, open your web browser to the installed instance. The URL follows this format: http://<jboss.server.hostname>:<jboss.server.port>/caintegrator/workspace.action.
\\
Refer to the {{<installer_directory>/install.properties}} file for the correct values. Enter *{_}manager{_}* as the user and *{_}manager{_}* as the password.
# After successfully installing caIntegrator, make a backup of the {{<installer_directory>/install.properties}} file in a different directory for future reference.

h3. Upgrading caIntegrator 1.3 to 1.4

This section describes how to upgrade your product from caIntegrator 1.3 to caIntegrator 1.4. The instructions in this section apply only if you have already installed a caIntegrator version 1.3.

You can perform an upgrade installation of caIntegrator v.1.3 using either of these two methods:
* A GUI Installation wizard. Instructions for this method are found in [#Upgrading caIntegrator Using the GUI Installer].
* A command-line installation. Instructions for this method are found in [#Upgrading caIntegrator Using the Command-Line Installer].

{note:title=BEFORE YOU BEGIN}
* *Important:* Backup the 1.3 database. You need to create a reliable copy of your entire caIntegrator database.
\\
* *Important:* Backup the current installation of caIntegrator and artifacts from the original installation, such as properties files.{note}

If you are performing a new installation, go directly to [#Installing caIntegrator v.1.4 Application and Services].

h4. caIntegrator 1.3 Users Upgrading to caIntegrator 1.4

The directions in this section presume that you have a valid and functioning caIntegrator 1.3. 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|#Required Software--Not Included in caIntegrator].

h4. Overview of Properties Files

When you installed the previous version of caIntegrator 1.3, you configured the {{install.properties}} file. To complete the upgrade to caIntegrator 1.4, you must use some of the values from the original {{install.properties}} to configure values in the installer wizard GUI.
\\

See steps 3 & 4 in [#Upgrading caIntegrator Using the Command-Line Installer] for more information.
\\

h4. Upgrading caIntegrator Using the GUI Installer

\\
For detailed information on all of the GUI installer fields, refer to the [BDA Properties page|https://wiki.nci.nih.gov/x/NAUuAQ].

To perform an upgrade to caIntegrator 1.4 using the GUI Installation Wizard, follow these steps:
# Because of the upgrade from JBOSS4 to JBOSS5 in the caIntegrator 1.4 release, two GUI installer invocations are required. The first will install the new JBOSS5 in the same directory as the existing JBOSS4 and the second will update the database.
# Open the install.properties file for the existing 1.3 installation located at {{<user home>/.installer-caintegrator/caintegrator_installer/install.properties}} and save it as {{install.properties_v1.3}} to your desktop for reference during the upgrade.
# Open a command prompt in the directory where you downloaded the {{caintegrator2_gui_distribution_1.4.jar-201207171753.jar}} and invoke the GUI installer using this: {{java \--jar caintegrator2_gui_distribution_1.4.jar-201207171753.jar}}.
# The Installation Wizard opens to facilitate the installation process. Click *Next* to proceed through the pages of the wizard, beginning with progressing past the Welcome page.
# Review the release notes.
# You must accept the license agreement to continue.
# Select the *Install* installation type in step #4.
# Select *JBoss* in step #6.
# Configure the JBoss Server-related settings.
# Specify the authentication type that caIntegrator is using. If you choose LDAP, configure the LDAP information: the LDAP Host Name, the LDAP Search Base, and the LDAP Search Prefix. An example of the Host Name is {{ldaps://myldaphost.mydomain.com:636}}.
# Review the summary of gathered information.
# Click *Next* to proceed through the next two pages.
# After you click *Next* from reviewing the installation destination, the installer runs. The installation wizard displays the installation progress and completion.
\\
# When you are informed that the process is finished, click *Done* in the lower right corner to close the installation wizard.
# At this point if you open your web browser to the installed instance you will see a MYSQLGrammerException error displayed.
# Before invoking the GUI installer again, stop the server.
# Open a command prompt in the directory where you downloaded the {{caintegrator2_gui_distribution_1.4.jar-201207171753.jar}} and invoke the GUI installer using this: {{java \--jar caintegrator2_gui_distribution_1.4.jar-201207171753.jar}}.
# The Installation Wizard opens to facilitate the installation process. Click *Next* to proceed through the pages of the wizard, beginning with progressing past the Welcome page.
# You must accept the license agreement to continue.
# Select the *Upgrade* installation type in step #4.
# Select *Everything* in step #6.
# Configure the JBoss Server-related settings.
# Specify the authentication type that caIntegrator is using. If you choose LDAP, configure the LDAP information: the LDAP Host Name, the LDAP Search Base, and the LDAP Search Prefix. An example of the Host Name is {{ldaps://myldaphost.mydomain.com:636}}.
# Review the summary of gathered information.Review the selected upgrade installation type and the upgrade destination.
# Click *Next* to proceed through the next two pages.
# After you click *Next* from reviewing the installation destination, the installer runs. The installation wizard displays the installation progress and completion.
# To verify the caIntegrator installation, open your web browser to the installed instance. The URL follows this format: http://<jboss.server.hostname>:<jboss.server.port>/caintegrator. Example: [http://hostname:47210/caintegrator] and enter *{_}ncimanager{_}* as the user and *{_}changeme{_}* as the password. Refer to the original {{install.properties}} for the correct {{jboss.server.hostname}} and {{jboss.server.port}} values.
# Once the update is verified you can delete the JBOSS4 directory.

h4. Upgrading caIntegrator Using the Command-Line Installer

To perform an upgrade to caIntegrator 1.4 using the command-line, follow these steps:
# Because of the upgrade from JBOSS4 to JBOSS5 in the caIntegrator 1.4 release, two *ant* commands are required. The first will install the new JBOSS5 in the same directory as the existing JBOSS4 and the second will update the database.
# Open the install.properties file found in the application.base.path  directory and save it to your desktop as {{install.properties.v1.3.1}} for  reference during the upgrade.
# Delete the {{caintegrator2-install-1.3.1.zip}} file from its directory such as the application.base.path directory.
# Download {{caintegrator2-install-1.4.zip}} to the directory where the previous install zip file was such as the application.base.path directory. From the directory where you downloaded the install zip file, extract the files, using one of these two methods:
\\
## Open a command prompt and use it to extract this file. For example, you may enter a command such as {{{*}{_}unzip \-q caintegrator2-install-1.4.zip{_}{*}}}. You must have a ZIP tool installed.
## Use WinZip or a similar utility to unzip the files.
\\
# When asked if you would like to replace the existing files,  respond All.
# Open the {{install.properties}} file and replace all {{REPLACE_VALUE}} properties  with the values in the {{install.properties.v1.3.1}} file. Before doing so, review [#Working with Properties Files].
\\
For the latest details about configuring the properties for your updated environment, refer to the [BDA Properties page|https://wiki.nci.nih.gov/x/MBKy].
# In the {{DATABASE SETTINGS}} section of the {{install.properties}} file replace {{database.re-create=true}} with {{database.re-create=false}}. In the {{DATABASE  SETTINGS}} section of the {{install.properties}} file add the property and value {{exclude.database=true}}.
# Save this file to your desktop as {{install.properties.v1.4step1}}. Save this  file to your desktop a second time, this time as {{install.properties}}. Upload the {{install.properties}} file to the application.base.path directory.
\\
{info:title=Modifying 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 {{\*.properties}} file to verify that the ports in this file are not being used by other applications.{info}
# From the command line, navigate to the directory where you unzipped the installer file and type *{_}ant{_}*. This is the first of two *ant* commands. The anticipated duration is anywhere 1-15 minutes depending on your system's speed, power and memory.
# When the installer detects that a database exists, it warns you to back it up, which you were instructed to do earlier in this process. Press *Y* to proceed.
# If you open the application now in a browser window you will see a MYSQLGrammerException  error.
# Stop the server.
# Open the {{install.properties}} file and revert {{database.re-create=false}} back to {{database.re-create=true}}. Delete the property and value {{exclude.database=true}}.
# Save this file to your desktop as {{install.properties.v1.4step2}}. Save this file to your desktop a second time, this time as {{install.properties}}. Upload the {{install.properties}} file to the application.base.path directory.
# From the command line, navigate to the directory where you unzipped the installer file and type *_ant upgrade:database_*.
# Restart the server.
# To verify caIntegrator installation, open your web browser to the installed instance. The URL follows this format: http://<jboss.server.hostname>:<jboss.server.port>/caintegrator /workspace.action. Example: [http://hostname:47210/caintegrator/workspace.action] and enter *{_}ncimanager{_}* as the user and *{_}changeme{_}* as the password. Refer to the original install.properties for the correct {{jboss.server.hostname}} and {{jboss.server.port}} values.
# Once the update is verified you can delete the JBOSS4 directory.

h3. Configuring JBoss
{note:title=For Optimal Performance}
You must modify your JBoss 5.1.0 configuration to increase the amount of available memory for the caIntegrator application. Directions for doing this in Windows are in the following step 1.{note}

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-5.1.0.GA-nci/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"*}}.
{info:title=Physical memory} 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.{info}
{warning:title=Warning} 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.{warning}
# Restart your JBoss 5.1.0 server for the changes to take effect. The method of doing this may depend on the start/stop/restart scripts you created after the installation. Most commonly, you can execute shutdown.bat and then {{run.bat}} under {{$JBOSS_HOME/bin}}. Refer to the publicly available [JBoss user's guide|http://www.jboss.org] {multi-excerpt-include:wikicontent:Exit Disclaimer to Include|name=ExitDisclaimer|nopanel=true} for more information.

h4. Configuring JBoss Servers and MySQL Server to Run as Services
{info:title=JBoss & MySQL as services} 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:
\\
* JBoss 5.1.0 for UPT (optional)
\\
* JBoss 5.1.0 (for caIntegratorapplication)
\\
* MySQL 5.0.x{info}

h4. Running JBoss as a Service

{note:title=BEFORE YOU BEGIN} 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.{note}
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:

h5. Linux

See [http://wiki.jboss.org/wiki/Wiki.jsp?page=StartJBossOnBootWithLinux] {multi-excerpt-include:wikicontent:Exit Disclaimer to Include|name=ExitDisclaimer|nopanel=true}.

h5. Windows

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.
\\

h4. Running MySQL as a Service
{info:title=Server installed?} 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.{info}
To run MySQL as a service, follow these steps:

h5. Linux

See [http://www.redhat.com/docs/manuals/enterprise/RHEL-AS-2.1-Manual/cluster-manager/s1-service-mysql.html] {multi-excerpt-include:wikicontent:Exit Disclaimer to Include|name=ExitDisclaimer|nopanel=true}.

h5. Windows

When installing MySQL server on Windows, choose the option to run MySQL as a Windows service.

h2. Post-Installation Tasks

h3. Using UPT to Administer caIntegrator Users

To add and administer caIntegrator users in the UPT, refer to the [caIntegrator User's Guide|https://wiki.nci.nih.gov/x/mwPTAg]






h2. Default Users

The following users are provided by default by the caIntegrator installer.

* ncimanager / changeme
* nciinvestigator / changeme
* cai2admin / changeme - This is the UPT user who will have access to provision caIntegrator users.

h2. Contacting Application Support

| *NCICB Application Support* | [http://ncicb.nci.nih.gov/NCICB/support|http://ncicb.nci.nih.gov/NCICB/support] \\
Telephone: 301-451-4384 \\
Toll free: 888-478-4423 |