Apache Module for WebObjects

This adaptor has been tested on Mac OS X (with Apache version 1.3.14) and Solaris (with Apache version 1.3.9). It was not tested on other Apache 1.3.x versions besides the aforementioned, but it should work. Note that the adaptor is not backward-compatible with Apache 1.2.x versions, because the module API changed from version 1.2 to 1.3.

Building the Adaptor

For convenience, this adaptor is configured to run out of the box on Mac OS X; no further installation or configuration is necessary. Any request with .../cgi-bin/WebObjects/... will be handled by the WebObjects Apache module. The Apache module overrides the use of the WebObjects executable in /Library/WebServer/CGI-Executables, though you can optionally disable the Apache module so that the CGI adaptor handles such requests.

On Mac OS X, recompiling is just a matter of running make in the /Developer/Examples/WebObjects/Source/Adaptors directory.

The Apache WebObjects module has been tested on Solaris, as well. It has not been tested on HP-UX nor Windows NT/2000, but there's no known reason it shouldn't work. The apxs rule in the Makefile works fine on Mac OS X and Solaris, but your experience may be different on other platforms. If your Apache web server can already accept Dynamic Shared Objects (DSOs), you can skip to the instructions for configuring the server to use the prebuilt Apache WebObject module.

General information regarding building Apache and including new DSO modules can be found at The Apache Group and in the documentation included with the web server and source for Apache v.1.3 or later.

Preparing the Apache Web Server to Accept the WebObjects Adaptor on Platforms other than Mac OS X

This guide does not attempt to teach you how to build an Apache web server that can accept Dynamic Shared Objects such as the Apache WebObject adaptor. Please refer to the Apache web site for more details. Usually, you must at least configure the web server in the following manner:

./configure --enable-module=so

Compiling the WebObjects Adaptor as a Dynamic Shared Object (DSO)

  1. Make sure that you've installed the following on your system:
  2. On platforms other than Mac OS X, make sure that you have defined and exported an environment variable called NEXT_ROOT which contains the path to your WebObjects installation (e.g. /opt/Apple).
  3. Make sure that you include the paths to the aforementioned executables in your PATH environment variable, preferably as close to the beginning as possible.
  4. Go to the ${NEXT_ROOT}/Developer/Examples/WebObjects/Source/Adaptors/ directory; on Mac OS X, go to /Developer/Examples/WebObjects/Source/Adaptors/. Amend make.config so that the variable ADAPTORS is only equal to Apache. Run make.
  5. If this succeeds in building mod_WebObjects.so in ${NEXT_ROOT}/Developer/Examples/WebObjects/Source/Adaptors/Apache, you will not have to rebuild the Apache server. Configure the Apache web server.
  6. If this fails to build, you will have to rebuild your Apache web server..

Configuring the Apache Server

Once you have built the adaptor and server, you'll need to configure the web server to handle WebObjects requests. On Mac OS X, the WebObjects installer has already properly set the configuration files, but you may still want to modify their parameters. On other platforms, you'll have to perform the following steps:

  1. Locate the Apache configuration file in the Apache package on your system. Usually it's called httpd.conf. On Mac OS X, this file is located in the /etc/httpd directory. Append these lines to the end of httpd.conf: 
    # Including WebObjects Configs
Include /System/Library/WebObjects/Adaptors/Apache/apache.conf
    This example "Include" line assumes that the apache.conf file supplied by WebObjects resides in the /System/Library/WebObjects/Adaptors/Apache directory (on OS X). For other platforms other than OS X, it should be located in ${NEXT_ROOT}/Library/WebObjects/Adaptors/Apache directory.
  2. Copy the newly compiled mod_WebObjects.so to ${NEXT_ROOT}/Library/WebObjects/Adaptors/Apache (on Mac OS X, /System/Library/WebObjects/Adaptors/Apache). Ensure that the LoadModule command in apache.conf is pointing at the right path. Continuing the example from the previous step: 
    LoadModule WebObjects_module /System/Library/WebObjects/Adaptors/Apache/mod_WebObjects.so
  3. You may also want to configure the parameters located in apache.conf: 
    WebObjectsDocumentRoot  <the document root for the web server> 
WebObjectsAlias         <the URL key>
WebObjectsConfig        <the URI to the configuration file> <interval between re-reading config>
    For example: 
    WebObjectsDocumentRoot /Local/Library/WebServer/Documents
WebObjectsAlias /Apps/WebObjects
WebObjectsConfig webobjects://239.128.14.2:1085 10
    The default alias is /cgi-bin/WebObjects. By default, the adaptor contacts the local instance of wotaskd to retrieve configuration information. Please consult the WebObjects document for more details.

    WebObjects supports three mechanisms for reading an adaptor configuration:

    1. to read from a static URL: 
       
WebObjectsConfig file:///Local/Library/WebObjects/Configuration/WebObjects.xml
WebObjectsConfig http://www.company.com/private/woappconfig.xml
    2. to find applications running on known hosts: 
       
WebObjectsConfig http://woserv1:1085,http://woserv2:1085,http://woserv2:1085 10
    3. to discover hosts using multicast: 
       
WebObjectsConfig webobjects://239.128.14.2:1085 10
    The re-read interval for either the host list or multicast mechanisms is set by specifying the desired re-read interval in seconds at the end of the line.
  4. You may have to add a handler to enable the adaptor to take over requests. To do this, add a <Location> directive to the built web server's httpd.conf file: 
    <Location /cgi-bin/WebObjects*>
SetHandler WebObjects
</Location>

Running the Apache Server

Once you've built and configured the server with the linked adaptor, you should start it and confirm that it's working by moving aside the WebObjects CGI adaptor in the cgi-bin directory and making a few requests. If you still are suspicious that the CGI adaptor may be handling the requests instead of the DSO module, you can check this by turning on the logging feature of the adaptor as follows:

  1. As root, touch /tmp/logWebObjects
  2. Make a request to some WebObjects application to initialize the log file.
  3. From the shell, tail -f /tmp/WebObjects.log
  4. If the Apache web server is configured to use the CGI adaptor, each request is logged with:
    Info: <CGI> new request: /cgi-bin/WebObjects/MyApp
  5. If the Apache web server is configured to use the WebObjects Apache module, each request is logged with:
    Info: <WebObjects Apache Module> new request: /cgi-bin/WebObjects/MyApp