Installation of GADS - latest version

This page describes how to install the latest version of GADS from scratch. This document will be updated whenever the installation procedure changes.

Preparing the application server

Install Java

You will need to install a Java Runtime Environment or Development Kit from http://java.sun.com. We are using version 1.4.2_04 but any version above this would be fine (I think version 1.5 is recommended by the latest version of Tomcat). Make sure the Java executables are in your PATH, e.g.:

export JAVA_HOME=/usr/java/j2sdk1.4.2_04/
export PATH=$JAVA_HOME/bin:$PATH

Test this by typing java -version. You should see something like:

java version "1.4.2_04"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_04-b05)
Java HotSpot(TM) Client VM (build 1.4.2_04-b05, mixed mode)

Install Tomcat

Download the latest version of Tomcat (5.5.15 at the time of writing) from http://tomcat.apache.org/. Read the release notes to see if there is anything special to do to install Tomcat on your setup. In our case, (Java 1.4.2 on Red Hat 9.0) we had to do the following:

• Download the Tomcat base (apache-tomcat-5.5.15.tar.gz) and the Java 1.4 compatibility package (apache-tomcat-5.5.15-compat.tar.gz)
• Decide on a place where Tomcat is to be installed. We chose /users/resc/programs. Change to this directory and extract the base and compatibility packages:

cd /users/resc/programs
tar xzf /path/to/apache-tomcat-5.5.15.tar.gz
tar xzf /path/to/apache-tomcat-5.5.15-compat.tar.gz

• Set the environment variable CATALINA_HOME to the directory where Tomcat is installed: setenv CATALINA_HOME /users/resc/programs/apache-tomcat-5.5.15.
• Open $CATALINA_HOME/bin/catalina.sh in a text editor. Just after the initial comment block add the lines:

JAVA_HOME=/usr/java/j2sdk1.4.2_04
JRE_HOME=$JAVA_HOME
JAVA_OPTS="-Xms512M -Xmx512M -Djava.library.path=$CATALINA_HOME/shared/lib/native"
LD_ASSUME_KERNEL=2.4.1

The first two lines set the path to the Java installation. The third line increases the memory available to Tomcat and sets a path for native libraries (we'll need this later). The last line is recommended by the release notes and is there to avoid stability problems on Red Hat 9.

• (Optional: if you want to change the ports on which Tomcat will listen, edit $CATALINA_HOME/conf/server.xml)
• Check that you can run Tomcat by running $CATALINA_HOME/bin/startup.sh. Point your web browser at http://lovejoy.nerc-essc.ac.uk:8080 and check that you get a welcome page. Of course, you will have to change the server if you are not running Tomcat on lovejoy, and you will need to change the port if you have edited server.xml as suggested in the point above.

Install JavaBeans Activation Framework (JAF)

For some reason, Tomcat 5 does not bundle activation.jar (Tomcat 4 did). This is required by Apache Axis. We just copied activation.jar from a former Tomcat installation. You could do this, or download it from http://java.sun.com/products/javabeans/glasgow/jaf.html. In any case, put activation.jar into $CATALINA_HOME/common/lib.

Install Axis (SOAP implementation)

(This is basically following http://ws.apache.org/axis/java/install.html)

• Download the latest version of Apache Axis from http://ws.apache.org/axis/. We are using Axis 1.4, so if you get problems with versions above this, try 1.4.
• Extract the archive somewhere
• In the extracted archive there will be a webapps directory. Copy the axis directory from here into $CATALINA_HOME/webapps
• Move the Log4J library log4j-1.2.8.jar from $CATALINA_HOME/webapps/axis/WEB-INF/lib to $CATALINA_HOME/common/lib. This allows it to be used by the Tomcat framework and all web applications.

Verify the installation

• If Tomcat is already running, stop it and start it again (with $CATALINA_HOME/bin/shutdown.sh and $CATALINA_HOME/bin/startup.sh).
• Point your browser at http://lovejoy.nerc-essc.ac.uk:8080/axis/happyaxis.jsp (again, change the server and port number if necessary). You may see that some optional libraries are missing but as long as the Needed Components are OK, you should be fine.

Obtaining the GADS source code

The latest version of the source code can be checked out from the Subversion repository: svn://lovejoy.nerc-essc.ac.uk/dataservers/gads/trunk. The source code comes with NetBeans project files so it can be loaded straight into NetBeans (version 5). The latest version is 0.16.

Building the GADS libraries

The GADS source code distribution contains an Apache Ant build file build.xml. To build the distribution, install Ant, then type ant jar. Alternatively, in NetBeans, just "Build Project". In either case you should now have two JAR libraries. One is called gads-0.16-core.jar and contains the core GADS classes that are used by other web applications (such as the Google Earth server). The other is called gads-0.16-ws.jar and contains only the Web Service interface classes used by the Axis library.

Installing GADS

The best way to install GADS, unfortunately, is manually.

Setup logging and config files

• Create a directory on the server to hold the configuration and logging files, say /users/resc/webservices/gads-0.16.
• Create a directory called config within this directory and place the users.xml file in here. You might want to copy the users.xml file from a previous version of GADS. In any case, make sure the correct path for the users.xml file is set in the gads.properties file, under the key UsersXMLFileName.
• Create a logs directory within /users/resc/webservices/gads-0.16. Make sure this is set as the destination for log files in log4j.properties.

Copy the files to Tomcat

• Copy the GADS WS interface library gads-0.16-ws.jar to $CATALINA_HOME/webapps/axis/WEB-INF/lib. This library is only visible to Axis services.
• Copy the core GADS library gads-0.16-core.jar to $CATALINA_HOME/shared/lib. This allows it to be used by other web applications.
• Copy all the jar files (not the subdirectories) from the lib/ directory of the GADS source code distribution into $CATALINA_HOME/shared/lib.
• Create a directory $CATALINA_HOME/shared/lib/native. This will hold the native libraries on which GADS relies. Copy the files from lib/linux-native directory of the GADS source code distribution into $CATALINA_HOME/shared/lib/native.
• Copy gads.properties from the config directory of the source distribution into $CATALINA_HOME/shared/classes.
• Copy log4j.properties from the config directory of the source distribution into $CATALINA_HOME/shared/classes.

Deploy GADS

• In the directory on the server that you created for config and logging files, create a subdirectory called deploy (e.g. /users/resc/webservices/gads-0.16/deploy). Copy deploy.wsdd and undeploy.wsdd from the deploy directory of the source distribution into this directory.
• Log in to the server. You can now run the Axis AdminClient on the deploy.wsdd file that you just copied over. You'll need to make sure that the Axis libraries are in your classpath. For example:

setenv AXIS $CATALINA_HOME/webapps/axis/WEB-INF/lib
setenv AXISCLASSPATH $AXIS/axis.jar:$AXIS/axis-ant.jar:$AXIS/commons-discovery-0.2.jar:
   $AXIS/commons-logging-1.0.4.jar:$AXIS/jaxrpc.jar:$AXIS/log4j-1.2.8.jar:
   $AXIS/saaj.jar:$AXIS/wsdl4j-1.5.1.jar
java -cp $AXISCLASSPATH org.apache.axis.client.AdminClient
   -lhttp://lovejoy.nerc-essc.ac.uk:8080/axis/services/AdminService deploy.wsdd

Note that you might have to change the location of the AdminService (the URL after the -l argument)

• You should receive a message saying <Admin>Done processing</Admin>. If you then view the list of deployed services (http://lovejoy.nerc-essc.ac.uk:8080/axis/servlet/AxisServlet) you should see GADS and its methods displayed.

Uninstalling GADS

You can uninstall GADS by firstly undeploying it from the server:

java -cp $AXISCLASSPATH org.apache.axis.client.AdminClient
   -lhttp://lovejoy.nerc-essc.ac.uk:8080/axis/services/AdminService undeploy.wsdd

Then you can remove all the files you copied to the server in the steps above.

-- JonBlower - 24 Jan 2006