Envinsa INSTALL GUIDE. Version 4.2. For Tomcat Application Servers

Transcription

1 Envinsa Version 4.2 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 MapInfo Corporation, One Global View, Troy, New York MapInfo Corporation. All rights reserved. MapInfo, the MapInfo logo and Envinsa are trademarks of MapInfo Corporation and/or its affiliates. MapInfo Corporate Headquarters: Phone: Fax: Sales: Government Sales: Technical Support: MapInfo UK and EMEA Headquarters: Phone: Fax: Technical Support: MapInfo Asia Pacific Headquarters: Phone: Fax: Technical Support: Contact information for all MapInfo 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. Adobe Acrobat is a registered trademark of Adobe Systems Incorporated in the United States. 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. October 9, 2007

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 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 Setting up JDBC Drivers Configuring Tomcat Instances Upgrade JDK Files for Security Configuring Envinsa Services Presentation Service Profile Management Service

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

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

7 Chapter 1: Requirements Envinsa Requirements (continued) Category Requirement Operating Systems Any of: Windows Server 2003 Standard Edition (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 (64-bit) Application Servers Any of: Apache Tomcat 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 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 Spatial Extender Microsoft SQL Server 2000 Service Pack 3 with MapInfo SpatialWare 4.8 Microsoft SQL Server 2005 MYSQL 4.1 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.2

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. 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. 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. 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. 10 Envinsa 4.2

11 Chapter 2: Preinstallation Tasks 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): 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: <tomcat-users> <role rolename="manager"/> Install Guide For Tomcat Application Servers 11

12 Tasks <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.2

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

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-4.2/ 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 a Graphical or Command-line Installation Choosing to Install from DVDs or a Local Directory 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. 16 Envinsa 4.2

17 Choosing to Install from DVDs or a Local Directory Chapter 2: Preinstallation Tasks 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 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 ENV40DAT1_US_CA... ENV42SRV6 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 1. Install Guide For Tomcat Application Servers 17

18 Decide on Installation Choices 18 Envinsa 4.2

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. In this section: Note: Only follow the instructions in one of the following sections. See Choosing a Graphical or Command-line Installation on page 16 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.2

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

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 Find Location, then you must also select Directory. If you select Route, then you must also select Presentation and Map Manager. If you select Presentation, then you must also select MapManager. 24 Envinsa 4.2

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. 9. In the Choose an Application Server screen, select Deploy Envinsa services into my existing application server and click Next. Install Guide For Tomcat Application Servers 25

26 10. In the Select Web Application Server screen, select Tomcat and click Next. 26 Envinsa 4.2

27 Chapter 3: Installing Envinsa 11. In the Select Service to Install in Server Instance screen, you must choose which services you want to install in this application server instance. If you are installing Envinsa into multiple instances, then see Optimizing Application Server Performance on page 14 for recommendations. Select the services you want to install to this application server instance and click Next. You can select multiple services by holding down the Control key while selecting each service. Install Guide For Tomcat Application Servers 27

28 12. In the Enter Tomcat Application Server Information screen, enter the configuration information for the application server instance and click Next. For more information on the fields in this screen, click Help. Note: When you click Next, the installer validates this information against your application server instance. You may notice a delay as the installer does this validation. 28 Envinsa 4.2

29 Chapter 3: Installing Envinsa 13. In the Install More Services screen, do the following: If you want to install Envinsa services into another application server instance, then select Yes and click Next. When you click Next, the installer will ask you to configure the next application server instance starting from step 10. If you have configured all of your application server instances for Envinsa, then select No and click Next. Install Guide For Tomcat Application Servers 29

30 14. In the Select Installation Source screen: 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. 30 Envinsa 4.2

31 Chapter 3: Installing Envinsa 15. 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. Install Guide For Tomcat Application Servers 31

32 16. In the Choose Install Directory screen, enter the directory where you want to install Envinsa and click Next. 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. 32 Envinsa 4.2

33 Chapter 3: Installing Envinsa 17. 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. Install Guide For Tomcat Application Servers 33

34 18. In the Use Existing Data or Install New Data screen, specify if you want to install new data or not and click Next. 34 Envinsa 4.2

35 Chapter 3: Installing Envinsa 19. 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. Install Guide For Tomcat Application Servers 35

36 20. 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. 36 Envinsa 4.2

37 21. Depending on your operating system, you will see one of the following screens. Chapter 3: Installing Envinsa 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. Install Guide For Tomcat Application Servers 37

38 22. 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. 38 Envinsa 4.2

39 Chapter 3: Installing Envinsa 23. 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. Install Guide For Tomcat Application Servers 39

40 Using the Command-line Installer 24. 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 43. 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 one of the following files to the directory you opened in step 1. If you are installing data for the United States and Canada (US_CA), then copy <Envinsa_media>/InstData/Templates/silentinstall_US_CA.properties. If you are installing data for any single country, then copy <Envinsa_media>/InstData/ Templates/silentinstall_GENERIC.properties. 40 Envinsa 4.2

41 Chapter 3: Installing Envinsa 3. Rename the file you copied to installer.properties. You now have the following file: <Envinsa_media>/InstData/<os>/VM/installer.properties 4. Change the permissions for the file to ensure you can save changes you make to it. 5. Open installer.properties in a text editor. 6. If you are using the single country properties file, then replace all occurrences of {ISOCC2} in the file with the two letter country code for the data you are installing. For example, if you are installing Envinsa with data for Germany, then replace {ISOCC2} with DE. 7. Specify values for the parameters in the file. See the comments in the file for more information about each parameter. 8. 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. 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. 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() 9. 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 43. Install Guide For Tomcat Application Servers 41

42 Using the Command-line Installer 42 Envinsa 4.2

43 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: Setting up JDBC Drivers Configuring Tomcat Instances Configuring Envinsa Services

44 Configuring Tomcat Instances 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. 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. 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: 44 Envinsa 4.2

45 Chapter 4: Postinstallation Tasks 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: Presentation Service Profile Management Service Presentation Service If you have installed the Presentation service, then perform the following tasks: Enabling Native Acceleration Method Configuring the Virtual Frame Buffer (Solaris only) Install Guide For Tomcat Application Servers 45

46 Configuring Envinsa Services Enabling Native Acceleration Method 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/tools/<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/tools/<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. This change will take 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. 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 46 Envinsa 4.2

47 Chapter 4: Postinstallation Tasks 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 53. 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 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. Install Guide For Tomcat Application Servers 47

48 Configuring Envinsa Services 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 47. 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. 48 Envinsa 4.2

49 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

50 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. 50 Envinsa 4.2

51 Appendix 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 51

52 Using the Envinsa Demo Application 52 Envinsa 4.2

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

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