home / content / kurkowski / integrating tomcat with apache :: 2965 views

Integrating Tomcat 4.0.x with Apache 1.3.x (Unix)

By Stephen Kurkowski, April 16, 2002

With the release of Tomcat 4, The Jakarta Project from The Apache Software Foundation has introduced a new servlet container known as Catalina which implements the Servlet 2.3 and JSP 1.2 specifications from Java Software. Sporting a "completely new architecture" in Catalina, upgrading to Tomcat 4 is slightly more involved than simply moving your applications from one container to another.

In this article I will illustrate the process of integrating Tomcat 4.0.x with Apache 1.3.x under Unix. Although I use Slackware 8.0 to illustrate the integration process on Unix, the steps outlined should work for System V and BSD based systems as well. This article assumes that you have a functioning Apache Web Server installed and it was compiled with DSO support, and a functioning Tomcat 4 installed as well.

The easiest way to begin the integration process under Linux is to download the WebApp connector module from the Jakarta site (there are pre-built modules for Solaris as well). Unfortunately, this module was compiled with GLIBC 2.2 and if your system does not have this version of GLIBC, then you will have to upgrade to it or compile your own module.

Compiling the WebApp Connector Module

To compile the WebApp connector module, you will have to download the Tomcat connectors source and the Apache Portable Runtime (APR) source. If you want the latest and greatest source code, you can check out the WebApp module sources from CVS using the following commands:

    cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login
    (Logging in to anoncvs@cvs.apache.org)
    CVS password: anoncvs
    cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic \
        checkout jakarta-tomcat-connectors/webapp

Once CVS has downloaded the WebApp module sources, you can download the APR sources with the following commands:

    cd ./jakarta-tomcat-connectors/webapp
    cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic \
        checkout apr

Here, we need to unpack the WebApp source and then unpack the APR sources into the newly created jakarta-tomcat-connectors-4.0.x-xx-src/webapp directory. The CVS folks will skip this step, of course. Next, we will create the configure script. Because all the shell scripts come without execute permissions, we need to change their permissions first:

    chmod 775 support/*.sh

Now we're good to go. From the webapp directory, run the configuration build script:

    ./support/buildconf.sh

You have to execute the script from the webapp directory or the build script cannot find the APR sources. You will notice a few new files in the current directory, mainly the configure script. We proceed by executing the configure script thusly:

    ./configure --with-apxs

and then build it:

    make

If "with-apxs" option is not specified, the Apache module will not be built (only the APR and WebApp libraries will be build). In addition, you might have to tell configure were to find the apxs executable:

    ./configure --with-apxs=/path/to/apache/bin/apxs

Deploying and Configuring the WebApp Connector Module

Given that everything went well, you will find the WebApp module in the webapp/apache-1.3 directory. Copy the mod_webapp.so file to your Apache 1.3 libexec directory, and add the following lines to your httpd.conf with the other module directives:

    LoadModule webapp_module libexec/mod_webapp.so
    AddModule mod_webapp.c

To insure that everything worked properly, issue the following:

    /path/to/apache/bin/apachectl configtest

If everything checks out, then we need to edit the httpd.conf file once again to add the WebApp directives which will tell Apache to send our servlet requests to Tomcat. For now, put the following at the bottom of your httpd.conf file (you can move it to a more appropriate location later, if you so desire):

    WebAppConnection conn      warp  localhost:8008
    WebAppDeploy     examples  conn  /examples

Basically, the WebAppConnection directive is as follows:

    WebAppConnection [connection name] [provider] [host:port]

In our example, we are instructing the WebApp module to connect to the servlet container on localhost, which is listening for requests on port 8008. This is the "WarpConnector" port, as specified in the server.xml file in the Tomcat conf directory and should not be confused with the default HTTP port for Tomcat--8080. Since "warp" is currently the only available provider, and "connection name" can be whatever we choose, let's move on to the WebappDeploy directive:

    WebAppDeploy [application name] [connection name] [url path]

Again, according to our example, we first declare a connection name for the "context path" of the default Web Application Deployment Descriptor called "examples", located in the webapps directory. If you are deploying a .war archive, you must specifiy the complete name of the .war archive in order for Tomcat to handle the request (i.e. opencms.war). Next, we provide the name of the previously declared WebAppConnection directive. Lastly, we define a URL handler from where this application can be accessed through HTTP. When accessing your applications through HTTP, a trailing slash after the handler name is required if you do not specify the name of a specific document, relying instead on the default document name (i.e. index.html or index.jsp).

You can define the "WebAppDeploy" directive for the entire server, or you can insert it into a "" tag. In the case of the latter, your application will be accessible only from that virtual host. In this case, of course, you must define a "WebAppDeploy" directive for each virtual host in which you want the application to be deployed, thus creating a new instance of the application for each virtual host.

One last directive is available from the WebApp module. The "WebAppInfo" directive allows you to monitor the status of all configured connections and deployed applications. Add the following to your httpd.conf file:

    WebAppInfo /webapp-info

Then point your favorite browser at the following URL:

    http://server.name:port/webapp-info/

Note: The trailing slash is required. You should see something like this:

Conclusion

Athough migrating from Tomcat 3 to Tomcat 4 requires a little more work than most systems administrators and software developers would like, the added control you gain over deployment makes up for the hastle. Many new open source projects require Tomcat 4 for deployment, so you may end up migrating sooner than later. Whether or not Tomcat 4 will perform as well or better than Tomcat 3 remains to be seen, but if you need all the latest bells and whistles from the Servlet and JSP specifications, welcome to Tomcat 4. For more information, see the Jakarta Tomcat 4 Documents.

Barcelona, España
16 April, 2002