Download KC Installation Guide-1 1 3

Kewill Customs Installations Guide
for Release 1.1.3
Original Publication:
Last Revision:
June, 2008
March, 2009
Kewill Customs Installation Guide
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
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
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
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
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
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
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
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
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
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
Three-Tier Setup Procedures
Overview
Step
The table below provides the steps required for the setup process.
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-tomcat5.5.26/webapps.
4
At this point, the war file should have been Refer to section “Kewill Customs running
automatically exploded by Tomcat. If not, Apache Tomcat on AIX” on how to stop
try to stop and restart Tomcat.
and restart Tomcat.
Three-Tier Configuration Procedures
Step
5
Action
Comment
Once exploded, navigate to
/kcustoms/apache-tomcat5.5.26/webapps/kcustoms
To point web start to the correct URL,
replace and set the following lines:
Edit icustoms.jnlp to point web start to
the correct URL.
<property
name="icustoms.primary.url"
From:
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
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
Step
Action
Comment
application server that is hosting Tomcat
and visible to users.
6
Navigate to /kcustoms/apache-tomcat5.5.26/webapps/kcustoms/WEB-INF
To point the server component to the correct
URL replace and set the following lines:
Edit web.xml to point the server
component to correct URL.
From:
<init-param>
<paramname>icustoms.primary.url</paramname>
<paramvalue>http://10.146.1.171:8080/
kcustoms/MainController</paramvalue>
</init-param>
To:
<init-param>
<paramname>icustoms.primary.url</paramname>
<param-value>http:HOST_IP:8080/
kcustoms/MainController</paramvalue>
</init-param>
Note: See definition of HOST_IP on Step 5
above.
7
Navigate to /kcustoms/apache-tomcat5.5.26/webapps/kcustoms/WEBINF/classes.
Example:
<param name="File" value="/
kcustoms/logs/customs.log" />
Edit log4j.xml, and point the log file to
appropriate location.
8
Navigate to /kcustoms/apache-tomcat5.5.26/webapps/kcustoms/WEBINF/classes/META-INF.
To point to the correct database server and
database username, replace and set the
following lines:
Edit persistence.xml to point to correct
database server and database username.
<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
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
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 of HOST_IP on Step 5
above.
KC Install-9
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
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
(See below for the two lines to be added.)
Navigate to /kcustoms/apache-tomcat5.5.26/bin, and edit catalina.sh. Right after
the commented lines, add the following 2
lines.
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
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
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-tomcat5.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-tomcat5.5.26/conf/logging.properties Djava.endorsed.dirs=/kcustoms/apache-tomcat5.5.26/common/endorsed -classpath :/kcustoms/apache-tomcat5.5.26/bin/bootstrap.jar:/kcustoms/apache-tomcat5.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-tomcat5.5.26/bin”
3
Type in “./catalina.sh stop”
KC Install-11
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
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.
Note
This command will abruptly kill the process
and throw away any pending transaction, so
use this command carefully.

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
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
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
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
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
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
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
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
Installation of Tomcat Program
Note on using a Servlet These installation instructions are for Tomcat. Please read the web archive
Container other than deploy instructions of the Servlet Container if using a Servlet Container other
Tomcat
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:
It should be towards the end of the file.
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
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
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:
It should be towards the end of the file.
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.
KC Install-17
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
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
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
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
1
Action
Go to the Windows Control Panel and switch to “Classic View”, as shown in
the example below.
Windows Control Panel:
KC Install-19
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
Step
Action
2
From the list, double-click on Java. The Java Control Panel page will display.
Java Control Panel:
Step
3
Action
On the General Tab page, click the Settings button. The Temporary Files
Settings page will display.
KC Install-20
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
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
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
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
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
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
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
Sample of modified Java Install Folder destination location:
KC Install-24
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
Appendix 2 -- Installing Tomcat Notes
Notes
1
Action
Comment
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
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
Sample of modified Install Folder destination location:
KC Install-26
Copyright © 2008-2009 Kewill, plc
Kewill Customs Installation Guide
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
Copyright © 2008-2009 Kewill, plc