HOW-TO: Setup the Apache module for WebObjects on AIX and HPUX

The previous version of this document can be found at http://www.tetlabors.de/wo/setup_webobjects_on_linux.html.

Preface:


This how-to is based on a German description on how to setup WebObjects under Linux by Timo Buhmann (timo@six.de). Translation and reformatting into this HTML document was done by Stefan (stefan@tetlabors.de) with suggestions from the WebObjects mailing lists at OmniGroup and an article about Linux and WO by Jonathan Wolf Rentzsch (jon@redshed.net).

Overview:

  1. compile the Apache adaptor for AIX
  2. compile the Apache adaptor for HPUX
  3. configure Apache for WebObjects
  4. start Apache und WebObjects services
  5. start JavaMonitor and test the installation

1. Compile the Apache adaptor for AIX


As the makefiles do not ship with AIX support you have to add support yourself. Luckily the adaptor sources come with WebObjects.

First, we need to ensure that we're using gnumake, not AIX make. GnuMake should respond to make -v with a string like:
GNU Make version 3.79.1, by Richard Stallman and Roland McGrath.

If this is not the case, make sure that the make in the path (which make) points (via a soft link) to gnumake. Next, export the OS variable, so the script knows we are on AIX, using gcc
export OS=AIX
export CC=gcc
We do need this only while compiling, it is not necessary to put it into /etc/profile.local (but you can do this if you want to). Next, open the file $NEXT_ROOT/Developer/Examples/WebObjects/Source/Adaptors/make.config with an editor of your choice and insert (copy and paste) the following lines right before the MacOS X Server entry (around line 17):

# AIX
ifeq "AIX" "$(OS)"
ADAPTORS = CGI Apache
APXS = /usr/HTTPServer/bin/apxs
endif

Save and exit. Then open $NEXT_ROOT/Developer/Examples/WebObjects/Source/Adaptors/Apache/Makefile and copy-and-paste the following lines after the last endif (around line 66):

ifeq "AIX" "$(OS)"

# If Apache is in a nonstandard location, change this as appropriate
APACHEINCLUDEFLAGS = -I/usr/HTTPServer/include

CFLAGS = -O2 -fpic -I../Adaptor ${LDAPACHESSLFLAG} ${DEBUG_FLAG} -DSINGLE_THREADED_ADAPTOR -D$(OS) -DEAPI -DFORKING_WEBSERVER -DAPACHE ${OPENSSLINCLUDEFLAGS} ${APACHEINCLUDEFLAGS} ${OPENSSLLIBFLAGS}
APXSFLAGS = -i
LDFLAGS += -G -L/lib -lc ${OPENSSLLIBFLAGS} -bE:mod_WebObjects.exp -bnoentry -bgcbypass:1 -ldl -bexpall

all: adaptor

adaptor: mod_WebObjects.so
○${APXS} ${APXSFLAGS} mod_WebObjects.so

mod_WebObjects.so: mod_WebObjects.o ${COMMON_OBJFILES}
○ld ${LDFLAGS} mod_WebObjects.o ${COMMON_OBJFILES} -o mod_WebObjects.so

clean:
○rm -rf mod_WebObjects.so mod_WebObjects.o *.o

mod_WebObjects.o: mod_WebObjects.c ${COMMON_OBJFILES}
○${CC} -c ${CFLAGS} mod_WebObjects.c ${COMMON_OBJFILES}

endif

Note: These funny looking circles (like at the beginning of: ○${APXS} ${APXSFLAGS} mod_WebObjects.so) are no typing errors but the TAB (tabulator) key. The make process needs them to complete sucessfully, so do not forget them!

In the Apache directory, create the file mod_WebObjects.exp (this tells the linker what to export from the shared library), with the contents:

#! .
mod_WebObjects

The last file to change is $NEXT_ROOT/Developer/Examples/WebObjects/Source/Adaptors/Adaptor/appcfg.c. Search for the following three lines, starting around line 52:

#ifndef MAXPATHLEN
#define MAXPATHLEN 255
#endif

Cut-and-paste these three lines _after_ the following lines (around line 72), like so:

#include <arpa/inet.h> /* inet_addr() */
#include <sys/param.h>
#endif

#ifndef MAXPATHLEN
#define MAXPATHLEN 255
#endif

After applying these changes, do the following:
cd $NEXT_ROOT/Developer/Examples/WebObjects/Source/Adaptors

make clean; make
During the compilation process, mod_WebObjects.so is automatically placed into /usr/local/apache/libexec, there is no need to do this by hand. If you find mod_WebObjects.so there, compilation was successful. The CGI adaptor has been built, too and can be found at $NEXT_ROOT/Developer/Examples/WebObjects/Source/Adaptors/CGI/WebObjects, if you want to play around with that.

Congratulations, you are almost done! Skip to configure Apache for WebObjects.

[back to Overview]


2. Compile the Apache adaptor for HPUX


As the makefiles do not ship with HPUX support - is there any sound reason for this, by the way? - it was supported under 4.5.1, so why not 5.1? - you have to add support yourself. Luckily the adaptor sources come with WebObjects.

First, export the OS variable, so the script knows we are on Linux:
export OS=HPUX11
export CC=gcc
We do need this only while compiling, it is not necessary to put it into /etc/profile.local (but you can do this if you want to).

Make sure we're using Apache 1.3.27 (not Apache 2). This is available from HP.

Make sure we're using gcc 3.2 (with binutils 2.12). This is available from HP (download the "gcc 3.2 pre-release for 32-bit 11.0 and 11i PA (binary) (depot, http, 51350 KB)" option)

Next, open the file $NEXT_ROOT/Developer/Examples/WebObjects/Source/Adaptors/make.config with an editor of your choice and insert (copy and paste) the following lines right before the MacOS X Server entry (around line 17):

# HPUX
ifeq "HPUX11" "$(OS)"
ADAPTORS = CGI Apache
# change this as appropriate
APXS = /opt/apache/bin/apxs
endif

Save and exit. Then open $NEXT_ROOT/Developer/Examples/WebObjects/Source/Adaptors/Apache/Makefile and copy-and-paste the following lines after the last endif (around line 66):

ifeq "HPUX11" "$(OS)"

# If Apache is in a nonstandard location, change this as appropriate
APACHEINCLUDEFLAGS = -I/opt/apache/include

CFLAGS = -O2 -fPIC -shared -I../Adaptor ${LDAPACHESSLFLAG} $(DEBUG_FLAG) -DDISABLE_SHARED_MEMORY -DSINGLE_THREADED_ADAPTOR -D$(OS) -DEAPI -DFORKING_WEBSERVER -DAPACHE ${OPENSSLINCLUDEFLAGS} ${APACHEINCLUDEFLAGS} ${OPENSSLLIBFLAGS}

APXSFLAGS = -i
LDFLAGS += -b -E ${OPENSSLLIBFLAGS}

all: adaptor

adaptor: mod_WebObjects.so
○${APXS} ${APXSFLAGS} mod_WebObjects.so

mod_WebObjects.so : mod_WebObjects.o ${COMMON_OBJFILES}
○ld ${LDFLAGS} mod_WebObjects.o ${COMMON_OBJFILES} -o mod_WebObjects.so

clean:
○rm -f mod_WebObjects.so mod_WebObjects.o *.o

mod_WebObjects.o: mod_WebObjects.c ${COMMON_OBJFILES}
○${CC} -c ${CFLAGS} mod_WebObjects.c
endif

Note: These funny looking circles (like at the beginning of: ○${APXS} ${APXSFLAGS} mod_WebObjects.so) are no typing errors but the TAB (tabulator) key. The make process needs them to complete sucessfully, so do not forget them!

Change $NEXT_ROOT/Developer/Examples/WebObjects/Source/Adaptors/Adaptor/config.h. Search for the following line, around line 198:
/* other Unix */

and change the definition of APPLE_ROOT and TEMPDIR as appropriate

Change $NEXT_ROOT/Developer/Examples/WebObjects/Source/Adaptors/Adaptor/hostlookup.h. Change line 33 to
#if defined(SOLARIS) || defined(HPUX) || defined(HPUX11)

change line 288 to:
#if defined(HPUX) || defined(HPUX11)

and change line 293 to:
#if (defined(HPUX) || defined(HPUX11)) && defined(NSAPI)

The last file to change is $NEXT_ROOT/Developer/Examples/WebObjects/Source/Adaptors/Adaptor/appcfg.c. Search for the following three lines, starting around line 52:

#ifndef MAXPATHLEN
#define MAXPATHLEN 255
#endif

Cut-and-paste these three lines _after_ the following lines (around line 72), like so:

#include <arpa/inet.h> /* inet_addr() */
#include <sys/param.h>
#endif

#ifndef MAXPATHLEN
#define MAXPATHLEN 255
#endif

After applying these changes, do the following:
cd $NEXT_ROOT/Developer/Examples/WebObjects/Source/Adaptors

make clean; make
During the compilation process, mod_WebObjects.so is automatically placed into /usr/local/apache/libexec, there is no need to do this by hand. If you find mod_WebObjects.so there, compilation was successful. The CGI adaptor has been built, too and can be found at $NEXT_ROOT/Developer/Examples/WebObjects/Source/Adaptors/CGI/WebObjects, if you want to play around with that.

Congratulations, you are almost done! Skip to configure Apache for WebObjects.

[back to Overview]


3. Configure Apache for WebObjects

In all instances in this section, alter the location Apache from /usr/local/apache to whatever is appropriate for your system, e.g. /opt/apache (HPUX), or /usr/HTTPServer (AIX).

Copy the configuration file for WebObjects to the Apache conf folder:
cd $NEXT_ROOT/Developer/Examples/WebObjects/Source/Adaptors/Apache

cp apache.conf /usr/local/apache/conf/webobjects.conf
Edit /usr/local/apache/conf/httpd.conf. Search for the line "LoadModule rewrite_module ..." and insert the following lines right _before_ it:

Include /usr/local/apache/conf/webobjects.conf
<Location /cgi-bin/./>
SetHandler WebObjects
</Location>

Search for the line "AddModule mod_rewrite.c" and put the following line right _after_ that:

AddModule mod_WebObjects.c

Search for a line "ServerName ..." and put your DNS host name in there. If you do not have one, you can use your IP adress, too. The explanation within httpd.conf about this is very good.

ServerName yourhost.yourdomain.com


Now edit /usr/local/apache/conf/webobjects.conf:

line 4: replace SYSTEM_LIBRARY_DIR/WebObjects/Adaptors/Apache/mod_WebObjects.so with /usr/local/apache/libexec/mod_WebObjects.so

line 5: put a # in front of AddModule mod_WebObjects.c to comment it out

line 9: replace LOCAL_LIBRARY_DIR/WebServer/Documents with /usr/local/apache/htdocs

Optionally, you can change the following:

line 13: /cgi-bin/WebObjects (can be changed to /myFunkyAlias/WebObjects)

line 28: http://localhost:1085 10 (can be changed to http://host1:1085,http://host2:1085 10, don't put spaces after the comma sign when adding multiple hosts!)

Save and exit. Now, to see if everything is right, try (assuming /usr/local/apache/bin is in your PATH variable, otherwise cd /usr/local/apache/bin first):
apachectl configtest
If it says "Syntax OK", you are fine. Else, try to find and correct the errors it reports.

[back to Overview]


4. Start Apache und WO Services


Starting Apache is easy (assuming /usr/local/apache/bin is in your PATH variable, otherwise cd /usr/local/apache/bin first):
apachectl start
Start wotaskd:
$NEXT_ROOT/Library/WebObjects/JavaApplications/wotaskd.woa/wotaskd &
When it is still running in the foreground after a while, you can press CTRL+C to get back to the shell; wotaskd then continues running in the background.


[back to Overview]


5. Start JavaMonitor and test the installation


The last step before adding application is starting JavaMonitor and see if it works:
$NEXT_ROOT/Library/WebObjects/JavaApplications/JavaMonitor.woa/JavaMonitor -WOPort 56789

After JavaMonitor is launched, you will see a line similiar to the following:

Your application's URL is:
http://yourhost.yourdomain.com:56789/

Open this URL in a web browser.

[back to Overview]


(END OF HOW-TO)