This cookbook describes how GeoNetwork 2.4.1 can be made to work under Tomcat 5.5 (JDK 1.5.0_17) on Windows XP. This document expands on http://trac.osgeo.org/geonetwork/wiki/HowToRunUnderTomcat and assumes that you have been able to successfully install and run GeoNetwork 2.4.1.

The GeoNetwork installer deploys the Jetty Web/servlet engine and McKoi SQL Database DBMS plus 3 Java applications: geonetwork (CSW client/server, and more), geoserver (WMS, WFS, WCS server), and intermap (WMS client). We decided to move the GeoNetwork applications to the Tomcat Web server because our production server is already running Tomcat and because it offers additional functionality (load balancing, etc.) for future growth. In the future, we may also replace McKoi with our existing PostgreSQL DBMS.

You probably want to use a newer version of Tomcat 5.5 and JDK 1.5 (Java Development Kit; Java SE 5) or even upgrade to latest Tomcat 6 and JDK 1.6 (Java SE 6). So far, I have only tested the following setup.

Install JDK

1. Download and Install JDK 1.5 (also called JDK 5.0). The JDK offers multiple programming tools, a Java API, and installs a Java Runtime Environment (JRE) which executes Java. You do not need Java EE (Enterprise Edition). I tend to install JDK to the root of a drive (e.g. C:\jdk1.5.0_17) out of convenience and to avoid any paths with spaces. 
2. Check your Windows Environment Variables and see if the JAVA_HOME system variable has been set to your JDK home (e.g. C:\jdk1.5.0_17). Create it if it is missing. You may also want to append ;%JAVA_HOME%\bin to the Path variable. Be careful not to delete any other paths.

Install Tomcat

1. Download and install Apache Tomcat 5.5. I like to use the "Windows Service Installer" because of convenience and because it also installs a Windows service for Tomcat that allows it run after a reboot even if no one logs in.  Again, I install Tomcat to a drive's root (e.g. C:\Tomcat5527) out of convenience and to avoid spaces in the path.
   1. Point Tomcat to your JDK.
   2. Decide if you want to run Tomcat on port 8080 (Tomcat default) or port 80 (HTTP default - may be already used by an other Web server). See Make Tomcat Work Through Port 80. In a production environment, you may want to put a heavy duty Web server  such as Apache 2 or Window's IIS in front of Tomcat and on port 80. 
2. Check Windows' Environmental Variables and set "CATALINA_HOME" to the Tomcat installation home.
3. If you use the Windows Service Installer to install Tomcat, you may not find the usual Tomcat configuration files but you get a Tomcat Monitor (icon in the system tray). You can open a Tomcat configuration window by right clicking on the system tray icon or from the "Configure Tomcat" link in Windows' Start Menu.
   You want to configure the following on the Java tab:
   1. Increase "Initial Memory pool" to 256 MB.
   2. Increase "Maximum memory pool" to at least 521 MB - I use 1025 MB but I have other Java applications besides GeoNetwork's.
   3. Add -XX:MaxPermSize=256m and -XX:PermSize=128m  to new lines in the "Java Options" text field. These are crucial settings to avoid OutOfMemoryError errors in GeoNetwork and also to make GeoServer work. Search PermGen error for more information.
4. Test Tomcat (e.g. http://localhost:8080)

Install GeoNetwork

Read instructions - NOTE: these instructions may not be entirely valid with this version of GeoNetwork

• http://trac.osgeo.org/geonetwork/wiki/HowToRunUnderTomcat
• http://mimis.simos.googlepages.com/Geonetworksetupsupportingmulti-langu.pdf

There are multiple ways to get and install GeoNetwork:

1. Download the GeoNetwork 2.4 Windows Installer - a Windows executable - and follow instructions.
2. Download the GeoNetwork 2.4 platform independent installer - a Java executable JAR fie - and follow instructions.
3. Compile the latest GeoNetwork build from SVN. You can find some information about it on the GeoNetwork Developer Wiki.

I used the windows installer out of convenience and installed GeoNetwork to the root of a drive (e.g. C:\geonetwork). Once GeonetWork is installed and running, we can configure it for Tomcat.

Configure GeoNetwork for Tomcat

You can run GeoNetwork's geonetwork (CSW client/server, and more), geoserver (WMS, WFS, WCS server), and intermap (WMS client) applications two ways:

1. Leave the application folders in C:\geonetwork\web\ and point Tomcat's context to the application location.
2. Copy the application folders from C:\geonetwork\web\ to C:\Tomcat5527\webapps

The first method requires less configuration changes but for a - perhaps unrelated - problem, I chose the second method.

Tomcat context configuration

Create context files for GeoNetwork apps in Tomcat. docBase specifies the app's  location. 

• C:\Tomcat5527\conf\Catalina\localhost\geoserver.xml

  • <Context ath="/geoserver" docBase="/webapps/geoserver"
    privileged="true" antiResourceLocking="false"
    antiJARLocking="false"> </Context>

• C:\Tomcat5527\conf\Catalina\localhost\geonetwork.xml

  • <Context ath="/geonetwork" docBase="/webapps/geonetwork"
    privileged="true" antiResourceLocking="false"
    antiJARLocking="false"> </Context>

• C:\Tomcat5527\conf\Catalina\localhost\intermap.xml

  • <Context ath="/intermap" docBase="/webapps/intermap"
    privileged="true" antiResourceLocking="false"
    antiJARLocking="false"> </Context>

GeoNetwork path configuration

C:\Tomcat5527\webapps\geonetwork\WEB-INF\config.xml - more geonetwork app configurations:
Check all paths that point to the data directory and make sure they point to the data folder in the GeoNetwork install directory (C:\geonetwork\data).

• Example:

  <uploadDir>../../data/tmp</uploadDir> to <uploadDir>../../geonetwork/data/tmp</uploadDir>

  • The path appears to be relative to the web server's Web-root (C:\Tomcat5527\webapps).
• Example:
  

  <param value="../../data"/> to <param value="c:\\geonetwork\\data" />

  • It looks like an absolute windows path works here. You may have to escape the \ with a \.

C:\Tomcat5527\webapps\geoserver\WEB-INF\web.xml - geoserver app configuration:
Update the path for <param-name>GEOSERVER_DATA_DIR</param-name> to that of the data directory:

• Example:
  

  <param-value>../data/geoserver_data</param-value> to
  <param-value>../geonetwork/data/geoserver_data</param-value>
  or
  <param-value>C:\geonetwork\data\geoserver_data</param-value>
  

  • The path appears to be relative to the servlet engine home (C:\Tomcat5527)

GeoNetwork log path and logging configuration

Use the logs to troubleshoot and learn from the GeoNetwork applications!

C:\Tomcat5527\webapps\geonetwork\WEB-INF\log4j.cfg - geonetwork Log4J logging configuration:

• Update the log path to your liking
  • I kept "log4j.appender.jeeves.file = logs/geonetwork.log"  which puts - in my case - the log file into C:\Tomcat5527\logs

C:\Tomcat5527\webapps\intermap\WEB-INF\log4j.cfg - intermap Log4J logging configuration:

• Update the log path to your liking
  • I kept "log4j.appender.jeeves.file = logs/geonetwork.log"  which puts - in my case - the log file into c:\Tomcat5.5\logs
• Optional, change the log level for debuging. This will have a negative performance effect.
  
  • Change "log4j.logger.jeeves = WARN, jeeves" to "log4j.logger.jeeves = DEBUG, jeeves"

C:\geonetwork\data\geoserver_data\services.xml - geoserver service level configuration:

• It looks like the <logLocation> path works independently of the servlet engine location
• For debugging purpose, edit Log4J option by pointing to other config files at C:\geonetwork\data\geoserver_data\logs
  • Example:
    

    change
    <log4jConfigFile>PRODUCTION_LOGGING.properties</log4jConfigFile>
    to
    <log4jConfigFile>VERBOSE_LOGGING.properties</log4jConfigFile>