NIH | National Cancer Institute | NCI Wiki  

Error rendering macro 'rw-search'

null

Versions Compared

Old Version 36

changes.mady.by.user Unknown User (hadfielj)

Saved on

compared with

New Version 37

changes.mady.by.user Unknown User (hadfielj)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Welcome to the caIntegrator 1.4 Local Installation Guide. Topics in this document include:

Table of Contents
minLevel2

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.

...

  1. Downloading and installing required software
  2. Setting environment variables
  3. Downloading caIntegrator v.1.4 distribution files
  4. Installing
    1. GUI Installer Method
    2. Command-Line Method
  5. Configuring JBoss servers and MySQL server to run as a service
  6. Post-Installation Tasks
    1. Using UPT to Add caIntegrator Users

...

  1. 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
  2. Log out and log back in so that the system recognizes your changes.

...

  1. From the command line, enter:
    echo $JAVA_HOME
    echo $ANT_HOME
    Both of these commands should return the location where you installed these tools.
  2. To verify your Java SDK installation, enter java --version from a command prompt. You should see java version "1.6.0_31".
  3. To verify your Ant installation, enter: ant --version from a command prompt. You should see: Apache Ant version 1.8.2
Windows

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

...

  1. From the command line, enter:
    echo %JAVA_HOME%*
    echo %ANT_HOME%*
    Both of these commands should return the location where you installed these tools.
  2. To verify your Java SDK installation, enter java --version from a command prompt. You should see java version "1.6.0_31".

  3. To verify your Ant installation, enter ant --version

    Info
    titleOther 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).

...

To download and install MySQL, follow the steps outlined on the MySQL website

Wiki Markup
{multi-excerpt-include:wikicontent:Exit Disclaimer to Include|name=ExitDisclaimer|nopanel=true}

.

Tip
titleTip

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

    Wiki Markup
    {multi-excerpt-include:wikicontent:Exit Disclaimer to Include|name=ExitDisclaimer|nopanel=true}
  • Performance
Tip
titleMore 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.

...

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.

...

...

  • 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
titleServer 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)

...

GUI Installer Method of Installation

...

  1. 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.
  2. 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.
  3. Review the release notes.
  4. You must accept the license agreement.
  5. Select the Install installation type. For a new installation, select Install.
  6. 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.
  7. 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.
  8. 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.
  9. JBoss Installation Options
  10. 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.
  11. If your JBoss is externally accessible then fill out the JBoss External Hostname Configuration page. Otherwise, leave it blank and continue.
  12. For a standard installation of caIntegrator, do not use SSO.
  13. Specify the authentication type that caIntegrator should use. Database is the most likely choice if you aren't sure what to select here.
  14. 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.
  15. 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.
  16. 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.
  17. 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.
  18. Review the summary of the information you entered.
  19. 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.
  20. When you are informed that the process is finished, click Done in the lower right corner of the wizard to close the installer.
  21. To verify caIntegrator installation:
    1. Open your web browser to installed instance. The URL follows this format: http://<jboss.server.hostname>:<jboss.server.port>/caintegrator/workspace.action.
    2. 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.
  22. 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.

...

  1. 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:
    1. 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.

    2. 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
      titleAbout 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.

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

  3. Record the property values you have set.

    Info
    titleOther 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.

  4. 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.
  5. 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.
  6. After successfully installing caIntegrator, make a backup of the <installer_directory>/install.properties file in a different directory for future reference.

...

Note
titleBEFORE 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.

...

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 caIntegrator 1.4 Local Installation Guide.

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.

Upgrading caIntegrator Using the GUI Installer

...

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. Review the release notes.
  6. You must accept the license agreement to continue.
  7. Select the Install installation type in step #4.
  8. Select JBoss in step #6.
  9. Configure the JBoss Server-related settings.
  10. 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.
  11. Review the summary of gathered information.
  12. Click Next to proceed through the next two pages.
  13. After you click Next from reviewing the installation destination, the installer runs. The installation wizard displays the installation progress and completion.
  14. When you are informed that the process is finished, click Done in the lower right corner to close the installation wizard.
  15. At this point if you open your web browser to the installed instance you will see a MYSQLGrammerException error displayed.
  16. Before invoking the GUI installer again, stop the server.
  17. 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.
  18. 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.
  19. You must accept the license agreement to continue.
  20. Select the Upgrade installation type in step #4.
  21. Select Everything in step #6.
  22. Configure the JBoss Server-related settings.
  23. 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.
  24. Review the summary of gathered information.Review the selected upgrade installation type and the upgrade destination.
  25. Click Next to proceed through the next two pages.
  26. After you click Next from reviewing the installation destination, the installer runs. The installation wizard displays the installation progress and completion.
  27. 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.
  28. Once the update is verified you can delete the JBOSS4 directory.

...

  1. 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.
  2. 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.
  3. Delete the caintegrator2-install-1.3.1.zip file from its directory such as the application.base.path directory.
  4. 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:
    1. 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.
    2. Use WinZip or a similar utility to unzip the files.
  5. When asked if you would like to replace the existing files, respond All.
  6. 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.
  7. 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.

  8. 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
    titleModifying 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.

  9. 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.
  10. 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.
  11. If you open the application now in a browser window you will see a MYSQLGrammerException error.
  12. Stop the server.
  13. 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.
  14. 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.
  15. From the command line, navigate to the directory where you unzipped the installer file and type ant upgrade:database.
  16. Restart the server.
  17. 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.
  18. Once the update is verified you can delete the JBOSS4 directory.

...

To configure JBoss in Windows, follow these steps.

  1. 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
    titlePhysical 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.

    Warning
    titleWarning

    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.

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

    Wiki Markup
    {multi-excerpt-include:wikicontent:Exit Disclaimer to Include|name=ExitDisclaimer|nopanel=true}

    for more information.

Configuring JBoss Servers and MySQL Server to Run as Services

Info
titleJBoss & 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

Running JBoss as a Service

...

See http://wiki.jboss.org/wiki/Wiki.jsp?page=StartJBossOnBootWithLinux

Wiki Markup
{multi-excerpt-include:wikicontent:Exit Disclaimer to Include|name=ExitDisclaimer|nopanel=true}

.

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.

Running MySQL as a Service

...

See http://www.redhat.com/docs/manuals/enterprise/RHEL-AS-2.1-Manual/cluster-manager/s1-service-mysql.html

Wiki Markup
{multi-excerpt-include:wikicontent:Exit Disclaimer to Include|name=ExitDisclaimer|nopanel=true}

.

Windows

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

...