Kewill Customs Installations Guide

Transcription

1 Kewill Customs Installations Guide For Release Alliance R07 Patch 2 Hotfix 1 Compatible Original Publication: June, 2010 KC Install - 1

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

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

4 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. The server must be connected to the high speed network. JDBC Connectivity. Java JDK 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. I. Minimum Client Requirements Minimum Requirements 2 GHz or better processor. 1GB memory is the minimum, 2GB is optimal. KC Install - 4

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 or similar). 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 Minimum Requirements 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 bit servers have a memory limitation 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). Adobe Reader 8 or greater. Direct or network access to printer for local printing of PDF. 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

6 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 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 R07 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_4 where 1 = Major Release version #1 2 = Minor Release version #2 3 = Patch version #3 4 = Minor Patch version #4 KC Install - 6

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 set correctly for Alliance login OS username: Note: If not set correctly, root username is required to edit /etc/security/limits. Command to use: ulimits -a time(seconds) unlimited data(kbytes) unlimited stack(kbytes) memory(kbytes) unlimited 2 Get Kewill Customs web archive file kcustoms.war from supplied media. 3 Transfer kcustoms.war to the home directory of Alliance user. 4 Log in to the application server using telnet. Copy kcustoms.war to /kcustoms/apache-tomcat /webapps. 5 At this point, the war file should have been automatically exploded by Tomcat. If not, try to stop and restart Tomcat. Refer to section Kewill Customs running Apache Tomcat on AIX on how to stop and restart Tomcat. Three-Tier Configuration Procedures Step Action Comment 6 Once exploded, navigate to /kcustoms/apache-tomcat /webapps/kcustoms Edit icustoms.jnlp to point web start to the correct URL. To point web start to the correct URL, replace and set the following lines: From: <property name="icustoms.primary.url" value=" kcustoms/maincontroller"/> KC Install - 7

8 Step Action Comment To: <property name="icustoms.primary.url" value=" kcustoms/maincontroller"/> Where: HOST_IP is the IP address of the application server that is hosting Tomcat and visible to users. 7 Navigate to /kcustoms/apache-tomcat /webapps/kcustoms/WEB-INF Edit web.xml to point the server component to correct URL. To point the server component to the correct URL replace and set the following lines: From: <init-param> </init-param> To: <init-param> <param-value> <paramname>icustoms.primary.url</paramname> <paramvalue> kcustoms/maincontroller</paramvalue> <paramname>icustoms.primary.url</paramname> kcustoms/maincontroller</paramvalue> </init-param> Note: See definition ofhost_ip on Step 5 above. 8 Navigate to /kcustoms/apache-tomcat /webapps/kcustoms/WEB- INF/classes. Edit log4j.xml, and point the log file to appropriate location. Example: <param name="file" value="/ kcustoms/logs/customs.log" /> KC Install - 8

9 Step Action Comment 9 Navigate to /kcustoms/apache-tomcat /webapps/kcustoms/WEB- INF/classes/META-INF. Edit persistence.xml to point to correct database server and database username. To point to the correct database server and database username, replace and set the following lines: <property name="toplink.jdbc.url" value="jdbc:oracle:thin:@database_ip :1521:DATABASE_SID" /> <property name="toplink.jdbc.user" value="db_schema" /> <property name="toplink.jdbc.password" 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. 10 Restart Tomcat to put the new settings into effect. The application should be accessible on this URL: Note: See definition ofhost_ip on Step 5 above. KC Install - 9

10 Installation of Apache Tomcat on AIX Prerequisites IP address of the application server Java JDK 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 tar.gz from the installation media. 2 FTP apache-tomcat tar.gz to home directory of alliance, e.g., /home/alliance. 3 Copy apache-tomcat tar.gz to /kcustoms. 4 Unzip apache-tomcat tar.gz, using unzip or gunzip, e.g., gunzip apache-tomcat tar.gz 5 Extract or untar apache-tomcat tar, e.g., tar xvf apache-tomcat tar 6 Navigate to /kcustoms/apache-tomcat /bin, and edit catalina.sh. Right after the commented lines, add the following 2 lines: (See below for the two lines to be added.) Add these 2 lines: JAVA_HOME=/usr/java5_64; export JAVA_HOME JAVA_OPTS='-Xms1536m -Xmx1536m -Xmaxe256m - Djava.awt.headless=true - Dicustoms.abi.root.dir=/alliance/RUNTIME/; export JAVA_OPTS KC Install - 10

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 the command will look like below. If so, proceed to Stopping Tomcat. If not, proceed to step 3. 3 Navigate to /kcustoms/apache-tomcat /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 :13:46 pts/7 69:24 /usr/java5_64/bin/java Xms1536m -Xmx1536m -Xmaxe256m - Djava.awt.headless=true Djava.util.logging.manager=org.apache.juli.ClassLoaderLogM anager -Djava.util.logging.config.file=/kcustoms/apachetomcat /conf/logging.properties - Djava.endorsed.dirs=/kcustoms/apache-tomcat /common/endorsed -classpath :/kcustoms/apache- tomcat /bin/bootstrap.jar:/kcustoms/apache-tomcat /bin/commons-logging-api.jar - Dcatalina.base=/kcustoms/apache-tomcat Dcatalina.home=/kcustoms/apache-tomcat Djava.io.tmpdir=/kcustoms/apache-tomcat /temp org.apache.catalina.startup.bootstrap start Stopping Tomcat Step Action Comment 1 Log in as Alliance username using telnet. 2 Navigate to /kcustoms/apache-tomcat /bin 3 Type in./catalina.sh stop KC Install - 11

12 Step Action Comment 4 Use the command in step 2 of Starting Tomcat to verify that application is really stopped. If it is not, proceed to step 5. 5 For some reason if the process of java is still hanging around after stopping it. Use kill -9 to hard stop the process. This command will abruptly kill the process and throw away any pending transaction, so use this command carefully. Note Alliance username must be used in restarting and stopping Kewill Customs because its environment is set accordingly. Kewill Customs is a stateless application so the users don t have to log out of their screens. The application should be able to recover once the server is up and running. Kewill Customs Logs Kewill Customs Logs The logs can be found in the following directory: 1. /kcustoms/logs log files that are specific to Kewill Customs processes. 2. /kcustoms/apache-tomcat /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: Example: The response should be:hello!maincontroller is alive and well. KC Install - 12

13 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: Example: (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. KC Install - 13

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 & System Requirements This is typically the same machine that runs Kewill Customs or Alliance (Integrity or AIX), therefore have similar and additional requirements specified here. Direct network access or connection to printer. The Reports background processes must be running on separate instance of Apache Tomcat. 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.] 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 R07 schema. IP address of the Application Server. Step Action Comment 1 Copy the directory /kcustoms/apachetomcat to /kcustoms/apachetomcat Navigate to /kcustoms/apache-tomcat /conf. Edit server.xml to change the default port number 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 - 14

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 /webapps/kcustoms/WEB- INF/classes. Edit service.xml to enable the Kewill Customs Reports background processes. Enable the following services by removing XML comment (<!-- -->) tag surrounding them: ReportSchedulerHandler ReportQueueHandler QueueHandler PrintQueueHandler 4 Navigate to /kcustoms/apache-tomcat /webapps/kcustoms/WEB- INF/classes. Edit log4j.xml, and point the log file to appropriate 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 starts Tomcat. Refer to section Kewill Customs running Apache Tomcat on AIX on how to stop and restart Tomcat. KC Install - 15

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 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 Apache Tomcat version 5.5. Apache Tomcat can be downloaded at: 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 - 16

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 of the memory is dependent on the capacity, load of the system and size of XML files. For initial setting, it is recommended to set the following: On windows, Apache Tomcat Properties: Initial memory pool: 1024 Maximum memory pool: 1024 On Unix, append the following line to JAVA_OPTS: -Xms1024m Xmx1024m KC Install - 17

18 Tomcat Configuration for Oracle: Note for Oracle: No special configuration is required for Oracle. Installation of Tomcat Program Note on using a Servlet Container other than Tomcat These installation instructions are for Tomcat. Please read the web archive deploy instructions of the Servlet Container if using a Servlet Container other than Tomcat. Step Action Comment 1 Copy the compressed program file kcadapter.war to the <Tomcat Install>/webapps folder. 2 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 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 the file. It should be towards the end of the file. 6 Set the correct values for the following properties: a. toplink.jdbc.url the database KC Install - 18

19 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 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 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 the file. It should be towards the end of the file. 10 Comment out the Oracle Connection properties and uncomment the Connx Connection properties. 11 Set the correct values for the following properties: a. toplink.jdbc.url the database connection string For Connx : jdbc:connx:dd=<dsn>;gateway=< gateway>;port=7500 The correct values should be substituted for <DSN>, <gateway>. [Contact the database administrator to find out these values.] KC Install - 19

20 b. toplink.jdbc.user the database username c. toplink.jdbc.password the password for the above database user 12 You are done. 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 Change to C:\Program Files\Java\jdk1.5.0_14 C:\Java\jdk1.5.0_14 2 Ensure that none of the folder names have spaces in them and are not too long. KC Install - 20

21 Sample of changing Java Install Folder from the default location: Sample of modified Java Install Folder destination location: KC Install - 21

22 Appendix 2 -- Installing Tomcat Notes Notes Action Comment 1 When installing Tomcat, change the Install Folder from the default location. [See screenshots below for sample.] For example: Change from Change to C:\Program Files\Apache Software Foundation\Tomcat 5.5 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 - 22

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

24 Appendix 3 Database Install/Upgrade Database Install Database Install Note that Database Install must be done by a DBA or under supervision of Kewill DBA Services. The table below describes the steps required for installing the database on top of Alliance R07 Patch 2 Hotfix 1. After running the install scripts, the upgrade scripts has to be perform to bring the 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 - 24

25 Create the synonyms of Alliance table to Kewill Customs: Step Action 5 Run sqlplus, and login as KCAPPS (database username/schema of KC). 6 Using sqlplus, run the following script from the installation media: c. install\db-2.0\create_kc_synonyms.sql Create KC tables on Alliance schema: Step Action 7 Run sqlplus, and login as TPSDBA (database username/schema of Alliance). 8 Using sqlplus, run the following script from the installation media: 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). 10 Using sqlplus, run the following script from the installation media: e. install\db-2.0\create_kc_tables.sql f. install\db-2.0\populate_kc_tables.sql KC Install - 25

26 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 on top of Alliance R07 Patch 2 with Kewill Customs 2.0 or Step Action 1 Run sqlplus, and login as TPSDBA (database username/schema of Alliance). 2 Using sqlplus, run the following script from the installation media: 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 \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] KC Install - 26