SmartPatch. Installation Manual Version 6.x

Transcription

1 SmartPatch Installation Manual Version 6.x

2 Copyright Copyright 2017 Brand-Rex Ltd. All rights reserved. No part of this publication or of the SmartPatch software, in source code or object code form, may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording or otherwise, without the prior written consent of Brand-Rex or technology partners of Brand-Rex Ltd. Contact information is available on request Disclaimer These materials are subject to change without notice and for informational purposes only, without representation of warranty of any kind. Document history History table: Version Date Author Description Edeeben Logo and style update 2

3 Contents Copyright... 2 Disclaimer... 2 Document history... 2 Introduction... 4 SmartPatch Deployment Components... 4 SmartPatch Server... 4 SmartPatch Client... 4 SmartPatch Database... 4 Installation... 4 Create and Setup the Working Directory... 5 Configure the Apache Tomcat Heap Memory Settings... 5 Configure the Apache Tomcat Java Settings... 5 Deploy SmartPatch Server on Apache Tomcat... 6 Configuring SmartPatch Server... 6 Running SmartPatch Server... 6 Running SmartPatch Client... 6 Upgrading an Existing Installation... 7 Back up the existing database and software... 7 Install the upgrade... 7 Reverting an upgrade... 7 Database and Configuration Back Ups... 8 Backing up the database and configuration... 8 Restoring a backed up database and configuration... 8 Support

4 Introduction This guide describes the structure of a SmartPatch deployment and the procedure for installing, configuring and running SmartPatch. SmartPatch Deployment Components SmartPatch is a three-tier client-server based application. The three components are: The SmartPatch Server The SmartPatch Client(s) The SmartPatch Database and related Database Management System (DBMS) SmartPatch Server The purpose of the SmartPatch Server is to interact with the SmartPatch Database and serve the data to the SmartPatch Client(s). The SmartPatch Server is a Java Web Application suitable for deployment on Apache Tomcat version or higher or 8.x. Note that, optionally, an Apache Web Server can be used as a front-end server to the Apache Tomcat server that the SmartPatch Server application is deployed on. This option may be applicable to cases where making use of certain Apache Web Server front-end functionalities is desired. Configuring Apache Web Server as a front-end to Apache Tomcat is outside of the scope of this document. SmartPatch Client The SmartPatch Client is the Graphical User Interface (GUI) with which the user interacts. The SmartPatch Client is a Java application that is downloaded on demand from SmartPatch Server via a web browser using Java Web Start Technology Communication between SmartPatch Client and SmartPatch Server is via HTTP(S). SmartPatch Database The SmartPatch Database contains the SmartPatch data. The SmartPatch Database is available in formats for many popular DBMS including MS SQL Server, Oracle and MySQL. The SmartPatch Database can be installed on a dedicated platform or can run on the platform that hosts SmartPatch Server. The size of the database will depend on the amount of information that is stored in SmartPatch, but will typically be between 10MB and 4 GB in size. Installation of the SmartPatch Database is described in the database-specific installation manual supplement. Installation It is assumed that 64-bit Apache Tomcat (or higher) or 8.x, and 64-bit Oracle Java 7.x or 8.x are installed on the machine that is to run SmartPatch Server. Please note that using Oracle Java is a requirement, and that instead using an Alternative Java flavor, such as OpenJDK is not supported. The Java Web Application version of SmartPatch Server is distributed as a standard Web Application Archive (WAR) file in the form pmserver<rev>.war, where <rev> is the software revision. In addition, the distribution contains an archive 'pmserver-working-dir.zip' that contains the content of the working directory that SmartPatch Server will use. 4

5 Create and Setup the Working Directory On the server machine, create a working directory for SmartPatch Server. The operating system user that is running the Apache Tomcat process should be configured to have read and write access to the working directory and any sub-directories of the working directory. Unzip the archive 'pmserver-working-dir.zip' into the working directory. Configure the Apache Tomcat Heap Memory Settings It is recommended that the Java heap memory settings for SmartPatch Server are configured in Apache Tomcat to be set at half the available physical RAM on the server machine. For example, this should be set at: '-Xmx4096m' for a server machine with 8GB of available RAM and as '-Xmx6144m' for a server machine with 12GB or more of available RAM, and so on. For Linux platforms, this can be achieved by creating a file 'setenv.sh' in the 'bin' directory of the Apache Tomcat installation directory and entering a line in the file specifying the heap memory settings. For example (for the '- Xmx4096m' case): export CATALINA_OPTS=-Xmx4096m For Windows platforms, in the 'Java' tab of the 'Tomcat Monitor', enter '512' as the value for 'Initial memory pool' and '4096' as the value for the 'Maximum memory pool' (for the '-Xmx4096m' case). For Windows platforms, in the 'Java' tab of the 'Tomcat Monitor', enter '512' as the value for 'Initial memory pool' and '4096' as the value for the 'Maximum memory pool' (for the '-Xmx4096m' case). Configure the Apache Tomcat Java Settings SmartPatch Server requires that the following Java system property is configured in Apache Tomcat. Djava.util.Arrays.useLegacyMergeSort=true For Linux platforms, this can be achieved by adding the following line to the 'setenv.sh' file (see section Error! Bookmark not defined.): JAVA_OPTS=-Djava.util.Arrays.useLegacyMergeSort=true For Windows platforms, in the 'Java' tab of the 'Tomcat Monitor', enter the following line in the 'Java Options' list: Djava.util.Arrays.useLegacyMergeSort=true 5

6 Deploy SmartPatch Server on Apache Tomcat To deploy SmartPatch Server on Apache Tomcat: 1. Ensure that Apache Tomcat is stopped. 2. In the 'webapps' directory of the Apache Tomcat installation, delete the folder 'ROOT' if it is present. 3. Copy 'pmserver<rev>.war' to the 'webapps' directory of the Apache Tomcat installation. 4. Rename 'pmserver<rev>.war' to be 'ROOT.war'. 5. Start Apache Tomcat. Within about 30 seconds 'ROOT.war' will be deployed into a generated 'ROOT' directory of the 'webapps' directory and Apache Tomcat will stop. 6. Open the file 'web.xml' in the 'webapps/root/web-inf' directory of the Apache Tomcat installation in a text editor and in the section <context-param>, enter the full path to the working directory in the <param-value> element. Save the changes. Configuring SmartPatch Server To configure the connection between SmartPatch Server and the SmartPatch Database, open the file 'server.properties' in the working directory and edit it as described in the database-specific installation manual supplement. Running SmartPatch Server Once SmartPatch Server has been deployed and configured, starting Apache Tomcat will run SmartPatchServer. Note that on Linux platforms, if the configuration of the Apache Tomcat default listening port (8080) has been re-configured to instead run on a port number less than or equal to 1024, then the process must be run as a root user. The final step to complete the installation process is to activate the application license by entering the license key in the SmartPatch Client login dialog. This step is described in the following section. Running SmartPatch Client SmartPatch Client is downloaded on demand from SmartPatch Server and launched via your web browser using Java Web Start technology. A requirement for the browser is that it supports Oracle Java version 7.x. or 8.x installed To download and launch SmartPatch Client, point your browser to the SmartPatch Server host and port that Apache Tomcat is listening on. For example: The start page will appear. On the start page, for client machines that are running 64-bit Java, select the 'Start' button to run SmartPatch. For client machines that are running 32-bit Java, there is an alternative link lower down on the start page to start SmartPatch. The application login dialog will appear. Note that if the SmartPatch license has not yet been activated, a text box will appear in the login dialog in which to enter the license key. Copy and paste the contents of the provided license key text file into the text box, then click the 'OK' button to activate the license and proceed with login. Note that the activation procedure only has to be performed once. Thus, the login dialog from any subsequent SmartPatch Client will not require the activation process to be repeated. The initial log-in credentials to the application are 'admin/admin' in the case of the default database. 6

7 Upgrading an Existing Installation Software upgrades to an existing SmartPatch Server installation are distributed as a complete Web Application Archive in the form pmserver<rev>.war and are intended to replace the existing one. Back up the existing database and software Prior to performing the upgrade, make a back up of the SmartPatch database and existing 'ROOT.war' file. The back ups can then be used if for any reason a revert back from the upgraded installation to the existing installation is required (see section 7.3 for information on how to revert back to the existing installation). Install the upgrade To install the upgrade, first undeploy the existing 'ROOT' web application: 1. Ensure that Apache Tomcat is stopped. 2. In the 'webapps' directory of the Apache Tomcat installation, delete the directory 'ROOT' and the file 'ROOT.war'. Deploy the new 'pmserver<rev>.war' file according to the steps in section 3.3. The installation is now upgraded and can be run using the normal procedure. Prior to running, ensure that the database login account that is specified in the 'server.properties' file in the working directory has database rights to alter, add and delete database tables in the SmartPatch database. These rights are only necessary for the upgrade process and can be set back to read/write access after the upgrade if so desired. During the first run after an upgrade, SmartPatch Server will automatically perform any necessary database table upgrades, so may take longer to start up than usual. Start up progress can be checked in the file 'patchmanager.log' in the 'logs' directory in the working directory. Reverting an upgrade If for any reason, a revert of the upgrade is required, the following steps describe the revert process: 1. Ensure that Apache Tomcat is stopped. 2. Undeploy the 'ROOT' web application from Apache Tomcat by deleting the directory 'ROOT' and the file 'ROOT.war' in the 'webapps' directory of the Apache Tomcat installation. 3. Restore the database that was backed up prior to the installation of the upgrade. 4.Copy the backed up 'ROOT.war' to the 'webapps' directory of the Apache Tomcat installation and follow steps 5 and 6 in section 3.3 7

8 Database and Configuration Back Ups Backing up the database and configuration To back up the database, perform your normal database back up procedure. Additionally, the directories 'icons', 'files' and 'images' in the working directory should be backed up. The files in these directories form part of the application data, but are maintained outside the database itself. To back up the configuration, the files 'server.properties' and 'license.bin' in the working directory should be backed up. Restoring a backed up database and configuration Prior to restoring a back up of the database and configuration, first ensure that the SmartPatch Server web application is stopped. To restore the database, perform your normal database restore procedure. To restore the additional application data files, restore the backed up directories 'icons', 'files' and 'images' into the working directory. To restore the configuration, restore the backed up files 'server.properties' and 'license.bin' into the working directory. Support Application logging information to assist troubleshooting is available in log files in the 'logs' directory of the Apache Tomcat installation directory and in log files in the 'logs' directory of the SmartPatch working directory. For any questions regarding the installation or use of SmartPatch, please contact you re approved Brand-Rex representative or techsupport@brand-rex.com. 8