Post on 17-Apr-2020
transcript
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
Kewill Customs Installation Guide
KC Install-3
Copyright © 2008-2009 Kewill, plc
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
Kewill Customs Installation Guide
KC Install-4
Copyright © 2008-2009 Kewill, plc
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 & 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.
Kewill Customs Installation Guide
KC Install-5
Copyright © 2008-2009 Kewill, plc
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.
Kewill Customs Installation Guide
KC Install-6
Copyright © 2008-2009 Kewill, plc
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
Kewill Customs Installation Guide
KC Install-7
Copyright © 2008-2009 Kewill, plc
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
Kewill Customs Installation Guide
KC Install-8
Copyright © 2008-2009 Kewill, plc
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"
Kewill Customs Installation Guide
KC Install-9
Copyright © 2008-2009 Kewill, plc
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.
Kewill Customs Installation Guide
KC Install-10
Copyright © 2008-2009 Kewill, plc
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
Kewill Customs Installation Guide
KC Install-11
Copyright © 2008-2009 Kewill, plc
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”
Kewill Customs Installation Guide
KC Install-12
Copyright © 2008-2009 Kewill, plc
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
Kewill Customs Installation Guide
KC Install-13
Copyright © 2008-2009 Kewill, plc
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.
Kewill Customs Installation Guide
KC Install-14
Copyright © 2008-2009 Kewill, plc
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]
Kewill Customs Installation Guide
KC Install-15
Copyright © 2008-2009 Kewill, plc
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.
Kewill Customs Installation Guide
KC Install-16
Copyright © 2008-2009 Kewill, plc
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
Kewill Customs Installation Guide
KC Install-17
Copyright © 2008-2009 Kewill, plc
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.
Kewill Customs Installation Guide
KC Install-18
Copyright © 2008-2009 Kewill, plc
Kewill Customs Troubleshooting
TroubleshootingSection Contents
Included in this Troubleshooting section is the following:
How to Resolve the Issue of a Growing Java Cache
Kewill Customs Installation Guide
KC Install-19
Copyright © 2008-2009 Kewill, plc
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:
Kewill Customs Installation Guide
KC Install-20
Copyright © 2008-2009 Kewill, plc
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.
Kewill Customs Installation Guide
KC Install-21
Copyright © 2008-2009 Kewill, plc
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.
Kewill Customs Installation Guide
KC Install-22
Copyright © 2008-2009 Kewill, plc
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.
Kewill Customs Installation Guide
KC Install-23
Copyright © 2008-2009 Kewill, plc
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:
Kewill Customs Installation Guide
KC Install-24
Copyright © 2008-2009 Kewill, plc
Sample of modified Java Install Folder destination location:
Kewill Customs Installation Guide
KC Install-25
Copyright © 2008-2009 Kewill, plc
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:
Kewill Customs Installation Guide
KC Install-26
Copyright © 2008-2009 Kewill, plc
Sample of modified Install Folder destination location:
Kewill Customs Installation Guide
KC Install-27
Copyright © 2008-2009 Kewill, plc
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]