Detailed Installation Instructions for caTIES

Preinstallation

Please review the minimum system requirements table at the end of this document.

We recommend installing this application in a virtual machine (VM), preferably in Server 2008
or 2003. Further, the install should be in the Datacenter Edition if datasets will be large and will
ultimately be used by a number of users simultaneously. This server should have a dedicated IP
address and the VM(s) should share this address.

The VM should have at least 250 GB of hard disk space to have space for installing all software
and subsequent databases.

With caTIES installed in a VM, it could be ported to another server without needing to again
install all of the applications and caTIES itself.

Before installing caTIES, it’s also important to have a good understanding of all components to
be installed, where folders are to be placed, and which environmental variables need to be set.

We recommend downloading all software requirements (programs to be installed prior to when

caTIES is installed) and placing them all on a removable drive. Be sure to pay close attention to
program versions downloaded as this is an important consideration. For example, caTIES v3.6B1
does not work with Tomcat versions later than 5.5. Therefore, if you install Tomcat 6.x then
caTIES won’t work.

Before beginning the install, create a new user and perform all of the install tasks logged in as
this user. In other words, don’t perform the install logged in as Administrator. This new user
account will also be used to run the Tomcat service, which is configured during the caTIES
installation. Do not make this user an administrator. Record this username and password here:

Tomcat service username: __________________________

Tomcat service password: __________________________
The link to the caTIES Preinstallation instructions Web site is:
http://caties.cabig.upmc.edu/Wiki.jsp?page=InstallOnOneMachine#section-
InstallOnOneMachine-SoftwareRequirements

All preinstall requirements must be met before installing caTIES.

The link to the caTIES download Web site is: (http://caties.cabig.upmc.edu/

Wiki.jsp?page=Download) will point you to the site of each application to be installed, mention
specific required settings, and obtusely recommend other important install tasks.

Some of the instructions refer to the DOS environment. In newer Windows versions, this is now
referred to as the “command line interface” or CLI.

Resources Required for Install in Windows XP Pro or Server 2003

Java SDK (v1.5):

• This begins Step 1 in the caTIES installation document.
• Instructions call for JDK v1.5. Check caTIES instructions to be sure a newer version is
allowed.
• Download from: http://java.sun.com/javase/downloads/index_jdk5.jsp
• Add “<jdk installation directory>\bin” to PATH environment variable.
• No other changes are needed to install this application.
• There is no need to test the Java install outside of viewing Add-ons through your
browser.

Apache Ant (v1.7.1):

• Download from: http://ant.apache.org/bindownload.cgi
• Install Ant at your root drive (c:\ant).
• Change installation folder name to “ant” (due to 8.3 filename limitations)
• Add “<ant installation directory>\bin” to PATH system variable.
• Create the JAVA_HOME and ANT_HOME environment variables. There is no need to
create the CLASS_PATH variable.
• Test Ant’s install by running the command “ant ui” (no dash or forward slash after the
ant command) from a DOS window.
◦ The install was successful if you get the ‘build failed’ message.
 ◦ Note: You may need to locate and copy the tools.jar from the JDK/BIN
directory to the JRE/BIN directory or vice-versa before your test will be
successful.
• Back up your virtual machine and hard drive before installing Tomcat. Label the backup
so you remember this was done after installing Apache Ant.

Tomcat (v5.5):
• Download from: http://tomcat.apache.org/download-55.cgi#5.5.27
• During install:
◦ Ensure “Native” option is not checked.
◦ Add “WebApps” functionality.
◦ Use default ports (8080 and 8443).
◦ Use default paths
◦ Do not install SSI and CGI.
◦ Write down the admin username and password you create.
▪ Admin username: _______________________
▪ Admin password: _______________________
• After install:
◦ Configure the Apache Tomcat service to run under a specific user account and
not the Local System Account.
◦ Configure the Apache Tomcat service to start automatically.
◦ Test Tomcat’s install by opening a browser and typing the following URL:
http://localhost:8080.
◦ Test Tomcat by clicking Status (top left corner of browser) and log in using the
admin username and password you recorded during installation. This is Step 6
in the caTIES installation document. It’s out of order, but correct to do this test
now.
▪ After logging into Tomcat, click List Applications from the table and
then click WSRF from the Applications table. You should see services
running.
▪ If you encounter WSRF errors, refer to WSRF Fix at the end of this
document.
• Back up your virtual machine and hard drive before installing MySQL. Label the backup
so you remember this was done after installing Tomcat.
MySQL (v5.1):
• Download from: http://dev.mysql.com/downloads/mysql/5.1.html
• Before install
◦ Add the install path to the PATH system variable. Include the bin subfolder in
the path (e.g. ‘c:\program files\mysql server 5.1\mysql\bin’).
• During install:
◦ Use install defaults unless otherwise noted.
▪ Port 3306
▪ Enable “Strict mode”
◦ Select ‘Complete installation’ not ‘Typical installation’.
◦ Select the ‘Configure the MySQL Server now’ option.
◦ Write down the admin (root) password you create.
▪ Admin username: root
▪ Admin password: _______________________
• After install:
◦ Locate MySQL.ini and add a line to configure max_allowed_packet = 16Mb
(this should be one string with no spaces before/after the equal sign)
◦ Test MySQL by launching the MySQL Command Line Client from a DOS
window. Log in as root.
◦ Be sure the MySQL service is running if you get an error.
◦ Open a DOS window and test the install.
▪ Navigate to the MySQL 5.1/bin directory and type:
MySQL –u root pw-password_you_created
▪ If you receive an instance error, you may need to reconfigure MySQL.
Do this by launching the MySQL Instance Configuration Wizard (from
the All Programs\SQL Server link).
• Delete the existing instance.
• Create another one, using all default settings (they are already
selected).
▪ If you receive a service error you might need to stop and start the
service.
▪ If start/stop does not work, change the service logon to use the same
logon and password as Tomcat uses.
▪ Don’t install MMTx until you’ve proven that MySQL functions
normally.
 ▪ Back up your virtual machine and hard drive before installing MMTx. Label the backup
so you remember this was done after installing MySQL.

MMTx:

Installation Instructions URL:

http://ii-public.nlm.nih.gov/MMTx/Download/download.shtml

Windows Installation Instructions (different from Linux):

• Download from: http://dev.mysql.com/downloads/mysql/5.1.html
• Download the latest version of MMTx and any of the optional data models into the
directory created in #1. Do not download MetaMap!
• Create the mmtx directory at the root drive.
• Create environment system variable “MMTX_PATH” with the value of the MMTx
installation directory.
• In DOS, change directory to the directory created in #1: cd $MMTX_PATH
• Extract the jar files to $MTX_PATH using winzip, pkzip, or zip! There is a bug in the
java jar program that removes file permissions leaving the embedded cygwin
executables un-runable. Unzip in the following order:
◦ Run winzip, pkzip, or zip on the mmtx_V2.4.C_base.jar
◦ Run winzip, pkzip, or zip on the mmtx_V2.4.C_2006_common_data.jar
◦ Run winzip, pkzip, or zip on the mmtx_V2.4.C_2006_strict_data.jar
▪ NOTE: You don't need to unjar the optional data model files (files 2 and
3 above) if you downloaded them - they will be processed via the install
program.
• The above unjar (unzip or extraction) actions will create the nls/mmtx directory under
your MMTX_PATH directory and fill it with all of the program files needed to run the
MMTx program.
• Now, change your DOS location to the mmtx directory: cd nls/mmtx. You must run the
script on the next step from this location. Do not run the script from any other location or
through Windows. (Double-clicking on the script name from the explorer window will
not work.)
• Run the install script by typing “\bin\install.bat” (without the quotes) from the DOS
command window by issuing the install.bat command.
 ◦ Remember that the size of the MMTx file is over 1 GB in size. The script may
take a long time to run. Don’t end task prematurely. Check Task Manager and
you should be able to verify that it is running through processes, RAM, and
CPU utilization.
◦ When the script runs, answer YES to add a registry entry for CYGWIN.
◦ If you receive a script error about a missing install.log file, create one via
Notepad and put the file in the nls/mmtx/logs directory. Then, run the script
again if needed.
• If you have successfully installed the programs and data, you no longer need the optional
data files that you might have downloaded. The *.jar files located in the
$MMTX_PATH directory are also no longer needed. If you are concerned about disk
space, all of these files may now be deleted.
• Test that your unjar actions by navigating to <drive_letter>:\mmtx\nls\mmtx. You
should see a number of folders (15) and one text file (readme.txt). This proves that
MMTx unjarred its files.
• Back up your virtual machine and hard drive before installing NCI. Label the backup so
you remember this was done after installing MMTx.

NCI Metathesaurus for MMTX:

• Download from http://caties.cabig.upmc.edu/ROOTbak/downloads/ncimeta-0601.zip.
• Unzip the downloaded file to mmtx/nls/mmtx/data directory.
◦ Note that the NCI instructions tell you to create this directory before unzipping
the file. However, the data directory was created when you unjarred MMTx.
Verify this before unzipping the NCI file.
◦ The NCI file is over 1 GB in size. The unzip action may take a long time to run.
Don’t end task prematurely. Check Task Manager and you should be able to
verify that it is running through processes, RAM, and CPU utilization.
◦ There are no options or paths to select when unzipping NCI.
• There is no need to test the NCI unzip action.
• Option: Back up your virtual machine and hard drive before installing caTIES. Label the
backup so you remember this was done after installing the NCI Metathesaurus.
CaTIES
This section references the installation guide on the caTIES wiki.
It can be found here:
http://caties.cabig.upmc.edu/Wiki.jsp?page=InstallOnOneMachine

• Before install:
◦ If you will be using DeID, add its installation path (C:\Program Files\DeID) to
the Path environment variable.
◦ Manually stop the Apache Tomcat service. This is Step 2 in the caTIES
installation document.
◦ Ensure that the MySQL service is still running and is set to automatically start
(not “Manual”).
◦ Create the caties directory at the root drive.
◦ Create the Tomcat_user’s home directory (same user you created for the Tomcat
service) at the root drive. Name the directory TC_home.
▪ Give the above user full control of this directory for both sharing and
NTFS permissions.
• Download the caTIES installer from: http://caties.cabig.upmc.edu/
Wiki.jsp?page=Download
• During install:
◦ This begins Step 3 in the caTIES installation document.
◦ Install caTIES to the caTIES directory you created above at the root drive.
◦ Choose the single machine installation type.
◦ Continue the install using default database name, settings, and ports, which are
already selected for you by the installer.
◦ Enter your static IP address for caTIES server address.
◦ If you are running MySQL and caTIES on one machine, your static IP address
applies to any instance when you are asked to provide an IP address during the
install.
◦ Enter the password for the root user you created when installing MySQL.
◦ Enter OHSU for organization name and abbreviation.
◦ Create hl7_files directory at the root of the caTIES directory.
◦ Create the deid directory at the root of the caTIES directory.
◦ Don’t create any database (leave all as not selected).
 ◦ Modify the cog.properties file using Notepad. This file is in the profile of the
logged in user (e.g. c:\documents and settings\user\.globus\cog.properties file.
This is Step 4 in the caTIES installation document.
▪ This step is very important. If you don’t do it correctly, caTIES will not
start properly and subsequent steps will not be done correctly.
▪ Remember the 8.3 (old DOS) rules when making this change.
▪ You need to replace the long pathname in the file with its short name
version. For example, 'c:\documents and
settings\<username>\.globus\certificates' is replaced with 'c:/docume~1/
<username>/globus~1/certif~1'. Use the dir /x command at the DOS
prompt to determine the 8.3 name for any directory or file.
• Remember to replace username with the user account name of
the logged in user.
• Remember to replace back slashes with forward slashes.
• Remember to remove the dot before the globus directory name.
• Don’t make any typing mistakes!
• Install errors:
◦ If you encounter an error asking for the createtablespace.sql file, open Notepad,
create the file with the SQL extension, and place the file in the caTIES\sql
directory. You do not need to type any text in this file as it appears to be a
placeholder that can stop the install process.
• After install:
◦ This is Step 5 in the caTIES installation document.
◦ Start the Apache Tomcat service. Be sure it is set to start automatically and that
it logs on using the Tomcat user you created.
• Export the local system’s Dorian certificate. This is Step 7 in the caTIES installation
document (Step 6 was done when you tested your Tomcat install).
◦ Open a DOS window.
◦ Navigate to the caties\security-ui directory, type "ant ui" and then press Enter to
start the GAARDS UI client.
▪ Select 'Grid Account Management' and then 'Dorian CA Certificate'
option.
▪ Click on ‘View Certificate’
▪ Select Export Certificate and save it to
c:\docume~1\<username>\.globus\certificates folder.
▪ Save the certificate as local_dorian.0
 ◦ Stop and restart the Apache Tomcat service for the changes to take effect.
• Test the caTIES Client. This is Step 8 in the caTIES installation document.
◦ The caTIES client can be accessed at: http://localhost:8080/caties/ (use your
browser).
◦ Select the 'Local Test CTRM' database.
▪ Note: instructions direct you to connect to the above database. This does
not work! Instead connect to the OSHU Test Data Network. This one
did work!
◦ Use the following account to login:
▪ Username:"dorian" (case should not matter, but use all lower-case, just
to be safe).
▪ Password:"password" (this is the actual password you are to type in, all
lower-case, without the quotes)
◦ You should be able to login and get access to the client as an administrator.
◦ Select the Dorian User from the left pane. Add the Honest Broker role to the
dorian user.
◦ Click save to record your selection of the Honest Broker role.
◦ Restart the caTIES client and login again. You should now see the honest broker
role available.
◦ Login using the honest broker role and run a few SQL select queries.
◦ Run a query and look at any report. All sections should contain information.
You should not be seeing any "Error retrieving identified information"
messages.
• The caTIES installation is now complete.
WSRF Fix (from the Tomcat installation)
The WSRF client included in Tomcat’s install package is dated. The current version is WSRF
v1.1.

Do not replace the version of WSRF with v1.1 unless you have install errors (you don’t see any
services).

You can download the v1.1 client from:

http://archive.apache.org/dist/ws/wsrf/1.1/wsrf-1.1.zip

Download the zip file and extract all of its contents to a folder you create.

Copy the entire current Tomcat\WebApps\WSRF directory to a safe location in case you need to
restore it.

Next, carefully replace any existing directory with its corresponding updated directory. Do not
delete files that are not replaced!

This can take a considerable amount of time. Take notes if you have to do this.

Stop and restart the Tomcat service after you replace all files/folders.

Launch Tomcat from a browser: http://localhost:8080, log in again and navigate back to the
WSRF directory. If you see services and not errors, you succeeded!
Minimum System Requirements

Java Tomcat MySQL NCI

caTIES ANT 1.6 MMTX
SDK 1.5 5.5 5.1 Meta
Minimum Requirements
1.5GHz
Processor or >
RAM 512 MB
HDD Space 5 GB+
Windows 98/ME/XP/2000 installed X
Microsoft Windows NT/2000/XP/2003/
Vista X X X X
Java SDK 1.5+ X X X
Apache ANT 1.6+ X X
Apache Tomcat 5.5 X
MySQL 5.1 X
MMTX X
NCI Metathesaurus (for MMTX) X
JAXP-compliant XML parser installed
and available on your classpath, such as
Xerces. This is included with ANT's
installer. X
J2SE 5.0 and later X
Disable virus protection on main
directory X
Needs its own temp directory with no
virus scan allowed X
Configure the Data File Builder module X