kewill customs installations guidelegacydocs.kewill.com/documentation/kc/kc... · kewill customs...

Kewill Customs Installations Guide

for Release 1.1.3

Original Publication: June, 2008

Last Revision: March, 2009

Kewill Customs Installation Guide

KC Install-2

Copyright © 2008-2009 Kewill, plc

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-3


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-4



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 & SystemRequirements

Application Server to run KC Server component and Web server: This istypically the same configuration of the machine that runs Alliance (Integrityor AIX). Typically the same machine as Alliance can be used for thispurpose, if additional resources are made available to that box asspecified 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/Citrixenvironment.


KC Install-5


I. Minimum Client Requirements

MinimumRequirements

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

MinimumRequirements

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 toaccommodate more users/server. 32 bit servers have a memorylimitation.

5-10 GB of free disk space per user.

Current TSS or Citrix OS.

Direct network access to the Application server - preferably high speedSun Java Runtime 1.5 or greater (Available at Java.com).

Please Note: For Remote Customer Site Implementation

Implementation Notesfor Remote Customers

The implementation of Kewill Customs at remote customer sites over aWAN requires Citrix or TSS to provide the required performance forremote sites.

The remote client sites would access the application server through theCitrix or TSS server. The Citrix or TSS server must be local to theapplication server as well. If it cannot be local, a high speed connectionbetween the two is required.


KC Install-6


Kewill Customs Release 3-tier Setup

Overview This document describes the general procedure for setting up Kewill Customson 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 toinstallation 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 R06schema.

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


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 filekcustoms.war from supplied media.

2 Transfer kcustoms.war to the homedirectory of Alliance user.

3 Log in to the application server usingtelnet.

Copy kcustoms.war to/kcustoms/apache-tomcat-5.5.26/webapps.

4 At this point, the war file should have beenautomatically exploded by Tomcat. If not,try to stop and restart Tomcat.

Refer to section “Kewill Customs runningApache Tomcat on AIX” on how to stopand 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 tothe correct URL.

To point web start to the correct URL,replace and set the following lines:

From:

<propertyname="icustoms.primary.url"

value="http://10.146.1.171:8080/kcustoms/MainController"/>

To:

<propertyname="icustoms.primary.url"

value="http://HOST_IP:8080/kcustoms/MainController"/>

Where:

HOST_IP is the IP address of the


KC Install-8


Step Action Comment

application server that is hosting Tomcatand visible to users.

6 Navigate to /kcustoms/apache-tomcat-5.5.26/webapps/kcustoms/WEB-INF

Edit web.xml to point the servercomponent to correct URL.

To point the server component to the correctURL replace and set the following lines:

From:

<init-param>

<param-name>icustoms.primary.url</param-name>

<param-value>http://10.146.1.171:8080/kcustoms/MainController</param-value>

</init-param>

To:

<init-param>

<param-name>icustoms.primary.url</param-name>

<param-value>http:HOST_IP:8080/

kcustoms/MainController</param-value>

</init-param>

Note: See definition of HOST_IP on Step 5above.

7 Navigate to /kcustoms/apache-tomcat-5.5.26/webapps/kcustoms/WEB-INF/classes.

Edit log4j.xml, and point the log file toappropriate location.

Example:

<param name="File" value="/kcustoms/logs/customs.log" />

8 Navigate to /kcustoms/apache-tomcat-5.5.26/webapps/kcustoms/WEB-INF/classes/META-INF.

Edit persistence.xml to point to correctdatabase server and database username.

To point to the correct database server anddatabase username, replace and set thefollowing lines:

<property name="toplink.jdbc.url"value="jdbc:oracle:thin:@DATABASE_IP:1521:DATABASE_SID" />

<property name="toplink.jdbc.user"value="DB_SCHEMA" />

<propertyname="toplink.jdbc.password"


KC Install-9


Step Action Comment

value="DB_PASSWORD" />

Where:

DATABASE_IP is the IP address of thedatabase server.

DATABASE_SID is the name of Oracledatabase. Usually, the dba shouldprovide this info.

DB_SCHEMA is the database usernamethat were created to access Alliancedatabase. The default for KewillCustoms is “kcapps”.

DB_PASSWORD is the password ofdatabase username. The default forKewill Customs is “kcapps”.

9 Restart Tomcat to put the new settingsinto effect.

The application should be accessible on thisURL: http:HOST_IP:8080/kcustoms/

Note: See definition of HOST_IP on Step 5above.


KC Install-10


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 theinstallation media.

2 Ftp apache-tomcat-5.5.26.tar.gz to homedirectory 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, usingunzip or gunzip, e.g. gunzip apache-tomcat-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 afterthe commented lines, add the following 2lines.

(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/MainController'; export JAVA_OPTS


KC Install-11


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 thecommand will look like below. If so, proceedto 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 andrunning, use the command in step 2.

Expected CommandResults

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/temporg.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-12


Step Action Comment

4 Use the command in step 2 of StartingTomcat to verify that application is reallystopped. If it is not, proceed to step 5.

5 For some reason if the process of java isstill hanging around after stopping it. Use“kill -9” to hard stop the process.

This command will abruptly kill the processand throw away any pending transaction, souse this command carefully.

Note Alliance username must be used in restarting and stopping KewillCustoms because its environment is set accordingly.

Kewill Customs is a stateless application so the users don’t have to log outof their screens. The application should be able to recover once the serveris 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 troubleshootingpurposes. They can be periodically cleaned up, as needed, e.g., /kcustomsmount point is running out of space.

Troubleshooting Kewill Customs

To check if KewillCustoms 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 memoryusage

The URL below can be used to check the memory usage and manage theinstances of Kewill Customs web application context. Use a browser to pull up:http://ip_address:8080/manager/status

http://69.48.135.27:8080/kcustoms/MainController

http://ip_address:8080/manager/status


KC Install-13


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.

http://69.48.135.29:8080/manager/status


KC Install-14


Kewill Customs Adapter Installation

Overview The following table describes the installation steps for the Kewill CustomsAdapter. 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 requiredfor installation:

1. Sun JDK version 1.5

2. Apache Tomcat version 5.5 or higher (or other comparable ServletContainer).

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-15


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-16


Installation of Tomcat Program

Note on using a ServletContainer other than

Tomcat

These installation instructions are for Tomcat. Please read the web archivedeploy instructions of the Servlet Container if using a Servlet Container otherthan Tomcat.

Step Action Comment

Copy the compressed program fileadapter.war to the

<Tomcat Install>/webapps folder.

Start Tomcat if it is not already started. Tomcat will create a new folder calledadapter under webapps. The adapterfolder contains the extracted applicationfiles.

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

It should be towards the end of the file.

Set the correct values for the followingproperties:

a. toplink.jdbc.url – the databaseconnection string

e.g. for Oracle :jdbc:oracle:thin:@<databaseserver>:<port>:<sid>The correct values should besubstituted for <databaseserver>, <port>, <sid>.

[Contact the databaseadministrator to find out these


KC Install-17


values.]

b. toplink.jdbc.user – the databaseusername

c. toplink.jdbc.password – thepassword for the above databaseuser

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

It should be towards the end of the file.

Comment out the Oracle Connectionproperties and uncomment the ConnxConnection properties.

Set the correct values for the followingproperties:

a. toplink.jdbc.url – the databaseconnection string

For Connx :jdbc:connx:DD=<DSN>;GATEWAY=<gateway>;PORT=7500

The correct values should besubstituted for <DSN>, <gateway>.

[Contact the database administratorto find out these values.]

b. toplink.jdbc.user – the databaseusername

c. toplink.jdbc.password – thepassword for the above databaseuser

You are done.


KC Install-18


Kewill Customs Troubleshooting

TroubleshootingSection Contents

Included in this Troubleshooting section is the following:

How to Resolve the Issue of a Growing Java Cache


KC Install-19


Resolving the Issue of Growing Java Cache

Overview By default, Java cache is set to grow to 1GB. The cache is used by Java tostore applets and Java application that the user visited from any web site thatis hosting Java application, e.g., Kewill Customs, or applets from the stockexchange.

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 inthe example below.

Windows Control Panel:


KC Install-20


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 FilesSettings page will display.


KC Install-21


Temporary Files Settings:

Step Action

4 On the Temporary Files Settings page, set the Disk Space to 200MB. This willlimit the cache to 200MB.

5 To make sure that Kewill Customs is the only Java application installed, go tothe General Tab and click the View button. . The Java Cache Viewer willdisplay.


KC Install-22


Java Cache Viewer:

Step Action

6 On the Java Cache Viewer grid, if there are multiple versions, you can removethe older version and leave the latest one.


KC Install-23


Appendix 1 -- Installing Java Notes

Notes Action Comment

1 When installing java, change the InstallFolder from the default location

For example: Change fromC:\Program Files\Java\jdk1.5.0_14

Change to C:\Java\jdk1.5.0_14

[See screenshots below for sample.]

2 Ensure that none of the folder nameshave spaces in them and are not toolong.

Sample of changing Java Install Folder from the default location:


KC Install-24


Sample of modified Java Install Folder destination location:


KC Install-25


Appendix 2 -- Installing Tomcat Notes

Notes Action Comment

1 When installing Tomcat, change theInstall Folder from the default location.

For example: Change fromC:\Program Files\Apache SoftwareFoundation\Tomcat 5.5

Change to C:\Java\Apache\Tomcat5.5

[See screenshots below for sample.]

2 Make sure that none of the foldernames have spaces in them and are nottoo long.

Sample of changing Tomcat Install Folder from the default location:


KC Install-26


Sample of modified Install Folder destination location:


KC Install-27


Appendix 3 – Database Upgrade

Database Upgrade Note that Database Upgrade must be done by a DBA or undersupervision of Kewill DBA Services.

The table below describes the steps required for upgrading the database.

Notes The database scripts are cumulative; all scripts have to be run if upgradingfrom a base install.

Example If upgrading from 1.0.0.1 to 1.0.3 then the scripts from 1.0.2 and 1.0.3 have tobe 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]

kewill customs installations guidelegacydocs.kewill.com/documentation/kc/kc... · kewill customs...

Documents