The WebApp Module for Apache 1.3

Introduction

The WebApp Module for Apache 1.3 (Mod WebApp) is a module for the 1.3.x version of the Apache HTTPd Web Server, which allows the deployment of Servlet Web Applications under Apache.

The module is built on top of the WebApp library, a native library written in C language, which itself is built on top of the APR library (the Apache Portable Runtime) for abstracting from the underlying operating system.

Being APR a part of WebApp does not mean that WebApp requires Apache 2.0, of which APR is a feature, but means that it's built on top of the same solid foundation for OS abstraction.

Compilation

First of all, to compile Mod WebApp, you will need to compile the APR library. The sources for the APR library can be found at http://apr.apache.org/. Do not use the APR version coming with Apache 2.0, but build a new copy from the stand-alone sources.

To compile APR, download its tarball, unpack it, and then issue:

./buildconf
./configure --prefix=[APR pfix dir] --enable-static --disable-shared
make
make install

Calling buildconf will generate the configure script and the initial makefiles from the tarball.

The configure call will start looking thru the definitions of your operating system and create a system dependant make environment. In the fist parameter --prefix=... don't use a shared directory, but use a temporary directory that will be used to install the newly compiled targets for APR. --enable-static will tell to configure to build a static version of the library (which is what we're going to build the WebApp library against), and the --disable-shared option will tell to configure not to generate a target shared library (not needed during the WebApp library build process.

The make and make install will respectively build the APR library and then install it in the directory specified in the --prefix parameter.

We're now ready to build the WebApp library and Mod WebApp, to do so, unpack the sources tarball into a directory and issue:

./buildconf.sh
./configure --with-apr=[APR pfix dir] --with-apxs=[APACHE dir]
make

Again, buildconf will build your OS-specific localized configure script.

The --with-apr=... option will tell to configure where to find the previously built APR library (it must be the parameter you gave to the --prefix=... option when compiling APR), while the --with-apxs=... option will specify where the Apache 1.3 apxs utility could be found for your Apache 1.3 installation.

Issuing make will build the WebApp library and at the end generate a statically linked DSO module for your web server in the apache-1.3 directory. The newly generated file apache-1.3/mod_webapp.so will contain both the required APR and WebApp functions, so that you won't have to deal with moving those library around your system.

Installation

Once successfully generated, siply copy the newly generated apache-1.3/mod_webapp.so file into your modules directory and add the following two lines at the beginning of your httpd.conf file:

LoadModule webapp_module [your modules directory]/mod_webapp.so
AddModule webapp_module

This will instruct your Apache 1.3 web server to load and recognize the newly compiled Mod WebApp.

Configuration

As any other Apache module, Mod WebApp is configured thru some directives specified in your httpd.conf file. These are the directives available in Mod WebApp:

WebAppConnection [connection name] [connection provider] [parameter]

This directive will instruct the module to set up a new connection between the web-server and the servlet container. The connection name is a unique name of the connection (no multiple connections can have the same name). The connection provider is the name of the provider to use to establish the specified connection (see below "Providers"). The parameter is an optional provider specific parameter used to setup the connection (See "Providers" below, again).

WebAppConnection myConnection warp localhost:8008

This will create a new connection called myConnection using the warp provider to contact the servlet container, and specifying that the warp-specific parameter for this connection is localhost:8008 (that tells that a servlet engine running a warp server can be contacted on host localhost on port 8008).

WebAppDeploy [application name] [connection name] [URL path]

This directive will instruct the module deploy a web application under a specified URL path. The application name is the name of the web-application as it resides within the servlet container (usually its WAR name without the .war extension). The conneciton name parameter specifies the name of the connection to use to connect to the servlet container in which the application resides (this must be specified in a WebAppConnection directive). Finally the URL path parameter specifies under which URL path the web application should be deployed.

WebAppDeploy myApplication myConnection /test/

This will deploy an application called myApplication (its name is specified by the servlet container, but it might mean that we have a myApplication.war somewhere accessible in the servlet container path that will be expanded and deployed) and that all requests coming in for http://yourhost/test/... will be forwarded to that web application.

WebAppInfo [URL path]

This directive will instruct the module dump out a status page whenever the specified URL path is accessed. This is exactly like specifying:

WebAppConnection _INFO_ info
WebAppDeploy _INFO_ _INFO_ [URL path]

Providers

Connection providers are several ways in which the web server can connect to the servlet container. Each connection is uniquely identified by its name and the parameter tells to the connection provider how the connection must be set up. These are the currently available connectors:

info

A simple connector for testing purposes not accepting any parameter. Any application deployed under one of its connections will display an informative status page on the current configuration of the library.

warp

The warp provider connects to a servlet container thru a network socket. The parameter for its connections are in the format of host:port where host is the name or IP address of the server where the servlet container is running and the port is the port number to which we must connect to be able to use the warp protocol.