Envinsa INSTALL GUIDE. Version 4.4. For Tomcat Application Servers

Transcription

1 Envinsa Version 4.4 INSTALL GUIDE For Tomcat Application Servers

2 Information in this document is subject to change without notice and does not represent a commitment on the part of the vendor or its representatives. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, without the written permission of Pitney Bowes Software Inc., One Global View, Troy, New York Pitney Bowes Software Inc. All rights reserved. MapInfo, the MapInfo logo and Envinsa are trademarks of Pitney Bowes Software Inc. and/or its affiliates. Corporate Headquarters: Phone: Fax: Sales: Government Sales: Technical Support: UK and EMEA Headquarters: Phone: Fax: Technical Support: Asia Pacific Headquarters: Phone: Fax: Technical Support: Contact information for all offices is located at: Copyright 2006 The Legion Of The Bouncy Castle Copyright IPDR Organization All Rights Reserved Copyright 2006, International Business Machines Corporation and others. All Rights Reserved. Copyright 2006 Open GIS Consortium, Inc., All Rights Reserved. Copyright 2006 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved. This product includes software developed by the Apache Software Foundation ( Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. Products named herein may be trademarks of their respective manufacturers and are hereby recognized. Trademarked names are used editorially, to the benefit of the trademark owner, with no intent to infringe on the trademark. February 5, 2010

3 Table of Contents Chapter 1: Requirements Release Notes and Envinsa Documentation Upgrading from Earlier Versions of Envinsa System Requirements Supported Software Chapter 2: Preinstallation Tasks Install Application Server Instances Tasks Set Java Properties for Application Server Instances Configure Tomcat Instances for Envinsa Verify File Descriptor Limit Create a Directory for Installer Log Files Set the DISPLAY Environment Variable Start Application Server Instances Recommendations Services Data Components Decide on Installation Choices Choosing Automatic or Manual Service Deployment Choosing a Graphical or Command-line Installation Choosing to Install from DVDs or a Local Directory Chapter 3: Installing Envinsa Using the Envinsa Installer Using the Command-line Installer Chapter 4: Postinstallation Tasks Manually Deploying WAR Files Setting Up JDBC Drivers Configuring Tomcat Instances Upgrade JDK Files for Security Configuring Envinsa Services Presentation and Map Tiling Services

4 Profile Management Service Appendix A: Running the Envinsa Demo Application Starting the Envinsa Demo Application Using the Envinsa Demo Application Appendix B: Configuring an iplanet Directory Server Appendix C: Troubleshooting Installation Problems Envinsa Log Files Error Messages Message: "Error: Can t open display:" One of the Installation Directories Is Not Valid Message: "Target Domain exists" Message: "112: Internal Error in Windows Installer" Message: "SEVERE: Error deploying web application directory..." Service Will Not Run After Reinstallation Envinsa 4.4

5 Requirements 1 This chapter discusses the additional Envinsa documentation you must read and the hardware and software configurations you can use with Envinsa. IMPORTANT: You must perform all preinstallation tasks described in this guide before running the installer. In this section: Release Notes and Envinsa Documentation System Requirements Supported Software

6 Upgrading from Earlier Versions of Envinsa Release Notes and Envinsa Documentation Before installing Envinsa, you must read the Envinsa Release Notes. These notes are the most recent source of information you need to know to install and use Envinsa, including known issues. The Release Notes are in the Envinsa Documentation Library on reference.mapinfo.com/envinsa. You should also read the Envinsa Product Guide for more information about the services, dependencies, and deployment strategies. The Envinsa Install Guide only contains information that relates to the installation procedure. The Envinsa Documentation Library contains the latest versions of all Envinsa guides in PDF and HTML formats. You can view the documents individually or download the entire library to your computer as a ZIP file. The guides in the library are updated as needed. Upgrading from Earlier Versions of Envinsa If you are upgrading from an earlier version of Envinsa, then you must first run the Envinsa Upgrade Installer on your existing Envinsa installation. This will ugprade your currently installed Envinsa components to the current version. After doing that, you can run the Envinsa installer to install any new components. For more information, see the Envinsa Upgrade Guide. System Requirements The following table summarizes the Envinsa hardware and software requirements. Envinsa Requirements Category Disk Space Requirement A complete Envinsa installation requires 1 GB for Envinsa services and tools plus additional space for data components. The space required for data components depends on the geography of the data. For example: Data for North America requires approximately 30 GB. Data for large European countries requires between 5 and 15 GB. Data for most other countries requires less than 5 GB. Depending on the components you choose to install, your installation may require less than these amounts. Memory A complete Envinsa installation requires 5 GB of memory. Depending on the components you choose to install, your installation may require less than this amount. As a guideline, the Route, Presentation, Map Tiling, and Location Utility services each require 1 GB of memory. The other services and components require 1 GB of memory in total. 6 Envinsa 4.4

7 Chapter 1: Requirements Envinsa Requirements (continued) Category Requirement Operating Systems Any of: Windows Server 2003 R2 SP2 (32- or 64-bit) Windows Server 2008 (32- or 64-bit) Solaris 10 for SPARC (32- or 64-bit) IBM AIX 5.3 (32- or 64-bit) Red Hat Enterprise Linux AS 4 for x86 (32- or 64-bit) Red Hat Enterprise Linux ES 4 for x86 (32- or 64-bit) Red Hat Enterprise Linux 5 for x86 (32- or 64-bit) Red Hat Enterprise Linux Advanced Platform 5 for x86 (32- or 64-bit) Application Servers Any of: Apache Tomcat or Core, if you are using JDK 1.5. To ensure your Tomcat installation properly supports the JVM option, you must download and install the.zip or.tar.gz file. Do not use the Windows Service Installer file. Apache Tomcat or with the JDK 1.4 Compatibility Package, if you are using JDK 1.4. Envinsa can also install Apache Tomcat automatically. For more information on this installation option, see the Envinsa Quick Install Guide. Java Virtual Machine Any of: JDK JDK (1.5.0_05 or higher is recommended) If you are using a 64-bit operating system, then you must use JDK 1.5. Envinsa requires the virtual machine from a JDK installation. Using the virtual machine from a JRE installation is not supported. Directory Servers To use the Profile Management Service you must have an LDAP v3 compatible directory server. Envinsa was validated with iplanet 5.1. Install Guide For Tomcat Application Servers 7

8 Supported Software Supported Software Envinsa also supports the use of the following software: Supported Software Security Category Supported Software By default, Envinsa services are installed with: Apache XML Security (Signature implementation only) Bouncy Castle JCE for JDK 1.4 Envinsa services also support the following security related tools: XML Encryption and Signature IBM XML Security Suite Verisign Trust Service Integration Kit (TSIK) Java Cryptography Extension (JCE) IBM Security Extension (available from the IBM JRE) Sun JCE (available from the Sun JDK) Bouncy Castle JCE for JDK 1.5 (bcprov-jdk jar) Databases Envinsa supports the following databases: MapInfo.tab files IBM DB2 8.1 (non-spatial) IBM DB2 9 (with or without Spatial Extender) Microsoft SQL Server 2000 Service Pack 3 with MapInfo SpatialWare 4.8 Microsoft SQL Server 2005 with MapInfo SpatialWare 4.9 MySQL 4.1 (non-spatial) Oracle9i Database Release 2 with Oracle Spatial and Oracle Locator Oracle Database 10g with Oracle Spatial and Oracle Locator Envinsa only supports case-insensitive databases. For more information on configuring your database to support this requirement, see your database documentation. SNMP Agents Web Browsers Envinsa supports any SNMP agent. Envinsa is validated against Java Dynamic Management Kit (JDMK) 5.0. Any of: Microsoft Internet Explorer 6.0 Mozilla Firefox Envinsa 4.4

9 Preinstallation Tasks 2 This chapter describes the tasks you must perform before installing Envinsa. Note: This chapter uses forward slashes to separate directories in paths that apply to all operating systems. Windows users must use backslashes when specifying paths. In this section: Install Application Server Instances Tasks Recommendations Decide on Installation Choices

10 Tasks Install Application Server Instances This guide describes the tasks you must perform to install the Envinsa services on your application server. To avoid any conflicts between the Envinsa services and your existing web applications, you should install one or more separate instances of your application server exclusively for Envinsa. This allows you to make configuration changes to your Envinsa services and applications without affecting any other applications. Tasks Before installing Envinsa, you must perform the following tasks: Set Java Properties for Application Server Instances Configure Tomcat Instances for Envinsa Verify File Descriptor Limit Create a Directory for Installer Log Files Set the DISPLAY Environment Variable Start Application Server Instances Set Java Properties for Application Server Instances The Java Virtual Machine (JVM) uses multiple predefined memory spaces for various types of memory management. The two main spaces are heap for object instances and permanent generation (PermSize) for code and static data. You must set the default size for each of these spaces to optimize the performance of Envinsa services. For most installations, MapInfo recommends that you configure each application server instance to use 1024 MB of heap space and 128 MB of permanent generation space. It is important that the amount of heap space that you specify be available as unused physical memory. The optimal heap size must be large to reduce the number of garbage collection occurrences, but must be small enough to run entirely in physical memory to avoid disk swapping. For more information see the performance documentation for your version of Java and application server. Consider the following guidelines when determining the size for each space: Route Service Heap size requirements are affected by the data used (it varies by country), the number and complexity of requests, and the type of result (with map or without). Memory usage is determined for one service instance per country for performance reasons. Presentation Service Memory usage depends on the mapping data used (it varies per country) and layer search requirements. Location Utility and Position Refine Services Memory usage varies according to the complexity of queries and the number of candidate matches. Map Tiling - Memory usage varies according to the mapping data used and the number of tiles to be cached in memory. All other Envinsa Services Memory usage varies according to the complexity of queries and the number of candidate matches, but these services are not memory intensive. 10 Envinsa 4.4

11 Chapter 2: Preinstallation Tasks Batch Geocoding Memory usage varies according to the size of the dataset. You may need to increase the JVM heap size to accommodate large datasets. For example, if you know you will be doing memory-intensive Route service processing, you may want to allocate a maximum heap size of 2048 MB. However, do not allocate a total heap size that exceeds your available memory because service requests will run out of memory and fail. To set the recommended values, perform the following steps for each application server instance: 1. Edit catalina.bat or catalina.sh in the Tomcat bin directory to set the heap and permanent space sizes. Add one of the following lines to the catalina script of all Tomcat instances that will run Envinsa services. UNIX (except for IBM AIX) and Linux: JAVA_OPTS="-server -Xms256m -Xmx1024m -XX:MaxPermSize=128m" IBM AIX JVM: JAVA_OPTS="-Xms256m -Xmx1024m" Windows: JAVA_OPTS=-server -Xms256m -Xmx1024m -XX:MaxPermSize=128m 2. If this server will run the Presentation or Map Tiling service, then add the following value to the JAVA_OPTS line: -XX:+DisableExplicitGC After completing these steps, save your changes and restart the instance for the changes to take effect. Configure Tomcat Instances for Envinsa Before installing Envinsa, you must make the following configuration changes to your Tomcat application server instances: 1. Configure Tomcat Users 2. Configure Server Settings 3. Configure MIME Extensions 4. Enable the Tomcat antilock Mechanism 5. Restart all Tomcat Instances 6. Install Tomcat as a Windows Service (Optional) For more information on these tasks, see the Tomcat documentation. Configure Tomcat Users Add a manager role and user account with that role to each Tomcat instance. To do this: 1. Open <Tomcat_home>/conf/tomcat-users.xml in a text editor. 2. Add the bold lines in the following code to the file: Install Guide For Tomcat Application Servers 11

12 Tasks <tomcat-users> <role rolename="manager"/> <user username="tc_user" password="tc_password" roles="manager"/> </tomcat-users> where tc_user and tc_password are the user name and password for the Tomcat administration account. 3. Save your changes to the file. 4. Repeat these steps for all of the other Tomcat instances you will use with Envinsa. Configure Server Settings Configure each Tomcat instance to disable automatic application deployment and support the UTF character set. To do this: 1. Open <Tomcat_home>/conf/server.xml in a text editor. 2. Locate the Define the default virtual host section in the file and add the following attribute, shown in bold: <!-- Define the default virtual host --> <Host name="localhost" debug="0" appbase="webapps" unpackwars="true" autodeploy="true" livedeploy="false"> 3. If you are running Tomcat on a non-english operating system, then locate the Define a non-ssl HTTP/1.1 Connector section of the file and add the following attribute, shown in bold: <!-- Define a non-ssl HTTP/1.1 Connector on port > <Connector port="8080" maxhttpheadersize="8192" maxthreads="150" minsparethreads="25" maxsparethreads="75" enablelookups="false" redirectport="8443" acceptcount="100" connectiontimeout="20000" disableuploadtimeout="true" URIEncoding="UTF-8" /> 4. Save your changes to the file. 5. Repeat these steps for all of the other Tomcat instances you will use with Envinsa. Configure MIME Extensions Add a MIME type for the.xsd extension to each Tomcat instance. To do this: 1. Open <Tomcat_home>/conf/web.xml in a text editor. 2. Locate the Default MIME Type Mappings section in the file and add the following lines: <mime-mapping> <extension>xsd</extension> <mime-type>text/xml</mime-type> </mime-mapping> 3. Save your changes to the file. 4. Repeat these steps for all of the other Tomcat instances you will use with Envinsa. 12 Envinsa 4.4

13 Enable the Tomcat antilock Mechanism Chapter 2: Preinstallation Tasks Note: If you are using JDK 1.5.0, then read this section. Otherwise, you can skip this section. Tomcat is compatible with JDK However, in Tomcat the "antilock" mechanism is disabled by default. You must enable it in order to successfully upgrade or uninstall Envinsa components. To enable antilock, do the following for each Tomcat instance: 1. Open <Tomcat_home>/conf/context.xml in a text editor. 2. Locate the <Context...> element near the beginning of the file and add the following attribute to it: antijarlocking="true" After changing the element, it will look like: <Context... antijarlocking="true"> 3. Save and close context.xml. Restart all Tomcat Instances Stop and start all of your Tomcat instances to ensure the changes you made in this section take effect. Install Tomcat as a Windows Service (Optional) Note: This section only applies to Windows Users. If you want to automatically start your Tomcat instances when you turn on your computer, then you must install Tomcat as a Windows service. See the Apache Tomcat documentation for more information on this task. Verify File Descriptor Limit Note: This section only applies to UNIX and Linux users. Envinsa requires that your file descriptor limit is at least 1024 resources. To test this, enter the following command at the command prompt: ulimit -Sn This returns the maximum number of resources for the session. If this number is less than 1024, then ask your system administrator to increase the limit. Install Guide For Tomcat Application Servers 13

14 Recommendations Create a Directory for Installer Log Files Note: This section only applies to Windows users. The Envinsa installer creates log files in C:\TMP and the directory specified with the %TEMP% environment variable. You must create both directories, if they do not exist, before starting the installer. Set the DISPLAY Environment Variable Note: This section only applies to UNIX and Linux users who want to display the installer screens on a remote computer. If you want to display the installer screens on a remote computer, then you must use an X client that is compatible with your X server. Before starting the installer, run the following command in the terminal window where you will start the installer: export DISPLAY=<client_computer_name>:0.0 where <client_computer_name> is the hostname or IP address of the computer where you are running the X client. For more information on this task, see your X server and X client documentation or contact your system administrator. Start Application Server Instances Your application server and all instances you will use for Envinsa must be installed and running before you start the Envinsa installer. If they are not currently running, then start them now. Recommendations The following recommendations provide additional information that can help you install Envinsa in a way that best uses your system resources. The recommendations are organized by: Services Data Components Services The following recommendations apply to all Envinsa services. Optimizing Application Server Performance The Presentation, Map Tiling, Route, and Location Utility services individually have large memory requirements. To ensure the best performance for these services, MapInfo recommends that you install each of these services into a separate application server instance. 14 Envinsa 4.4

15 Chapter 2: Preinstallation Tasks During the installation process, the installer will give you the opportunity to install each service into a separate application server instance. To help you during the installation process, consider creating a work sheet similar to the following example: Decide which services you will install and write the name of each service under one instance on the work sheet. When the installer prompts you to select the services you want to install under each application server instance, you can refer to the work sheet as a reference. Using a Naming Convention for Multiple Installations MapInfo recommends that you use a naming convention for your installation. This naming convention will help you to keep track of the components that you have installed or upgraded when looking at the file system. This is especially useful if you are installing multiple application server instances. One way to keep track of multiple instances is to use a naming convention based on the port number of the instance, such as Envinsa/domain7070 and Envinsa/domain7080. A sample naming convention would be: Domain/Envinsa<version>/instance<version><port> Increasing the File Descriptor Limit Note: This recommendation only applies to Solaris installations. The file descriptor limit in Solaris determines the number of open file handles any single process can hold. For Envinsa installations, we recommend that you set the file descriptor limit to its maximum value before starting each application server instance. To do this, enter the following command that matches your shell environment: > ulimit -n 1024 (Bourne or Korn Shell) > unlimit descriptors (C Shell) We also recommend that you make this a permanent change to your application server startup scripts and batch files. This ensures that your application server will always have sufficient file descriptors. Install Guide For Tomcat Application Servers 15

16 Decide on Installation Choices Data Components The following recommendations apply to all Envinsa data components. Optimizing Disk Space for Data Components If you are installing multiple instances of Envinsa services on this computer, then you should only install the data components once. In the second installation, choose to reuse existing data and then select the data domain from the first installation. Installing Data for Multiple Countries By default, data is installed under the <Envinsa_home>/DataDomain directory. If you want to install data for multiple countries to the same domain location, then plan the directory structure that you want to install to at this location. For example, plan to use country-specific subdirectories under the data directory, so that it would have the following structure for Australia (AU), Germany (DE), and United Kingdom (UK) data: Envinsa/ DataDomain/ AU/ DE/ UK/ Supporting Multi-Country Routing Requests The Envinsa Route Service can generate routes that involve multiple countries. To use this feature, you must install the data for each country under the same data domain. For example, to create a route from France to Spain, you must install the data for both countries in the same directory. Decide on Installation Choices Before starting the Envinsa installer, you must decide on the following choices: Choosing Automatic or Manual Service Deployment Choosing a Graphical or Command-line Installation Choosing to Install from DVDs or a Local Directory Choosing Automatic or Manual Service Deployment The Envinsa installer can either deploy the Envinsa services to your application server instances or create WAR files that you can deploy yourself. The installer will prompt you with this choice. Note: If you are using the Envinsa installer to create WAR files that you will manually deploy on your application server, then contact Technical Support for further instructions. 16 Envinsa 4.4

17 Chapter 2: Preinstallation Tasks The WAR files created by the installer can only be deployed on the computer where they were created. You cannot deploy these WAR files to another computer. See your application server s documentation for instructions on deploying the WAR files. After deploying the services, you must perform the post-installation tasks described in this guide. This applies to both automatic and manual deployments. Choosing a Graphical or Command-line Installation You can install Envinsa using either a graphical or command-line installer. The graphical installer guides you through the installation process by asking a series of questions. This is the installer that most users will use to install Envinsa. The command-line installer allows you to install Envinsa from the command prompt or scripts. The command-line installer requires you to specify your installation preferences in a configuration file before running the installer. MapInfo expects only advanced users whose environments require a command-line installer to use this method. Choosing to Install from DVDs or a Local Directory You can install Envinsa either from the product DVDs or from your hard drive. If you install from DVDs, then the installer will prompt you to change disks during the installation process. Alternatively, you can copy the Envinsa DVDs to your hard drive or a shared network drive and install Envinsa components from that location. This method can simplify the installation process because you will not need to change disks after the installer starts. However, you must ensure that you have enough free disk space on the computer after copying the disks to perform the installation. Note: If you are using the command-line installer, then you must perform a network installation. To install from DVDs: If you are installing Envinsa on a UNIX or Linux computer, then note the following considerations: Do not start the installer directly from the DVD. Instead, run the installer from the DVD by starting it from your user directory or the root directory. This ensures that you will be able to eject the DVD to insert the next disk during the installation process. On AIX computers with only one DVD drive, you must copy the Envinsa Install Disk to your hard drive and then run the installer from your hard drive. On Solaris computers, always use the /cdrom/cdrom0 directory when referring to the DVD drive. A disk label directory may be available, but do not use it. To install from a directory: 1. Create a directory that will hold the contents of the Envinsa DVDs. 2. Copy the contents of each DVD disk to that directory. You must copy every disk excluding the license and documentation disks. 3. If you copied the DVDs to a computer that is not the computer where you are installing Envinsa, then you must ensure the directory where you copied the files is accessible to the computer where you are installing Envinsa. If you are installing Envinsa on a UNIX or Linux computer, then Install Guide For Tomcat Application Servers 17

18 Decide on Installation Choices mount the copied directory on the machine where you are installing Envinsa. If you are installing Envinsa on a Windows computer, then map the copied directory to a drive on the computer where you are installing Envinsa. After you finish copying the directories, you will have a directory structure similar to the following: ENVINSA_DVDS ENVDAT1_US_CA... ENV44SRV6 InstData This example shows the directory structure for the United States and Canada Envinsa media. All of the media directories are under the ENVINSA_DVDS directory, which was created in step Envinsa 4.4

19 Installing Envinsa 3 This chapter guides you through the process of installing Envinsa. You must complete all applicable tasks in Preinstallation Tasks in Chapter 2 on page 9 before continuing with this chapter. Note: This chapter uses forward slashes to separate directories in paths that apply to all operating systems. Windows users must use backslashes when specifying paths. In this section: Note: Only follow the instructions in one of the following sections. See Choosing a Graphical or Command-line Installation on page 17 for more information on the two installers. Using the Envinsa Installer Using the Command-line Installer

20 Using the Envinsa Installer This section guides you through the process of starting the Envinsa installer. IMPORTANT: You must perform all preinstallation tasks described in this guide before running the installer. To install Envinsa using the Envinsa installer: 1. Start the Envinsa installer by running one of the following commands: (UNIX or Linux) sh <source>/startinstall.sh (Windows) <source>\setup.exe Note: If you are running the installer from disk on a UNIX or Linux system, then enter the preceding command from the root directory or your home directory. Running the command from the directory where the disk is mounted can prevent you from ejecting the disk during the installation process. If you copied the Envinsa Install Disk DVD to your computer or a network drive, then <source> is the directory where you copied the DVD to. If you are running the installer from the DVD directly, then <source> is the DVD drive. This starts the Envinsa installer. While running the installer, you can click Help for more information on the current screen. 2. In the Introduction screen, review the introduction and click Next. 20 Envinsa 4.4

21 3. In the What s New screen, review the new features and click Next. Chapter 3: Installing Envinsa 4. In the License Agreement screen, review the agreement. If you agree with the agreement, then select I accept... and click Next to continue with the installation. Otherwise, select I do NOT accept... and click Cancel to exit the installer. Install Guide For Tomcat Application Servers 21

22 5. In the Enter Serial Number screen, enter your Envinsa serial number and click Next. The serial number is located on the outside of your Envinsa product box. 22 Envinsa 4.4

23 Chapter 3: Installing Envinsa 6. In the Choose the Envinsa Package Directory screen, click Choose... and select the directory that contains Envinsa.xml on your computer. After selecting the directory, click Next. Note: After clicking Next, you cannot return to this screen and select a different package directory. If you chose the wrong directory, then you must quit the installer and start it again. The Envinsa.xml file is included on the Envinsa License Disk or provided to you by your Envinsa representative. If you have saved the file on your computer, then specify the directory where you saved the file. Otherwise, insert the license disk and specify that directory. Install Guide For Tomcat Application Servers 23

24 7. In the Choose Install Set screen, select the services and data components that you want to install and click Next. If there are any data components listed under a service, then you must select at least one of them to use the service. Note: If you select FindLocation Service, then you must also select Directory Service. If you select Route Service, then you must also select Location Utility Service, Presentation Service and Map Manager Application. If you select Presentation Service, then you must also select Map Manager Application. If you select Map Manager Application, then you must also select Presentation Service. 24 Envinsa 4.4

25 Chapter 3: Installing Envinsa 8. If you chose to install Route data and there is pedestrian data available with that route data, then you will see the Select Route Data screen. On this screen, select if you want to install the pedestrian data along with the route data. Install Guide For Tomcat Application Servers 25

26 9. In the Choose an Application Server screen, do one of the following: Select Deploy Envinsa services into my existing application server and then select Tomcat. Select Create WAR files that I will manually deploy. Note: If you want to create WAR files that you will manually deploy on your application server, then contact Technical Support for further instructions before proceeding. For more information on this choice, see Choosing Automatic or Manual Service Deployment on page 16. Click Next to continue. 26 Envinsa 4.4

27 Chapter 3: Installing Envinsa 10. In the Define Server Instances screen, click Add and specify the following properties for each application server instance where you will install Envinsa services. Note: If you are creating WAR files that you will manually deploy later, then you may not see all of these fields. Server name Enter a name that uniquely identifies this server instance. You will use this name later in the installation process to assign services to application server instances. Server directory Enter the full path to the application server s home directory, or click Choose to select a directory. Host name Enter the DNS hostname or IP address of the machine hosting the Web application server. The host name must be a name that other computers can use to access the Envinsa services. For example, if machines in a different domain will access Envinsa, then you must specify a fully qualified host name. Port Enter the HTTP port number of the Web application server. Administrator name Enter the name for the application server's administration account. Administrator password Enter the password for the application server's administration account. Proxy URL If a proxy is used to access the Web application server, enter where <host> and <port> are the hostname and port number of the proxy. If you prefer, you can enter the IP address instead of the hostname. However, you cannot enter localhost or Select an instance and click Edit to modify any of the values you specified or click Remove to remove the instance from this list. After specifying all of your instances, click Next. Install Guide For Tomcat Application Servers 27

28 11. In the Assign Services to Servers screen, specify the application server instance where you want to deploy each service. You can also change the group name for each service. Administrators can use the group name to filter services in Enterprise Manager. After assigning all of the services, click Next. 28 Envinsa 4.4

29 Chapter 3: Installing Envinsa 12. In the Select Installation Source screen, do one of the following: Select Directory, if you copied the Envinsa DVDs to a directory on your computer. Select DVD, if you did not copy the DVDs. For more information on this choice, see Choosing to Install from DVDs or a Local Directory on page 17. Click Next to continue. Install Guide For Tomcat Application Servers 29

30 13. Depending on your choice on the previous screen, you will see one of the following screens. If you chose to install from a directory, then in the Specify the Network Location screen, click Choose and select the directory you copied the Envinsa DVDs to. Click Next to continue. If you chose to install from DVD, then in the Specify the Disk Drive screen, click Choose and select the drive you will use for the Envinsa DVDs. Click Next to continue. 30 Envinsa 4.4

31 Chapter 3: Installing Envinsa 14. In the Choose Install Directory screen, enter the directory where you want to install Envinsa and click Next. Note: When installing on Windows 64-bit OS, you must change the default install directory to not inlcude c:/program Files (x86) in the installation path. Note: If you are upgrading your Envinsa installation and you have already run the Envinsa Upgrade Installer, then enter the path to your existing installation here. If you have not run the upgrade installer, then exit the Envinsa Installer and read the Envinsa Upgrade Guide. Install Guide For Tomcat Application Servers 31

32 15. In the Enter User Name and Password screen, enter the user name and password for the Envinsa administrator account. The user name and password are both case sensitive and can only contain letters, numbers, and periods. The installer will create this account, which you use to access the Envinsa administrative tools such as Enterprise Manager and Content Manager. If you have previously installed Envinsa on this computer, then you must enter information for an existing administrator account. 32 Envinsa 4.4

33 Chapter 3: Installing Envinsa 16. In the Use Existing Data or Install New Data screen, specify if you want to install new data or not and click Next. Install Guide For Tomcat Application Servers 33

34 17. Depending on your choice on the previous screen, you will see one of the following screens. If you chose to install new data in the previous screen, then in the Choose Data Domain Directory screen, enter the directory where you want to install Envinsa data and click Next. If you chose to reuse existing data, then in the Choose Existing Envinsa Data Domain Directory screen, specify the location of your existing Envinsa data and click Next. 34 Envinsa 4.4

35 Chapter 3: Installing Envinsa 18. In Choose Java Virtual Machine screen, select a JDK virtual machine from the list and click Next. The installer will configure the Envinsa tools, such as Enterprise Manager and Content Manager, to use this virtual machine. You must select a JDK and not a JRE virtual machine. If the system JAVA_HOME environment variable is set on your system, then the Envinsa administrative tools will use JAVA_HOME virtual machine. If you are performing a typical installation, then the Tomcat instances will use the JVM you select from this list and not the default JVM specified by the JAVA_HOME environment variable. If the JAVA_HOME environment variable is not set on your system, then the Envinsa administrative tools and Tomcat instances will use the JVM you select from this list. Install Guide For Tomcat Application Servers 35

36 19. Depending on your operating system, you will see one of the following screens. If you are using Windows, then in the Choose Shortcut Directory screen, select where you want to create Envinsa shortcuts and click Next. Click Help for more information on these choices. If you are using UNIX or Linux, then in the Choose Link Directory screen, select where you want to create Envinsa links and click Next. Click Help for more information on these choices. 36 Envinsa 4.4

37 Chapter 3: Installing Envinsa 20. In the Pre-Installation Summary screen, review the installation options and click Install to start installing Envinsa. The installer will install Envinsa to your computer. If the installer prompts you to insert a data disk that you do not have, then the most likely cause is that you selected a data component that you are not licensed to use. To proceed with the installation, click Skip in the warning dialog. Install Guide For Tomcat Application Servers 37

38 21. After installing Envinsa, if you installed the Envinsa Demo application, the installer will ask you if you want to run the application. Select your choice and click Next. Note: Some Envinsa services and components require that you perform additional tasks before you can run them successfully. You may not be able to run all parts of the Demo application until you complete all of the tasks described in Chapter 4: Postinstallation Tasks. For information on running the demo application, see Appendix A: Running the Envinsa Demo Application. 38 Envinsa 4.4

39 Chapter 3: Installing Envinsa 22. In the Install Complete screen, click Done to exit the installer. This completes the Envinsa installation process, however, there are additional tasks you must perform to configure the installation. You must perform these tasks to successfully use Envinsa. For the remaining tasks, see Postinstallation Tasks on page 41. Using the Command-line Installer This section guides you through installing Envinsa using the command-line installer. IMPORTANT: You must perform all preinstallation tasks described in this guide before running the installer. To use the command-line installer: 1. Open or change to the following directory: <Envinsa_media>/InstData/<os>/VM where <Envinsa_media> is the directory where you copied the Envinsa DVDs to and <os> represents your operating system. For more information on this task, see Choosing a Graphical or Command-line Installation on page Copy the installer.properties file located in the <Envinsa_media>/InstData/Templates/ to the directory you opened in step 1. You now have the following file: <Envinsa_media>/InstData/<os>/VM/installer.properties 3. Change the permissions for the file to ensure you can save changes you make to it. Install Guide For Tomcat Application Servers 39

40 Using the Command-line Installer 4. Open installer.properties in a text editor. 5. Specify values for the parameters in the file. See the comments in the file for more information about each parameter. Note: If you install Find Location, then you must also install Directory. If you install Route, then you must also install Presentation and Map Manager. If you install Presentation, then you must also install MapManager. If you are installing to a WAR file, contact Technical Support for further instructions before proceeding. Once you have contacted technical support for installation instructions, you must change the SERVER_TYPE property equal to WARFile. See the comments in the file for more information. 6. Depending on your operating system, perform the following tasks from the same directory as the properties file. If you are using UNIX or Linux, then do the following: a. In a terminal, run sh install.bin. This immediately returns you to a command prompt. b. Monitor /tmp/envinsa_errors.log. This file is updated as the installer installs each component. The installation is complete after the following line appears in the file: calling cleanupunix() If you are using Windows, then do the following: a. At the command prompt, run install.exe. This immediately returns you to a command prompt. b. Monitor C:\TMP\envinsa_errors.log. This file is updated as the installer installs each component. The installation is complete after the following line appears in the file: calling CleanUpWin32() 7. Rename installer.properties. If you do not rename or move this file, then the next time you try to start the installer from this directory, it will automatically use the values set in this file. Renaming this file prevents you or other users from accidentally reinstalling Envinsa. This completes the Envinsa installation process, however, there are additional tasks you must perform to configure the installation. You must perform these tasks to successfully use Envinsa. For the remaining tasks, see Postinstallation Tasks on page Envinsa 4.4

41 Postinstallation Tasks 4 This chapter describes the steps you must perform after running the Envinsa installer. Note: This chapter uses forward slashes to separate directories in paths that apply to all operating systems. Windows users must use backslashes when specifying paths. In this section: Manually Deploying WAR Files Setting Up JDBC Drivers Configuring Tomcat Instances Configuring Envinsa Services

42 Setting Up JDBC Drivers Manually Deploying WAR Files If you had the installer create WAR files for you to manually deploy, then you can find the files in <Envinsa_home>/PlatformDomain/WARFiles, where <Envinsa_home> is the Envinsa installation directory. There will be a subdirectory for each application server instance you specified in the installer. For information about deploying the WAR files, see your application server documentation. Setting Up JDBC Drivers The following services or components require database connections using JDBC: Content Manager Directory Service Map Manager Map Tiling Service Presentation Service Web Feature Service Web Map Service To install the JDBC drivers for these services and components, do the following: 1. Obtain copies of the JDBC driver JAR files for your database. For IBM DB2 (non-spatial), use the DB2 Universal JDBC Driver file, db2jcc.jar. This files are installed into <DB2_home>/sqllib/java when you install DB2. For IBM DB2 Spatial Extender, use the DB2 Universal JDBC Driver files, db2jcc.jar and db2jcc_license_cu.jar. These files are installed into <DB2_home>/sqllib/java when you install DB2. For Microsoft SQL Server, download the JDBC drivers for your database from msdn.microsoft.com. For Oracle Spatial, download the ojdbc14.jar JDBC driver from otn.oracle.com. For MySQL, download the Connector/J JDBC driver from dev.mysql.com. 2. Copy the driver files to <Tomcat_home>/webapps/<service>/WEB-INF/lib directory, where <Tomcat_home> is your Tomcat installation directory and <service> is the name of the service you want to use the JDBC driver with. Repeat this for each of the services in the above list that you are using. As an example, for the Directory Service on Windows, copy the driver files to C:\Tomcat\webapps\Directory\WEB-INF\lib. 3. If you installed Content Manager, then copy the driver files to <Envinsa_home>/PlatformDomain/CMC/lib, where <Envinsa_home> is the directory where you installed Envinsa. 4. If you installed Map Manager, then copy the driver files to <Envinsa_home>/PlatformDomain/MapManager/lib, where <Envinsa_home> is the directory where you installed Envinsa. 42 Envinsa 4.4

43 Chapter 4: Postinstallation Tasks This change will take effect the next time you start the application server instances. After configuring the JDBC driver, you must create data sources for each of the services and components described at the beginning of this section. See each service s Reference Guide for more information on doing this. For more information about installing the JDBC drivers, see the documentation for your database and application server. Configuring Tomcat Instances Tomcat users must complete the following task before using Envinsa: Upgrade JDK Files for Security Complete all of the tasks in this section and then restart your application server instances so the changes can take effect. Upgrade JDK Files for Security Note: This section only applies if you are using JDK 1.4. If you are using JDK 1.5, then you can skip this section. The Sun JDK 1.4 and Tomcat both include an old version of the Xalan-Java jar files. To enable security for Web service requests and responses, you must do the following: 1. Locate the following jar files in the WEB-INF/lib directory for any Envinsa service: xalan.jar xercesimpl.jar xml-apis.jar xmlparserapis.jar For example, for the WebMap service, the directory is <Tomcat_home>/webapps/WebMap/WEB-INF/lib. 2. Create a <Java_home>/common/endorsed directory, if it does not already exist, where <Java_home> is the Java installation your Tomcat instances use. 3. Copy the jar files from step 1 into <Java_home>/common/endorsed. 4. Create a <Tomcat_home>/common/endorsed directory, if it does not already exist, where <Tomcat_home> is where your Tomcat instance is installed. You must create this directory for each Tomcat instance that runs an Envinsa service. 5. Copy the jar files from step 1 into all the <Tomcat_home>/common/endorsed directories you created step 4. Configuring Envinsa Services This section describes additional tasks you must perform for specific services. Complete the following sections for the services you have installed: Install Guide For Tomcat Application Servers 43

44 Configuring Envinsa Services Presentation and Map Tiling Services Profile Management Service Presentation and Map Tiling Services If you have installed the Presentation or Map Tiling service, then perform the following tasks: Enabling Native Acceleration Method (Linux, Solaris, and Windows only) Configuring the Virtual Frame Buffer (Solaris only) Enabling Native Acceleration Method Note: This section only applies to Linux, Solaris, and Windows installations. The Presentation and Map Tiling Services work with the Java Advanced Imaging (JAI) API. When you install these services, the installer also installs platform-specific library files for JAI 1.1.2, which are optimized for your operating system. To optimize these services, add the correct JAI native library to your environment variables. To do this: 1. Add <Envinsa_home>/PlatformDomain/Presentation/JAI/native/<os> to your PATH environment variable, where <Envinsa_home> is the directory where you installed Envinsa and <os> is the subdirectory that corresponds to your operating system. 2. If you are using Solaris or a Linux operating system, then add <Envinsa_home>/PlatformDomain/Presentation/JAI/native/<os> to your LD_LIBRARY_PATH environment variable, where <Envinsa_home> is the directory where you installed Envinsa and <os> is the subdirectory that corresponds to your operating system. If you installed the Map Tiling Service and not the Presentation Service, then replace the Presentation directory in the paths above with MapTiling. This change takes effect the next time you start the application server instances. For more information about JAI refer to the Sun Web site at Configuring the Virtual Frame Buffer Note: This section only applies to Solaris installations using a virtual frame buffer. If you are using the Presentation or Map Tiling service on a Solaris system and using a virtual frame buffer, then you must add the following parameter to the _JAVA_OPTIONS environment variable: -Dsun.java2d.pmoffscreen=false This change ensures that your computer can render theme legends. For more information on the pmoffscreen parameter, see the Java documentation. This change will take effect the next time you start the application server instances. 44 Envinsa 4.4

45 Chapter 4: Postinstallation Tasks Profile Management Service The Profile Management service requires a running LDAP directory server. Before using the Profile Management service, you must install and configure an LDAP schema for your directory server. To do this: 1. Install the Envinsa LDAP Schema 2. Configure the Directory Server 3. Register the Directory Server with Envinsa Install the Envinsa LDAP Schema To install the schema: 1. Open or change to the <Envinsa_home>/PlatformDomain/Profile/scripts directory, where <Envinsa_home> is the directory where you installed Envinsa. 2. Open one of the following scripts in a text editor. If you are using Windows, then open create_ldap_schema.bat. If you are using UNIX or Linux, then open create_ldap_schema.sh. 3. In the text editor, modify the following parameters with values that correspond to your LDAP server: LDAP_URL="ldap://miaware.mapinfo.com:389" LDAP_USER="cn=Directory Manager" LDAP_PASSWD="mypassword" 4. Save your changes to the script. 5. Run the script. The script will run and install the Envinsa LDAP schema to your directory. Continue configuring the Profile Management service with Configure the Directory Server below. Configure the Directory Server The following steps describe the general steps you must perform to configure your directory server for the Profile Management service. If you are using an iplanet Directory Server, then see Configuring an iplanet Directory Server in Appendix B on page 51. Otherwise, see your directory server documentation for more information on completing these steps. 1. On the directory server, create a new root suffix named o=miaware.com and an associated database. 2. If you are using UNIX, then convert the line endings for <Envinsa_home>/PlatformDomain/Profile/SampleProfileData/miaware.com.ld if using dos2unix or a similar command. <Envinsa_home> is the directory where you installed Envinsa. 3. Initialize the database you created for the root suffix and populate it with the sample data from <Envinsa_home>/PlatformDomain/Profile/SampleProfileData/miaware.com.ld Install Guide For Tomcat Application Servers 45

46 Configuring Envinsa Services if, where <Envinsa_home> is the directory where you installed Envinsa. This file contains sample data for the Envinsa Demo application. You now have a directory with sample data for the Envinsa Demo application. You can also use this sample data as a template for your profile data. Continue configuring the Profile Management service with Register the Directory Server with Envinsa below. Register the Directory Server with Envinsa To register your directory server with Envinsa, you must perform the following tasks: 1. Start Envinsa Enterprise Manager by running either of the following commands: If you are using Windows, then run <Envinsa_home>\Tools\EnterpriseManager\EnterpriseManager.bat. Otherwise, run <Envinsa_home>/Tools/EnterpriseManager/EnterpriseManager.sh. 2. Log into Enterprise Manager using the Envinsa administrator account you created during the installation process. 3. In the Enterprise Manager menu, select Tools > Views > Advanced. This ensures you can see all administration options in the menus. 4. In the list of services and Envinsa components, select the Profile service. 5. In the menu, select View > Services > Registration > Parameter Settings. This displays the Parameter Settings tab for the service. 6. Under the tab, expand all options under ProfileService and select Properties. This displays the Profile Management service properties. 7. Double-click on each of the following parameters and set them to the appropriate values for your directory server. These must match the values you specified in Install the Envinsa LDAP Schema on page 45. Enterprise Identifier: Enter miaware.com. This value must match an Envinsa root suffix. LDAP Server URL LDAP Administrator Identifier LDAP Administrator Password 8. Click the Save icon ( ) to save your changes. This completes all of the tasks you must perform to configure the Profile Management service. 46 Envinsa 4.4

47 Running the Envinsa Demo Application A The Envinsa Demo Application allows you to test your Envinsa installation and use the services. In this section: Starting the Envinsa Demo Application Using the Envinsa Demo Application

48 Using the Envinsa Demo Application Starting the Envinsa Demo Application To start the Envinsa Demo Application, you must: 1. Start the application server instances that you configured for Envinsa services. 2. Open in a web browser, where <hostname> is the name of your computer, <port> is the port number for the instance where you installed the Envinsa Demo Application. You can see the name and port numbers for the application by opening <Envinsa_home>/Logs/envinsa_installer_log_<time>.htm, where <Envinsa_home> is the directory where you installed Envinsa, and <time> is the approximate time when you installed Envinsa. This file lists information about your Envinsa installation. 3. Log in to the application. The default user name is demo and the default password is demo. After logging in, you will see the main page for the demo application. Using the Envinsa Demo Application The Envinsa Demo Application has samples that demonstrate how many of the Envinsa services work. For each sample, you can see a simple HTML form where you can enter your request information or the corresponding XML text that is sent to the web service. When you submit a request, the application forwards it to the Envinsa service, and then displays the resulting XML text in the browser. For Presentation Service requests, you also have the option of displaying the map as a graphic. The following example explains how you can use the application create a map with the Presentation Service. To do this: 1. Log in to the Envinsa Demo Application. For information on this task, see Starting the Envinsa Demo Application on page On the left side of the browser window, under Service Demo, select HTML. This displays HTML forms instead of XML text on the right side of the window. 3. On the left side of the window, select Presentation. This displays Envinsa Presentation Web Service on the right side of the window. 4. From the drop down list, select AnalysisLayer. This shows the AnalysisLayer sample form. 48 Envinsa 4.4

49 Chapter A: Running the Envinsa Demo Application 5. Click Submit Request to submit the default form information. This opens a new browser window with a world map showing the relative population of each country and how each population is distributed by age groups. Generating this map was one sample in the demo application. You can continue using the demo application by submitting requests for different samples and services. Install Guide For Tomcat Application Servers 49

50 Using the Envinsa Demo Application 50 Envinsa 4.4

51 Configuring an iplanet Directory Server B This appendix provides detailed instructions on configuring the iplanet Directory Server for the Envinsa Profile Management service. These steps are described for any directory server in Install the Envinsa LDAP Schema on page 45. The following steps assume that you have already installed the Envinsa LDAP schema to your directory server and only describe the iplanet-specific tasks you must perform. To configure an iplanet directory server for the Profile Management service: 1. Start the iplanet Console and log in as cn=directory Manager. You must specify the directory manager password for this account. 2. In the console, expand the list of servers until you see Directory Server. 3. Double-click Directory Server to open it. This opens another console window showing a list of tasks you can perform for this server. 4. Select the Configuration tab and select Data in the navigation tree.

52 5. Right-click on Data and select New Root Suffix from the menu that appears. This opens the Create new root suffix dialog. 6. Complete the dialog as follows: a. In the New suffix field, enter o=miaware.com. b. Check the Create associated database... check box. c. In the Database name field, enter a name for the database. d. Click OK to create the root suffix. 7. Under the Configuration tab, expand Data to show the o=miaware.com root suffix. Expand the suffix and select the database you created. 8. Initialize the database as follows: a. Right-click on the database and select Initialize Database from the menu that appears. This opens a dialog asking you for an LDIF file. b. If you are using UNIX, then convert the line endings for <Envinsa_home>/ PlatformDomain/Profile/SampleProfileData/miaware.com.ldif using dos2unix or a similar command. <Envinsa_home> is the directory where you installed Envinsa. c. In the dialog, enter <Envinsa_home>/PlatformDomain/Profile/ SampleProfileData/miaware.com.ldif, where <Envinsa_home> is the directory where you installed Envinsa. This file contains sample data for the Envinsa Demo application. d. Click OK and then Yes to initialize the database. This opens a dialog showing the status of the initialization. e. When Import Finished appears on the dialog, click Close. This completes the iplanet-specific tasks you must perform to use the Profile Management service. Before using the service, you must register it with Envinsa. For more information, see Register the Directory Server with Envinsa on page Envinsa 4.4