Kewill Customs Installations Guidelegacydocs.kewill.com/documentation/KC/KC... · Kewill Customs is a stateless application so the users don’t have to log out of their screens

Kewill Customs Installation Guide

KC Install - 1

Copyright © 2008 – 2010 by Kewill Inc.

Kewill Customs Installations Guide

For Release 2.0.3 – Alliance R07 Patch 2 Hotfix 1 Compatible

Original Publication: June, 2010


KC Install - 2


Table of Contents

Table of Contents..................................................................................................................................... 2

Kewill Customs Installation Guide......................................................................................................... 4

Installation and Implementation Requirements ................................................................................ 4

Application Server ............................................................................................................................... 4

I. Minimum Client Requirements ......................................................................................................... 4

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 Reports Setup on AIX............................................................................................. 14

Kewill Customs Adapter Installation for Windows............................................................................. 16

Adapter Prerequisites: ....................................................................................................................... 16

Tomcat Configuration for RMS: ........................................................................................................ 16

Tomcat Configuration for Oracle: ..................................................................................................... 18

Installation of Tomcat Program......................................................................................................... 18

Configuring the Database Connection - Oracle: ............................................................................... 18

Configuring the Database Connection - Connx:................................................................................ 19


KC Install - 3


Appendix 1 -- Installing Java Notes ..................................................................................................... 20

Appendix 2 -- Installing Tomcat Notes ................................................................................................ 22

Appendix 3 – Database Install/Upgrade .............................................................................................. 24

Database Install .................................................................................................................................. 24

Database Upgrade .............................................................................................................................. 26


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.

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.

I. Minimum Client Requirements

MinimumRequirements

2 GHz or better processor.

1GB memory is the minimum, 2GB is optimal.


KC Install - 5


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/100mbps LAN orsimilar).

Sun Java Runtime 1.5 or greater.

Adobe Reader 8 or greater.

Direct or network access to printer for local printing of PDF.

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 is required to accommodate more users/server. 32 bitservers 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 speedSun Java Runtime 1.5 or greater (Available at Java.com).

Adobe Reader 8 or greater.

Direct or network access to printer for local printing of PDF.

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

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

IP address of the Application Server.

Release Number Nomenclature

Overview Kewill Customs releases are named with the following nomenclature:

Example: Release 1_2_3_4 where

1 = Major Release version #1

2 = Minor Release version #2

3 = Patch version #3

4 = Minor Patch version #4


KC Install - 7


Three-Tier Setup Procedures

Overview The table below provides the steps required for the setup process.

Step Action Comment

1 Verify that the following ulimits are setcorrectly for Alliance login OS username:

Command to use: ulimits -a

time(seconds) unlimited

data(kbytes) unlimited

stack(kbytes) 65526

memory(kbytes) unlimited

Note: If not set correctly, root username isrequired to edit /etc/security/limits.

2 Get Kewill Customs web archive filekcustoms.war from supplied media.

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

4 Log in to the application server usingtelnet.

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

5 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

6 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"/>


KC Install - 8


Step Action Comment

To:

<propertyname="icustoms.primary.url"

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

Where:

HOST_IP is the IP address of theapplication server that is hosting Tomcatand visible to users.

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

8 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" />


KC Install - 9


Step Action Comment

9 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"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”.

10 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 fromthe installation media.

2 FTP apache-tomcat-5.5.26.tar.gz tohome 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., gunzipapache-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. Rightafter the commented lines, add thefollowing 2 lines:

(See below for the two lines to be added.)

Add these 2 lines: JAVA_HOME=/usr/java5_64; export JAVA_HOME

JAVA_OPTS='-Xms1536m -Xmx1536m -Xmaxe256m -Djava.awt.headless=true -Dicustoms.abi.root.dir=/alliance/RUNTIME/; 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_64/bin/java –Xms1536m -Xmx1536m -Xmaxe256m -Djava.awt.headless=trueDjava.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.

http://69.48.135.27:8080/kcustoms/MainController


KC Install - 13


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

Example: http://69.48.135.29:8080/manager/status

(See below for sample Status results).

Sample Status:

Note The “Free memory” must not exceed or be equal to “Max memory”. If it is,the Kewill Customs application needs to be restarted.

http://ip_address:8080/manager/status

http://69.48.135.29:8080/manager/status


KC Install - 14


Kewill Customs Reports Setup on AIX

Overview This procedure will enable Kewill Custom’s reports background processes.The table below provides the steps required for the setup process.

Hardware & SystemRequirements

This is typically the same machine that runs Kewill Customs or Alliance(Integrity or AIX), therefore have similar and additional requirementsspecified here.

Direct network access or connection to printer.

The Reports background processes must be running on separate instanceof Apache Tomcat.

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

Kewill Customs 3-tier has been installed already. [If not, refer to“Three-tier Setup Procedure” section.]

Oracle Database is already running and installed with Alliance R07schema.

IP address of the Application Server.

Step Action Comment

1 Copy the directory /kcustoms/apache-tomcat-5.5.26 to /kcustoms/apache-tomcat-5.5.26-2.

2 Navigate to /kcustoms/apache-tomcat-5.5.26-2/conf.

Edit server.xml to change the default portnumber of the second Apache Tomcat.

From:

<Server port="8005"shutdown="SHUTDOWN">

<Connector port="8080"maxHttpHeaderSize="8192"…

<Connector port="8009"enableLookups="false"redirectPort="8443"protocol="AJP/1.3" />


KC Install - 15


Step Action Comment

To:

<Server port="8006"shutdown="SHUTDOWN">

<Connector port="8081"maxHttpHeaderSize="8192"…

<Connector port="8010"enableLookups="false"redirectPort="8443"protocol="AJP/1.3" />

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

Edit service.xml to enable the KewillCustoms Reports background processes.

Enable the following services by removingXML comment () tag surroundingthem:

ReportSchedulerHandler

ReportQueueHandler

EMailQueueHandler

PrintQueueHandler

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

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

From:

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

To:

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

5 At this point, the setup is done and startsTomcat.

Refer to section “Kewill Customs runningApache Tomcat on AIX” on how to stopand restart Tomcat.


KC Install - 16


Kewill Customs Adapter Installation for Windows

Overview The Kewill Customs Adapter is an integration module for Kewill Customs.

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.

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]

http://tomcat.apache.org/download-55.cgi


KC Install - 17


Sample of change in Apache Tomcat Properties window:

Unix/Linux Edit <Tomcat_Install>/bin/catalina.sh

1. Append the following line to the JAVA_OPTS

-Dicustoms.database.type=RMS

Note on Memory: The memory setting on Apache Tomcat has to be set accordingly. The size ofthe memory is dependent on the capacity, load of the system and size of XMLfiles.

For initial setting, it is recommended to set the following:

On windows, Apache Tomcat Properties:Initial memory pool: 1024Maximum memory pool: 1024

On Unix, append the following line to JAVA_OPTS:-Xms1024m –Xmx1024m


KC Install - 18


Tomcat Configuration for Oracle:

Note for Oracle: No special configuration is required for Oracle.

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

1 Copy the compressed program filekcadapter.war to the

<Tomcat Install>/webapps folder.

2 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

3 Navigate to the folder:

<Tomcat Install>/webapps/kcadapter/WEB-INF/classes/META-INF

4 Edit the file persistence.xml

5 Locate the <properties> tag within thefile.

It should be towards the end of the file.

6 Set the correct values for the followingproperties:

a. toplink.jdbc.url – the database


KC Install - 19


connection 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 thesevalues.]

b. toplink.jdbc.user – the databaseusername

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

Configuring the Database Connection - Connx:

Step Action Comment

7 Navigate to the folder:

<Tomcat Install>/webapps/adapter/WEB-INF/classes/META-INF

8 Edit the file persistence.xml

9 Locate the <properties> tag within thefile.

It should be towards the end of the file.

10 Comment out the Oracle Connectionproperties and uncomment the ConnxConnection properties.

11 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 administrator tofind out these values.]


KC Install - 20


b. toplink.jdbc.user – the databaseusername

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

12 You are done.

Appendix 1 -- Installing Java Notes

Notes Action Comment

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

For example: Change from

C:\ProgramFiles\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.


KC Install - 21


Sample of changing Java Install Folder from the default location:

Sample of modified Java Install Folder destination location:


KC Install - 22


Appendix 2 -- Installing Tomcat Notes

Notes Action Comment

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

For example: Change from

C:\Program Files\ApacheSoftware Foundation\Tomcat5.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 - 23


Sample of modified Install Folder destination location:


KC Install - 24


Appendix 3 – Database Install/Upgrade

Database Install

Database Install Note that Database Install must be done by a DBA or under supervisionof Kewill DBA Services.

The table below describes the steps required for installing the database on topof Alliance R07 Patch 2 Hotfix 1.

After running the install scripts, the upgrade scripts has to be perform to bringthe database to the latest patch or hotfix of Kewill Customs.

Create a database user for Kewill Customs:

Step Action

1 Run sqlplus, and login as SYSTEM (dba for Oracle).

2 Using sqlplus, run the following:

a. install\db-2.0\create_kc_user.sql

Grant the Alliance table to Kewill Customs:

Step Action

3 Run sqlplus, and login as TPSDBA (database username/schema of Alliance).

4 Using sqlplus, run the following script from the installation media:

b. install\db-2.0\grant_alliance_tables.sql


KC Install - 25


Create the synonyms of Alliance table to Kewill Customs:

Step Action

5 Run sqlplus, and login as KCAPPS (database username/schema of KC).


c. install\db-2.0\create_kc_synonyms.sql

Create KC tables on Alliance schema:

Step Action



d. install\db-2.0\create_kc_synonyms.sql

Scripts creating and inserting Kewill Customs required tables and data:

Step Action

9 Run sqlplus, and login as TPSDBA (database schema of Kewill Customs).


e. install\db-2.0\create_kc_tables.sql

f. install\db-2.0\populate_kc_tables.sql


KC Install - 26


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 ontop of Alliance R07 Patch 2 with Kewill Customs 2.0 or 2.0.1.

Step Action



a. upgrade\db-2.0.2\data\VALIDATION_TABLE_X_REF.sql

b. upgrade\db-2.0.2\data\VALIDATION_MESS.sql

c. upgrade\db-2.0.2\data\VALIDATION_CONTROL.sql

d. upgrade\db-2.0.2.2\data\SYSTEM_PARAMETER.sql

e. upgrade\db-2.0.3\data\VALIDATION_TABLE_X_REF.sql

f. upgrade\db-2.0.3\data\VALIDATION_MESS.sql

g. upgrade\db-2.0.3\data\VALIDATION_CONTROL.sql

h. upgrade\db-2.0.3\data\SYSTEM_PARAMETER.sql

i. upgrade\db-2.0.3\data\SECURITY_PREFERENCES.sql

Copyright © 2010 Kewill plc [last revision date: 06/09/10]

Documents

Kewill Customs Installations Guidelegacydocs.kewill.com/documentation/KC/KC... · Kewill Customs is a stateless application so the users don’t have to log out of their screens