Kewill Customs Installations Guide

Kewill Customs Installations Guide for Release 1.1.3 Original Publication: June, 2008 Last Revision: March, 2009

Table of Contents Table of Contents...2 Kewill Customs Installation Guide...4 Installation and Implementation Requirements...4 Application Server...4 I. Minimum Client Requirements...5 II. Minimum Citrix Requirements...5 Please Note: For Remote Customer Site Implementation...5 Kewill Customs Release 3-tier Setup...6 Three-Tier Prerequisites...6 Release Number Nomenclature...6 Three-Tier Setup Procedures...7 Three-Tier Configuration Procedures...7 Installation of Apache Tomcat on AIX...10 Steps for Setting Up Apache Tomcat on AIX...10 Starting Tomcat...11 Stopping Tomcat...11 Kewill Customs Logs...12 Troubleshooting Kewill Customs...12 Kewill Customs Adapter Installation...14 Adapter Prerequisites:...14 Tomcat Configuration for RMS:...14 Tomcat Configuration for Oracle:...15 Installation of Tomcat Program...16 Configuring the Database Connection - Oracle:...16 Configuring the Database Connection - Connx:...17 Kewill Customs Troubleshooting...18 KC Install-2

Resolving the Issue of Growing Java Cache...19 How to Limit the Growth of the Java Cache:...19 Appendix 1 -- Installing Java Notes...23 Appendix 2 -- Installing Tomcat Notes...25 Appendix 3 Database Upgrade...27 KC Install-3

Kewill Customs Installation Guide Overview This document contains the following: Installation requirements for the Kewill Customs application. Installation and configuration instructions for the 3-Tier Setup. Installation and configuration of Kewill Customs Adapters for Windows. Installation and Implementation Requirements Application Server Hardware & System Requirements Application Server to run KC Server component and Web server: This is typically the same configuration of the machine that runs Alliance (Integrity or AIX). Typically the same machine as Alliance can be used for this purpose, if additional resources are made available to that box as specified here. Direct network access or dedicated network to the database server (Alpha, as/400, etc.). The server must be connected to the high speed network. JDBC Connectivity. Java JDK 1.5 64-bit runtime. Oracle JDBC/user for Oracle (This is included free with Oracle). KC desktop client executes on client systems or in a TSS/Citrix environment. KC Install-4

I. Minimum Client Requirements Minimum Requirements 2 GHz or better processor. 512MB memory is the minimum, 1GB is optimal. 10 GB of free disk space. Windows XP (e.g., Business edition meaning XP Pro and not XP Home). Direct network access to the Application server (10/100 LAN or similar). Sun Java Runtime 1.5 or greater. OR II. Minimum Citrix Requirements Minimum Requirements 2 GHz processor or better 200 MB memory/user. This is in addition to OS requirements. Note: 64 bit server may be desired for large implementations to accommodate more users/server. 32 bit servers have a memory limitation. 5-10 GB of free disk space per user. Current TSS or Citrix OS. Direct network access to the Application server - preferably high speed Sun Java Runtime 1.5 or greater (Available at Java.com). Please Note: For Remote Customer Site Implementation Implementation Notes for Remote Customers The implementation of Kewill Customs at remote customer sites over a WAN requires Citrix or TSS to provide the required performance for remote sites. The remote client sites would access the application server through the Citrix or TSS server. The Citrix or TSS server must be local to the application server as well. If it cannot be local, a high speed connection between the two is required. KC Install-5

Kewill Customs Release 3-tier Setup Overview This document describes the general procedure for setting up Kewill Customs on a 3-tier environment. Included in this section are the following: Prerequisites Release Number Nomenclature Setup Procedures Configuration Procedures Troubleshooting Three-Tier Prerequisites Prerequisites Java JDK 1.5 Runtime must already be installed. [If not, refer to installation of Java to specific platforms.] Apache Tomcat is already installed and running. [If not, refer to Installation of Apache Tomcat on AIX section.] Oracle Database is already running and installed with Alliance R06 schema. IP address of the Application Server. Release Number Nomenclature Overview Kewill Customs releases are named with the following nomenclature: Example: Release 1_2_3 where 1 = Major Release version #1 2 = Min or Release version #2 3 = Patch version #3 KC Install-6

Three-Tier Setup Procedures Overview The table below provides the steps required for the setup process. Step Action Comment 1 Get Kewill Customs web archive file kcustoms.war from supplied media. 2 Transfer kcustoms.war to the home directory of Alliance user. 3 Log in to the application server using telnet. Copy kcustoms.war to /kcustoms/apache-tomcat- 5.5.26/webapps. 4 At this point, the war file should have been automatically exploded by Tomcat. If not, try to stop and restart Tomcat. Refer to section Kewill Customs running Apache Tomcat on AIX on how to stop and restart Tomcat. Three-Tier Configuration Procedures Step Action Comment 5 Once exploded, navigate to /kcustoms/apache-tomcat- 5.5.26/webapps/kcustoms Edit icustoms.jnlp to point web start to the correct URL. To point web start to the correct URL, replace and set the following lines: From: <property name="icustoms.primary.url" value="http://10.146.1.171:8080/ kcustoms/maincontroller"/> To: <property name="icustoms.primary.url" value="http://host_ip:8080/ kcustoms/maincontroller"/> Where: HOST_IP is the IP address of the KC Install-7

Step Action Comment application server that is hosting Tomcat and visible to users. 6 Navigate to /kcustoms/apache-tomcat- 5.5.26/webapps/kcustoms/WEB-INF Edit web.xml to point the server component to correct URL. To point the server component to the correct URL replace and set the following lines: From: <init-param> </init-param> To: <init-param> <param-value>http:host_ip:8080/ <paramname>icustoms.primary.url</paramname> <paramvalue>http://10.146.1.171:8080/ kcustoms/maincontroller</paramvalue> <paramname>icustoms.primary.url</paramname> kcustoms/maincontroller</paramvalue> </init-param> Note: See definition ofhost_ip on Step 5 above. 7 Navigate to /kcustoms/apache-tomcat- 5.5.26/webapps/kcustoms/WEB- INF/classes. Edit log4j.xml, and point the log file to appropriate location. 8 Navigate to /kcustoms/apache-tomcat- 5.5.26/webapps/kcustoms/WEB- INF/classes/META-INF. Edit persistence.xml to point to correct database server and database username. Example: <param name="file" value="/ kcustoms/logs/customs.log" /> To point to the correct database server and database username, replace and set the following lines: <property name="toplink.jdbc.url" value="jdbc:oracle:thin:@database_ip :1521:DATABASE_SID" /> <property name="toplink.jdbc.user" value="db_schema" /> <property name="toplink.jdbc.password" KC Install-8

Step Action Comment value="db_password" /> Where: DATABASE_IP is the IP address of the database server. DATABASE_SID is the name of Oracle database. Usually, the dba should provide this info. DB_SCHEMA is the database username that were created to access Alliance database. The default for Kewill Customs is kcapps. DB_PASSWORD is the password of database username. The default for Kewill Customs is kcapps. 9 Restart Tomcat to put the new settings into effect. The application should be accessible on this URL: http:host_ip:8080/kcustoms/ Note: See definition ofhost_ip on Step 5 above. KC Install-9

Installation of Apache Tomcat on AIX Prerequisites IP address of the application server Java JDK 1.5 64 bit runtime. Unix username for Alliance. Mount point /kcustoms with 10GB space. Steps for Setting Up Apache Tomcat on AIX Step Action Comment 1 Get apache-tomcat-5.5.26.tar.gz from the installation media. 2 Ftp apache-tomcat-5.5.26.tar.gz to home directory of alliance e.g. /home/alliance. 3 Copy apache-tomcat-5.5.26.tar.gz to /kcustoms. 4 Unzip apache-tomcat-5.5.26.tar.gz, using unzip or gunzip, e.g. gunzip apachetomcat-5.5.26.tar.gz 5 Extract or untar apache-tomcat-5.5.26.tar, e.g. tar xvf apache-tomcat-5.5.26.tar. 6 Navigate to /kcustoms/apache-tomcat- 5.5.26/bin, and edit catalina.sh. Right after the commented lines, add the following 2 lines. (See below for the two lines to be added.) Add these 2 lines: JAVA_HOME=/usr/java5; export JAVA_HOME JAVA_OPTS='-Xmx1536m -Xmaxe256m -Djava.awt.headless=true - Dicustoms.abi.root.dir=/alliance/RUNTIME/ - Dicustoms.abi.control.filename=/alliance/RUNTIME/ABD/ABICTL - Dlogger.level=TRACE - Dicustoms.primary.url=http://localhost:8080/icustoms/MainControl ler'; export JAVA_OPTS KC Install-10

Starting Tomcat Step Action Comment 1 Login as alliance username using telnet. 2 In $ or shell prompt, type in ps eaf grep java. If Kewill Customs is running, the result of the command will look like below. If so, proceed to Stopping Tomcat. If not, proceed to step 3. 3 Navigate to /kcustoms/apache-tomcat- 5.5.26/bin 4 Then type in./catalina.sh start 5 To verify that the application is up and running, use the command in step 2. Expected Command Results alliance 827588 1 124 11:13:46 pts/7 69:24 /usr/java5/bin/java -Xmx1536m -Xmaxe256m - Djava.awt.headless=true - Dicustoms.abi.root.dir=/alliance/RUNTIME/ -Dlogger.level=TRACE - Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djava.util.logging.config.file=/kcustoms/apache-tomcat- 5.5.26/conf/logging.properties - Djava.endorsed.dirs=/kcustoms/apache-tomcat- 5.5.26/common/endorsed -classpath :/kcustoms/apache-tomcat- 5.5.26/bin/bootstrap.jar:/kcustoms/apache-tomcat- 5.5.26/bin/commons-logging-api.jar - Dcatalina.base=/kcustoms/apache-tomcat-5.5.26 - Dcatalina.home=/kcustoms/apache-tomcat-5.5.26 - Djava.io.tmpdir=/kcustoms/apache-tomcat-5.5.26/temp org.apache.catalina.startup.bootstrap start Stopping Tomcat Step Action Comment 1 Log in as Alliance username using telnet. 2 Navigate to /kcustoms/apache-tomcat- 5.5.26/bin 3 Type in./catalina.sh stop KC Install-11

Step Action Comment 4 Use the command in step 2 of Starting Tomcat to verify that application is really stopped. If it is not, proceed to step 5. 5 For some reason if the process of java is still hanging around after stopping it. Use kill -9 to hard stop the process. This command will abruptly kill the process and throw away any pending transaction, so use this command carefully. Note Alliance username must be used in restarting and stopping Kewill Customs because its environment is set accordingly. Kewill Customs is a stateless application so the users don t have to log out of their screens. The application should be able to recover once the server is up and running. Kewill Customs Logs Kewill Customs Logs The logs can be found in the following directory: 1. /kcustoms/logs log files that are specific to Kewill Customs processes. 2. /kcustoms/apache-tomcat-5.5.26/logs log files for Apache Tomcat. The log files can grow and be useful for debugging and troubleshooting purposes. They can be periodically cleaned up, as needed, e.g., /kcustoms mount point is running out of space. Troubleshooting Kewill Customs To check if Kewill Customs is operating correctly The URL below can be used to check if Kewill Customs is operating correctly. Use a browser to pull up: http://ip_address:8080/kcustoms/maincontroller Example: http://69.48.135.27:8080/kcustoms/maincontroller The response should be:hello!maincontroller is alive and well. To check the memory usage The URL below can be used to check the memory usage and manage the instances of Kewill Customs web application context. Use a browser to pull up: http://ip_address:8080/manager/status KC Install-12

Example: http://69.48.135.29:8080/manager/status (See below for sample Status results). Sample Status: Note The Total memory must not exceed or be equal to Max memory. If it is, the Kewill Customs application needs to be restarted. KC Install-13

Kewill Customs Adapter Installation Overview The following table describes the installation steps for the Kewill Customs Adapter. The instructions have been separated into three areas: 1. Prerequisites 2. Tomcat Configuration 3. Installation of Program 4. Configuring the Database Connection Adapter Prerequisites: Prerequisites required for installation: 1. Sun JDK version 1.5 2. Apache Tomcat version 5.5 or higher (or other comparable Servlet Container). Apache Tomcat can be downloaded at: http://tomcat.apache.org/download-55.cgi Tomcat Configuration for RMS: Windows: 1. Open the Tomcat Configuration tool. 2. Click on the Java tab 3. Append the following line to the Java Options: -Dicustoms.database.type=RMS [See screenshot below] KC Install-14

Sample of change in Apache Tomcat Properties window: Unix/Linux 1. Edit <Tomcat_Install>/bin/catalina.sh 2. Append the following line to the JAVA_OPTS -Dicustoms.database.type=RMS Tomcat Configuration for Oracle: Note for Oracle: No special configuration is required for Oracle. KC Install-15

Installation of Tomcat Program Note on using a Servlet Container other than Tomcat These installation instructions are for Tomcat. Please read the web archive deploy instructions of the Servlet Container if using a Servlet Container other than Tomcat. Step Action Comment Copy the compressed program file adapter.war to the <Tomcat Install>/webapps folder. Start Tomcat if it is not already started. Tomcat will create a new folder called adapter under webapps. The adapter folder contains the extracted application files. Configuring the Database Connection - Oracle: Step Action Comment Navigate to the folder: <Tomcat Install>/webapps/adapter/ WEB-INF/classes/META-INF Edit the file persistence.xml Locate the <properties> tag within the file. Set the correct values for the following properties: a. toplink.jdbc.url the database connection string e.g. for Oracle : jdbc:oracle:thin:@<database server>:<port>:<sid> The correct values should be substituted for <database server>, <port>, <sid>. [Contact the database administrator to find out these KC Install-16 It should be towards the end of the file.

values.] b. toplink.jdbc.user the database username c. toplink.jdbc.password the password for the above database user Configuring the Database Connection - Connx: Step Action Comment Navigate to the folder: <Tomcat Install>/webapps/adapter/ WEB-INF/classes/META-INF Edit the file persistence.xml Locate the <properties> tag within the file. Comment out the Oracle Connection properties and uncomment the Connx Connection properties. Set the correct values for the following properties: a. toplink.jdbc.url the database connection string For Connx : jdbc:connx:dd=<dsn>;gateway=< gateway>;port=7500 The correct values should be substituted for <DSN>, <gateway>. [Contact the database administrator to find out these values.] b. toplink.jdbc.user the database username c. toplink.jdbc.password the password for the above database user You are done. It should be towards the end of the file. KC Install-17

Kewill Customs Troubleshooting Troubleshooting Section Contents Included in this Troubleshooting section is the following: How to Resolve the Issue of a Growing Java Cache KC Install-18

Resolving the Issue of Growing Java Cache Overview By default, Java cache is set to grow to 1GB. The cache is used by Java to store applets and Java application that the user visited from any web site that is hosting Java application, e.g., Kewill Customs, or applets from the stock exchange. To limit the size of the cache, follow the steps below. How to Limit the Growth of the Java Cache: Step Action 1 Go to the Windows Control Panel and switch to Classic View, as shown in the example below. Windows Control Panel: KC Install-19

Step Action 2 From the list, double-click on Java. The Java Control Panel page will display. Java Control Panel: Step Action 3 On the General Tab page, click the Settings button. The Temporary Files Settings page will display. KC Install-20

Temporary Files Settings: Step Action 4 On the Temporary Files Settings page, set the Disk Space to 200MB. This will limit the cache to 200MB. 5 To make sure that Kewill Customs is the only Java application installed, go to the General Tab and click the View button.. The Java Cache Viewer will display. KC Install-21

Java Cache Viewer: Step Action 6 On the Java Cache Viewer grid, if there are multiple versions, you can remove the older version and leave the latest one. KC Install-22

Appendix 1 -- Installing Java Notes Notes Action Comment 1 When installing java, change the Install Folder from the default location [See screenshots below for sample.] For example: Change from C:\Program Files\Java\jdk1.5.0_14 Change to C:\Java\jdk1.5.0_14 2 Ensure that none of the folder names have spaces in them and are not too long. Sample of changing Java Install Folder from the default location: KC Install-23

Sample of modified Java Install Folder destination location: KC Install-24

Appendix 2 -- Installing Tomcat Notes Notes Action Comment 1 When installing Tomcat, change the Install Folder from the default location. [See screenshots below for sample.] For example: Change from C:\Program Files\Apache Software Foundation\Tomcat 5.5 Change to C:\Java\Apache\Tomcat5.5 2 Make sure that none of the folder names have spaces in them and are not too long. Sample of changing Tomcat Install Folder from the default location: KC Install-25

Sample of modified Install Folder destination location: KC Install-26

Appendix 3 Database Upgrade Database Upgrade Note that Database Upgrade must be done by a DBA or under supervision of Kewill DBA Services. The table below describes the steps required for upgrading the database. Notes Example The database scripts are cumulative; all scripts have to be run if upgrading from a base install. If upgrading from 1.0.0.1 to 1.0.3 then the scripts from 1.0.2 and 1.0.3 have to be run. Scripts upgrading from 1.0.2 to 1.0.3: Step Action 1 Run sqlplus, and login as TPSDBA (database schema of Kewill Customs). 2 Using sqlplus, run the following script from the installation media: upgrade\db-1.0.3\schema\ alter_table.sql Scripts upgrading from 1.0.0.1 to 1.0.2: Step Action 3 Run sqlplus, and login as TPSDBA (database schema of Kewill Customs). 4 Using sqlplus, run the following script from the installation media: a. upgrade\db-1.0.2\schema\ alter_table.sql b. upgrade\db-1.0.2\data\ table_relation_x_ref.sql c. upgrade\db-1.0.2\data\ validation_table_x_ref.sql Copyright 2009 Kewill, plc [last revision date: 03/19/09] KC Install-27