installation & operations guide - desinventar.net€¦ · web viewinstallation of tomcat 23....

MANUAL INSTALLATION For advanced Users or Users with other Java Web

Applications

DesInventar Server 9

Version 9.2.11

December 2009.

DesInventar-Web Installation & Operations Guide

Table of ContentsTable of Contents...................................................................................2Send Us Your Comments........................................................................3Installation Overview..............................................................................4Introducing DesInventar Server 7......................................................5DesInventar Requirements..................................................................6

Internet Connection requirements...................................................6Software requirements....................................................................6Manual Installation Requirements:...................................................7Database requirements...................................................................7Hardware requirements...................................................................8

Using the DesInventar Server Installer...............................................9Manual Installation of DesInventar....................................................21

Installation of the Java2 platform software....................................21Installation of Tomcat....................................................................23Testing the Installation..................................................................24Deploying DesInventar Web Application........................................24Configuring Tomcat........................................................................26

Appendix A...........................................................................................32WINDOWS Installation of the Java2 platform software...................32Installation of Tomcat....................................................................36

© La Red de Estudios Sociales en Prevención de Desastres en América Latina


Send Us Your CommentsThis section describes how to contact LA RED/DesInventar Web-Development team if you have issues with the documentation or software. It also provides a list of useful resources for administrators and developers.

Send us email to If [email protected] Have issues with [email protected] Have issues with Software

You can visit us at http://www.desinventar.org And at http://www.desinventar.net

This product may use or reference software from the following third parties:

Official Java/JSP site:http://java.sun.com

Oracle Corporation (Oracle 8i, 9i)http://www.oracle.com

Microsoft Corporation (MS Visual Basic, MS Access, MS SQL Server)http://www.microsoft.com

Apache Software foundation (Apache and Tomcat servers):http://www.apache.org

Official Tomcat web site:http://jakarta.apache.org/


http://jakarta.apache.org/

http://www.apache.org/

http://www.microsoft.com/

http://www.oracle.com/

http://java.sun.com/

http://www.desinventar.net/

http://www.desinventar.org/

mailto:[email protected]

mailto:[email protected]


Installation OverviewDesInventar-web is a 100% pure Java application running using a JSP (Java Server Pages) powered interface. As such it requires a Java Virtual Machine (JVM) and a JSP/Servlet container to run and support al its features, usually the Apache Tomcat server.

For most users installation is a straightforward process, as simple as inserting a CD in the disc drive and following the instructions of the installer.

Some other more sophisticated users may want to take advantage of advanced Database management systems and/or other versions of Tomcat or other Java Application Servers. Those users should follow the instructions in the Manual Installation Section.



Introducing DesInventar Server 9One of the flagship products of LA RED, DesInventar is a full-featured, 100% Java, platform and database independent Internet application. It allows multiple simultaneous users being capable of remotely updating the Disaster inventory database taking advantage of Internet connections.

As it’s brother, the stand-alone version of DesInventar it is composed of two clearly separated modules, a data management/entry tool and an analysis/query tool.

DesInventar supports the most popular search engines and databases, including Oracle, MS SQL Server, PostgreSQL, MySQL and MS Access.

DesInventar is dynamically configured, fed and controlled via a web interface powered by a Java Application Server.

This JSP/Java implementation has been successfully tested in the following OS platforms:

Windows (98, 2000 pro, 2000 server, 2003 server, XP home/Pro). Sun Solaris 8 Linux Redhat 7.2 Hewlett Packard HP-UX 11

This document focuses entirely in the deployment and installation of DesInventar in Windows environments. However, it can be used as general guide for other operating systems, in which it must be installed manually.



DesInventar RequirementsThere are several requirements to run the System (in this document the word ‘System’ is used as a synonym of ‘DesInventar’):

Internet Connection requirements

Clients:DesInventar makes intensive use of the connection to Internet. A dial-up connection to the Internet is considered enough generally for Clients, but depending on user requirements it can provide a slow service.

A high-speed Internet connection is highly recommended. The higher the volume of Datacards to retrieve and process, the higher speed recommended.

Servers:The DesInventar Server must run in an environment with high Internet connectivity. In case of an Intranet server, a normal LAN (10/100 baseT) will be more than enough.

For Internet servers, the bandwidth must be calculated base on number of clients, expected size of the queries and updates and response time expectations.

Please note that in many cases DesInventar will require a lot of bandwidth, which can be an issue especially if DesInventar is to be run in the same machine that serves another web sites. DesInventar will consume also processor, memory and database resources.

In such cases is recommended to run DesInventar in a separate machine with an independent Internet connection.

Software requirements

Being a pure Java application, DesInventar can run in almost any software platform. It has been tested and successfully run in the



several Operating Systems. However, this guide is intended for administrators of Windows operating systems.

While Clients of DIS7 can run in almost any version of Windows higher that Win95, Servers should run at the minimum in one of the following:

Windows NT, Windows 2000 Server or Windows Server 2003.

In the case of Intranet servers Windows 2000 Profesional or Windows XP professional can be considered.

Manual Installation Requirements:

The main requirement to implement a DI Server is an appropriate JVM, supporting Java2 Standard Edition, SDK version 5 or higher. The System also requires a JSP/Servlet container that implements the Servlet 2.3 and JSP 1.2 specification.

No extra software is required (except the database software, of course) in order to run DesInventar itself.

Among others, the following Web Servers and Application Servers comply with these requirements:

- Tomcat 4.x, 5.x or 6.x- IBM Websphere- Bea WebLogic- Sun ONE application Server- Sun Java Web Server- Oracle Application Server

Database requirements

DesInventar software uses JDBC to connect to relational database engines. Although in theory the JDBC presents a uniform interface to any ‘standard’ SQL driven database, the reality is that there are several incompatibilities among the different implementations of SQL and datatypes in the market.

DesInventar has been tested with the following database/indexing systems:



- Oracle 8i, Oracle 9i, Oracle 10g, Oracle 10express or Oracle 11.- MS Access- MS SQL Server 2000 or higher- PostgreSQL 7.4 or higher

In theory DesInventar should run MySQL with no problems, but newer versions hasn’t been tested yet.

No tests have been performed on other databases like DB2, etc.

Hardware requirements

DesInventar requires:

- a Minimum of 256 Mb. Of Ram, that may be higher depending on the number of concurrent users.

- 100Mbs approximately for Java and Tomcat and depending on the number of databases and documents (DATACARDS) anything above 100Mbs of additional hard disk space.



Manual Installation of DesInventarManual Installation Overview

This section shows how to install DesInventar software in a specific JSP/Servlet container (Tomcat 4.x or 5.x).

Other JSP/Servlet containers may be used instead of Tomcat, and the application itself has been built in such a way that it’s independent of the container, as a standard Java Web Application.

The installation of DesInventar in such an environment (Java 2/ Tomcat) involves several steps:

- Downloading and Installing a Java 2 Standard Edition JDK (Java Development Kit)

- Downloading and Installing Tomcat- Deploying DesInventar Web Application- Creating the database connections and tables DesInventar will

use- Configuring the system- Other post-installation tasks (such as configuring a firewall, etc.)

The distribution CD contains downloads of both Java 2 (JDK 1.5) and Tomcat (Tomcat 5.1) suitable for DesInventar under Windows environments. However, if the end system requirements are different, DesInventar should run with other versions of both the JDK and Tomcat.

This document assumes that an appropriate operating system has been set-up and configured, as well as the database engine has been installed and it’s up and running.

Please note that most configuration issues involve providing DesInventar with the appropriate drivers and database access parameters. More info on this can be found in the next few sections.

The installation of DesInventar in an environment with Java 2 and Tomcat 4.1 involves several steps:



Installation of the Java2 platform software

Start by downloading the Java 2 Standard Edition JDK (Java Development Kit) from:

http://java.sun.com/j2se

The latest version of the JDK at the moment of this writing Note there are two packages available: the JRE (Java Runtime Environment) and the JDK itself. You must download the full JDK, or use the copy of the JDK installer for Windows supplied in the distribution CD.

To install the JDK just follow the instructions of the installer. We recommend installing the JDK in a directory at the root level, with a short name (i.e /jdk1.3), with no embedded spaces. This will greatly simplify the path and class path names and will avoid problems caused by spaces in names.

A JDK interactive installer is supplied for Windows environments. Please refer to Appendix A for a detailed explanation on how to use this Windows installer.


http://java.sun.com/j2se


Installation of Tomcat

Tomcat can be downloaded from the Apache web site at:

http://apache.mirrored.ca/jakarta/tomcat-4/binaries

For Windows installations you can use the download of Tomcat 4.1.XX supplied with the distribution CD.

Configuring and setting up Tomcat requires several steps: deploying the Tomcat software itself, that must be done after installing the full Java 2 development kit (JDK 1.3/4), defining the environment variables and modifying/editing several configuration files.

The software (Tomcat latest release of v. 4.1.X) is to be downloaded from jakarta.apache.com as a binary distribution and installed in the hard disk.

The procedure to install Tomcat will vary from platform to platform. On Unix like environments Tomcat is distributed as a gzipped tarball. The gunzip utility will be needed to decompress and later untar the file. Please refer to the on-line documentation for more information about this process.

An interactive installer is supplied for Windows environments. Please refer to Appendix A for a detailed explanation on how to use the Windows installer.

In a Windows environment we suggest to install Tomcat in the C: drive (to reduce to the maximum problems of drive management, as the Tomcat service will run from and try to access files by default in C:).

We strongly suggest to rename the directory Jakarta-tomcat-4.1.XX to tomcat for simplicity.

The DesInventar application distribution CD contains a copy of the Windows based Installer for Tomcat version 4.1.18 (against which the application was developed and tested).

We recommend installing Tomcat:

- in Unix like environments in /usr/local/tomcat- in Windows in c:\tomcat




Testing the Installation

To confirm that the installation was successful do the following:

Open an Internet Explorer in the web server machine. Type http://localhost:8080 in the address bar, and hit the ‘enter’ key. It is assumed here that Tomcat was installed in port 8080. Please change the port number accordingly. If Tomcat was installed in port 80 no port specification is required, just type http://localhost

If everything was properly installed, the screen should look like:

This test can be performed from the localhost machine or from any other machine using the network name of the computer instead of ‘localhost’.


http://localhost/

http://localhost:8080/


Deploying DesInventar Web Application

Copying the files: The installation of the software is extremely simple, it’s just copying the directory DesInventar in the distribution CD to a suitable place in the hard disk.

WE STRONGLY RECOMMEND TO COPY DESINVENTAR SOFTWARE TO THE /webapps FOLDER OF TOMCAT. This follows the standard for deployment of Java2/JSP/Servlet web applications.

The directory with default properties, /etc/DesInventar with all the files it contains must be also copied. The folder /etc exists by default in Unix like environments but it must be created in Windows. The structure /etc/DesInventar must exist, no matter the OS.

Removing the read-only attribute: on certain operating systems the copy operation will also copy the read-only status that files have in a CD. Such attribute must be changed manually.

In a Windows environment use the attrib command in a DOS command window:

attrib –r c:\xxxxx\DesInventar\* /s

OR

attrib –r c:\tomcat\webappss\DesInventar\* /s

also:

attrib –r c:\etc\DesInventar\* /s

Where xxxxx is the folder where DesInventar was copied, typically under tomcat/webapps.

Permissions: must be set so that the user running Tomcat and DesInventar has access to all directories involved. This is especially critical in Unix like systems :

/etc/DesInventar/*



/usr/local/tomcat/* (or wherever tomcat is installed)/xxx/DesInventar/* (or wherever DesInventar is installed).

Another issue to consider with Unix-like systems is the permission to use ports less that 1024. Only the root user can start processes that take these ports.

Setting environment variables: Environment variables tell the system where to find specific pieces of software.

In Windows operating system NO environment variables must be set. In a Unix like environment it is somewhat more complex as it needs settings for PATH, JAVA_HOME and TOMCAT_HOME. Please refer to the end of Appendix A on how to set these variables and their values.

In addition to these variables the Unix environments usually need the shared library paths that will allow software components to locate dynamic libraries.

These environment variables can be declared in a variety of places, ranging from the user profile files (.profile) to the specific scripts where they can be temporarily declared using setenv or set … export, depending on the shell. The technique suggested with DesInventar is the later. Example Unix (Linux, to be specific) scripts can be found in the /xxxxx/DesInventar/WEB-INF/classes directories.

The administrator will have to customize the according to the settings of the system and the database and/or indexing engine used.

Determining and making available drivers: JDBC drivers for databases must be made available to DesInventar and Tomcat. The easiest way of accomplishing this is to copy the jar files corresponding to the drivers to the directory /usr/local/tomcat/common/lib (or c:\tomcat\common\lib on a windows machine), if the drivers are to be used across all applications, OR copy them to the WEB-INF/lib directory of the DesInventar application if the drivers are to be used only by DesInventar.

Each vendor is responsible for supplying these driver files. Oracle supplies them as zip files, which have to be unpacked and the


converted to jar format using the command jar, supplied with the Java installer.

Configuring Tomcat

There are several configuration files required to run Tomcat (all of them located in the directory conf under the main Tomcat directory:

- conf/server.xml : the default server.xml file has to be modified in the <context> section to define the application. This application name (which does not need to be the directory name in which the application is deployed, it is a symbolic application name), must be the word DesInventar.

The most important parameter set is enclosed between <Context tags. The name of the application (DesInventar) and the document root (the folder where DesInventar files were copied into) are defined here.

Example:

 <Context path="/DesInventar"

docBase="DesInventar" debug="0"privileged="true"/>

NOTE: this example assumes DesInventar was installed in the webapps directory of Tomcat. For installations on other folders, change the parameter docBase to the fully qualified path of the installation, including the Drive in Windows systems.

The example context can be erased safely from the server.xml file under the \tomcat\conf folder. It will have no effect on the document. Erase all lines between <Context path=”/examples” …. and the next </Context> tag.

For users installing version 4.1.18, a pre-defined server.xml file is supplied with the distribution CD. This initial configuration file supplied by LA RED contains tags enabling:

o The http connector running on port 8080 (same as default)o The AJP13 connector, required to communicate Tomcat

with Apache (or other web servers if that’s the case)


Make sure both connectors are enabled (uncommented). We also recommend turning the parameter enableLookups=False

The following screens show the actual modifications made in server.xml:

a) defining the ‘DesInventar’ application Context:

Note that in this example no drive (in the case of a Windows OS) has been defined. This is possible if all components are installed on Drive C:, which is recommended.

The main issue with Windows systems is that the NT Service that runs Tomcat will run ALWAYS from drive C:, making it the default drive. Locating DesInventar and/or Tomcat in other drives is always possible, but will have consequences and possibly will involve maintaining redundant properties files (folder /etc/properties in more than one drive), which is not recommended.

Unix like environments don’t suffer of these issues.



b) Disabling lookups for the HTTP 1.1 Connector:

Note that the suggested port (8080) can be changed to port 80 if there are no other web servers running on that same machine. That would allow the URLs of the application to run without the :8080 suffix on the URL. Keep in mind that Unix like OS requires root privileges to start an application that takes ports less than 1024.

conf/tomcat-users.xml: this file contains the username and password of the Manager application. Modify the line that contains the roles ‘Manager’ and ‘Admin’, with the appropriate values:

<user username="admin" password="password" roles="admin,manager"/>



The initial value of these elements is defined during the installation, when a window with these values is shown.

After all these modifications are done, Tomcat must be restarted to make them take effect.

In a Windows platform use the Services Panel to restart the server (or stop it and the start it again):

After the service is restarted, Tomcat should be ready to execute the DESINVENTAR application.



In a Unix/Linux/HP-UX environment the startup.sh and shutdown.sh scripts should be used to accomplish the same effect:

cd /usr/local/tomcat/bin./shutdown.sh./startup.sh

In order to test it, open an Internet Explorer in the web server machine. Type http://localhost/ DesInventar (or http://localhost:8081/ DesInventar if you didn’t change the default port) in the address bar, and hit the ‘enter’ key. If everything was properly installed, the screen should look like:


http://localhost:8081/DesInventar

http://localhost/DesInventar


NOTE: Is possible that the list of Regions is empty this first time, due to the lack of database connectivity. See next sections for instructions on how to configure and connect DesInventar to the database.

Appendix A

WINDOWS Installation of the Java2 platform software



Start by downloading the Java 2 Standard Edition JDK (Java Development Kit) from:

http://java.sun.com/j2se/1.3/download.html

Note there are two packages available: the JRE (Java Runtime Environment) and the JDK itself. If you’re planning to install only DesInventar (no interface, or interface running on an existing JSP/Servlet container, you may download the JRE.

If you want to install Tomcat in order to have the web application too, you must download the full JDK, or use the copy of the JDK supplied in the distribution CD.

To install the JDK just follow the instructions of the installer. We recommend installing the JDK in a directory at the root level, with a short name (i.e /jdk1.3), with no embedded spaces.

Double click on the installer to get the setup screen:


http://java.sun.com/j2se/1.3/download.html


The user will have to agree with the terms of license from Sun. Note that the JDK is publicly accessible, and free. Click on Next to get to the License screen.

Click on ‘Yes’ button to get to the Folder specification screen. In this screen you must choose a folder in with setup will install JDK. It suggests a default name, but it is recommended to specify a shorter name, like ‘jdk1.3’. It is also recommended to install all the software components and application in a drive different than C.



Leave the Plug-in screen with the default settings and click on ‘Next’.



The following screen allows the user to define what sub-components should be installed. Please select the ones shown below:

After Setup copies the files, the final screen is shown:



Installation of Tomcat

Tomcat can be downloaded from the Apache web site at:


Or use the download of Tomcat 4.1.18 supplied with the distribution CD.

Configuring and setting up Tomcat requires several steps: deploying the Tomcat software itself, that must be done after installing the full Java 2 development kit (JDK 1.3), defining the environment variables and modifying/editing several configuration files.

The software (Tomcat latest release of v. 4.1.X) is to be downloaded from jakarta.apache.com as a binary distribution and installed in the C drive (to reduce to the maximum problems of drive management, as the application and database will also reside in C:.). We strongly suggest to rename directory Jakarta-tomcat-1.3.1 to tomcat for simplicity.




The DesInventar application distribution CD contains a copy of version 4.1 (against which the application was developed and tested).

Double-click on the installer icon to start the setup process. It will attempt to find a suitable Java Development Kit (JDK), which should have been installed already.

If Tomcat Setup detects successfully a JDK it will pop this screen up:

Click on OK to continue. A License Agreement screen is shown. Click on ‘I Agree’ button to continue.



Installation Options: In this screen the user selects the components to be installed. Please select the ones shown in the screen below. Note that no examples are installed, and the NT Service (not enabled by default) should be selected.

Installation Directory: Please select a short name, without spaces, preferably in drive D. Strongly suggested the name ‘tomcat’, as shown here:



Installer Options: If you plan to run Tomcat as main Web Server you will want to specify port 80. Otherwise is recommended not to modify the default HTTP connection port (8080) options unless another web server or application is already running using that IP port.

Enter the password for the Tomcat administrator. This password can be later modified in the /tomcat/conf/tomcat-users.xml file.

Hit ‘Next’ when ready.



The installer will show the operations being performed until the word ‘Completed’ is shown, after which the button ‘Close’ can be clicked on to finalize the installation.

Immediately after the installation, the environment must be modified (right click on My Computer, properties, advanced, environment variables) adding two new variables, JAVA_HOME and TOMCAT_HOME to point to the installation directories previously mentioned. The PATH environment variable must be modified to include c:\jdk1.3\bin.

Adding the JAVA_HOME: click on the button ‘New’ to get this screen:

After setting the value and hitting ‘OK’, the environment screen will look like:



Adding the TOMCAT_HOME: click on the button ‘New’ to get this screen:

Once JAVA_HOME and TOMCAT_HOME have been set up, select from the ‘System Variables list box the variable PATH, and click on ‘Edit’. Modify the value adding the path to the bin directory of the JDK (C:\jdk1.3\bin). Note paths are separated using semicolons (;):


installation & operations guide - desinventar.net€¦ · web viewinstallation of tomcat 23....

Documents