Installing the Jetty servlet container

Overview

Some of the data store implementations for XBRLAPI are designed to run within Java servlet containers. Moreover, XBRLAPI itself is suitable for use by Java servlets and so can motivate a need to have an installed Java servlet container.

This page gives terse suggestions for setting up the Tomcat servlet container to host XML database that can act as data stores for XBRLAPI. More details on Tomcat installation and configuration are available from the Tomcat 5.5 documentation.

Obtaining and installing Tomcat

XBRLAPI has been tested with XML databases running from within both Tomcat and Jetty. This document covers Tomcat 5.5.

Install Tomcat in the user's home directory for use by a single user

Note that Tomcat can be installed in other ways, depending on how you want to use it. If you are doing development work, then having Tomcat installed for the user that is doing the development work can make the development process easier, for example, by supporting debugging from within IDEs.

Tomcat 5.5 can be downloaded (get the binary core download) from tomcat.apache.org. The XBRLAPI has been tested with Tomcat 5.5.

Download Tomcat.

Extract the archive file that you downloaded to a folder in the user's home directory, such as (on Linux) /home/username/programs/ to create /home/username/programs/tomcat or some such.

Configure Tomcat for use by the single user

Consider changing the ports specified in the server.xml configuration file to ensure that the ports for the single user version of Tomcat does not collide with the ports being used by other servlet container installations that are also being run.

Set the environment variables for JAVA_HOME and CATALINA_HOME

The environment variable, JAVA_HOME, should be set equal to the root directory of the JAVA SDK installation that you want to use to run Tomcat. For example: /usr/lib/jvm/java-1.5.0-sun.

The environment variable, CATALINA_HOME, should be set equal to the root directory of the Tomcat installation that you want to use. For example: /home/username/programs/tomcat

Testing the installation

Change to the CATALINA_HOME/bin directory and make sure that the permissions of the shell scripts allow them to be executed by the user that will be running Tomcat.

Start Tomcat with startup shell script (.s/startup.sh on *NIX) and stop Tomcat with the stop shell script (./shutdown.sh on *NIX) once the permissions have been set correctly.

Test if Tomcat is running correctly by opening a web browser to the Tomcat home page assuming that 8280 is the port that you specified when you modified the server.xml configuration file.