Date: 09/09/2009 - minor updates without fully testing: 07-11-2013

= Running !GeoNetwork under Tomcat =

!GeoNetwork can be run under Tomcat.

There are two web applications (webapps) in !GeoNetwork; you will find
them in the `web` directory of the installation: `geonetwork` and `geoserver`.
For !GeoNetwork to function correctly in Tomcat (or in any servlet
container, for that matter), you must publish at least `geonetwork`;
the following instructions publish both webapps.

 1. Install Tomcat.
 1. Prepare !GeoNetwork. You can either:
   a. Use the installer.
   a. Download and build from source.  See HowToWorkWithGit
      for help with downloading, and HowToCompile for help with
      building.
 1. Copy or link to the webapps.  Either:
   a. From your !GeoNetwork build (or installation), copy all of the
      subdirectories of the `web` directory to the `webapps` directory
      of Tomcat. (So you will have `webapps/geonetwork`,
      etc., in your Tomcat installation.)
   a. In the directory `$CATALINA_HOME/conf/Catalina/localhost`
      of your Tomcat installation, create a configuration file for
      each webapp.  You will have files `geonetwork.xml`,
      and `geoserver.xml`. In the file `geonetwork.xml`
      put the following, adjusting the `docBase` path as necessary:
      {{{
      <Context docBase="/...path_to_GeoNetwork_installation_goes_here.../web/geonetwork"
               privileged="true" antiResourceLocking="false" antiJARLocking="false">
      </Context>
      }}}
      Same story with `geoserver.xml`.
 1. Make sure Tomcat is the owner of the following directories:
   a. `/...path_to_GeoNetwork_installation_goes_here.../web`
   a. `/...path_to_GeoNetwork_installation_goes_here.../data` (If this step or the next one is missing, metadata upload and !GeoServer won't work. As a consequence also the little map in the search box won't be displayed.)
 1. Change the path of the !GeoServer data directory:
   a. In `/...path_to_GeoNetwork_installation_goes_here.../web/geoserver/WEB-INF/web.xml` set the value of the parameter 'GEOSERVER_DATA_DIR' to '/...path_to_GeoNetwork_installation_goes_here.../data/geoserver_data'.
 1. Turn off Tomcat security:
   a. In `/etc/default/tomcatXXX` set 'TOMCATXXX_SECURITY' (XXX = Tomcat version) parameter to 'no'.
 1. Make sure you allocated enough Java heap space:
   a. In `/etc/default/tomcatXXX` set 'JAVA_OPTS="-Xmx768M"' if you get an error like this: java.lang.!OutOfMemoryError: Java heap space 
 1. Edit Tomcat's `server.xml` to set parameters as you wish.
 1. If you can't find your log files, make sure you edit `/...path_to_GeoNetwork_installation_goes_here.../web/geonetwork/WEB-INF/log4j.cfg`:
   a. Change 'log4j.appender.jeeves.file' to '/var/log/tomcatXXX/geonetwork.log' (XXX = Tomcat version) or wherever you want to have your logs.
 1. Start Tomcat.

= Running the Z39.50 server =

You'll encounter problems if you enable the Z39.50 server,
because Tomcat is missing a JAR file that is included
with the Jetty installation bundled with !GeoNetwork.

In short, you'll need this additional step:
 1. From your !GeoNetwork build, locate the file
    `jetty/ext/xercesImpl.jar`, and copy it into
    your Tomcat's `webapps/geonetwork/WEB-INF/lib`.