HOW-TO: Setup WebObjects on Linux

(rev 1.5; 2003-03-02, see full revision list)
The latest version of this document can be found at http://www.tetlabors.de/wo/setup_webobjects_on_linux.html.

Legal stuff:
You can do with this how-to whatever you want but do it at your own risk. I WILL TAKE NO RESPONSIBILITIES WHATSOEVER. If you are not an expert in these things, I suggest setting up a new system just for test purposes first and then use your newly gained knowledge on a real world system.

Preface:
This how-to describes how to setup WebObjects deployment for Linux in about two hours - if you know what you are doing. Otherwise, it might take a little bit longer. :-)

It now covers installation of WebObjects 5.2 as well (see revision list at the end of this how-to for changes).

This how-to is based on a German description on how to setup WebObjects under Linux by Timo Buhmann. Translation and reformatting into this HTML document was done by me with suggestions from the WebObjects mailing lists at OmniGroup and an article about Linux and WO by Jonathan Wolf Rentzsch.

I am no guru when it comes to Linux - I have used it for about two days before writing this tutorial. Luckily, there were enough people around here I could ask all kinds of questions when I got stuck. If you see strange things or clumsy stuff in this how-to, please mail me and kindly send along corrections or improvements. Maybe Apple integrates Linux support in the next release of WebObjects so you won't not need this how-to any longer. In the meantime: let's hack!


Overview:

  1. before you start
  2. install Apache
  3. install Java2 SDK 1.4
  4. install WebObjects 5.1 Deployment for Solaris
  5. install WebObjects 5.1 update 3
  6. compile the Apache adaptor for Linux
  7. configure Apache for WebObjects
  8. start Apache und WebObjects services
  9. start JavaMonitor and test the installation
  10. cleaning up
  11. troubleshooting
  12. revision list



1. Before you start

To minimize delays during the process, you might want to put together all the stuff you need _before_ you start. For this how-to the following software was used:

In your Linux installation, the following packages should installed (the letter at the beginning of each line lists the appropriate package series for a SuSE 7.1 installation, this may be different for other Linux distributions):

Here is what you _do not_ need, un-select this before installing (or uninstall these packages if you already have a running system): A good place to look for packages is http://rpmfind.net. Let package dependencies be resolved by the installer automatically and you are on the way...

After Linux installation is complete, create the following folders; we later use them to drop the installation packages in and remove them when we are done:
mkdir -p /opt/install/apache

mkdir -p /opt/install/java

mkdir -p /opt/install/woupdate

[back to Overview]



2. Install Apache

As Apache version 2.x will not work with the WebObjects adaptor, you have to use Apache version 1.3.x.

Important
Around June 20th, 2002, a security hole in Apache became known that allows attackers to execute code on the server or maybe get even root access. As all versions up to 1.3.24 are affected, you should use at least version 1.3.26, which fixes this security hole.

Put the downloaded apache sources (apache_1.3.27.tar.gz) in /opt/install/apache. Then untar:
cd /opt/install/apache

tar xfvz apache_1.3.27.tar.gz

cd apache_1.3.27
Configure, build and install Apache. The gdbm-devel package must be installed for this to work.
./configure --prefix=/usr/local/apache --enable-module=so --enable-module=rewrite --enable-shared=max --enable-rule=SHARED_CORE

make clean; make; make install
Make starting Apache a bit easier:
ln -s /usr/local/apache/bin/apachectl /usr/bin/apachectl
Try if it works:
apachectl start        
Now open http://<your-host> in your browser. If you see the Apache default page, everything is fine.

Important
In its default installation (as explained in this how-to), the system should be considered unsecure and not connected to the Internet without some kind of protection! As I know next to nothing about Linux/Apache security I strongly suggest that you consult some security how-to on how to make you system more secure.

[back to Overview]



3. Install Java2 SDK 1.4

Put the downloaded SDK (j2sdk-1_4_0_01-linux-i586-rpm.bin) to /opt/install/java
cd /opt/install/java

chmod a+x j2sdk-1_4_1_02-linux-i586-rpm.bin

./j2sdk-1_4_1_02-linux-i586-rpm.bin
Read the license agreement and enter yes at the end. The script will then unpack the RPM package, so you can now install it:
rpm -i -vv j2sdk-1_4_1_02-fcs-linux-i386.rpm

ln -s /usr/java/j2sdk1.4.1_02/bin/java /usr/bin/java
To see if it works, try this:
java -version
The output should look similiar to this:
java version "1.4.1_02"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.1_02-b06)
Java HotSpot(TM) Client VM (build 1.4.1_02-b06, mixed mode)
[back to Overview]



4. Install WebObjects 5.1 Deployment for Solaris

Mount the WebObjects 5.1 installation disc:
mount -t iso9660 -o nojoliet -o norock -o map=o /dev/cdrom /cdrom

cd /cdrom

ls
Important:
As the install script is case sensitive, files and folders on the CD have to contain normal and capital letters. If you see everything in /cdrom being displayed in either lowercase or uppercase but nothing mixed, it did not work. :-(
To get around this, you can copy the contents of the CD to a shared folder on a Windows box and read it from there. Provided that the Windows box has the adress 192.168.1.1 and the share name is wocd, you can reach it like this:
mount -t smbfs //192.168.1.1/wocd /cdrom -o username=smb,password=smb
In this example, you will need a user smb with its password set to smb on the Windows box. If you activate the Guest account on Windows (not recommended), you can omit the username/password for the mount command.

S
tart the install script and follow the instructions:
cd /cdrom/Deployment/SOLARIS

./install.sh
For batch setup, you can use the following:
cd /cdrom/Deployment/SOLARIS

./install.sh -license B-111-AAA-111-AAA-111-AAA-111-AAA-111 -adaptorsOnly NO -minimalInstall NO -cgibin /usr/local/apache/cgi-bin -docroot /usr/local/apache/htdocs -woroot /opt/Apple
First, be sure to cd to /cdrom/Deployment/SOLARIS _before_ starting the installation or the license key check may fail. Second, instead of B-111-AAA-111-AAA-111-AAA-111-AAA-111 you should provide your real license key.  :-)

Follow the instructions on the screen and wait for the installation to finish.

In case of an error, try the following:
ln -s /usr/bin/uncompress /usr/bin/compress
Now, create /etc/profile.local if it does not exist yet:
touch /etc/profile.local
To export NEXT_ROOT at each startup, add the following lines to /etc/profile.local:

NEXT_ROOT=/opt/Apple
export NEXT_ROOT


Now you should log off and log in again to make NEXT_ROOT known. You can also export NEXT_ROOT for your current session manually:
export NEXT_ROOT=/opt/Apple
To see if it works, enter this:
echo $NEXT_ROOT
If /opt/Apple is echoed back, everything's fine. :-)

[back to Overview]



5. Install WebObjects 5.1 update 3,

Skip this step for WebObjects 5.2 as there is no update available yet.


Before starting the update, mod_WebObjects has to be unloaded from the web server and all WebObjects related processes have to stop. It should not matter in the case of this how-to since we never used WebObjects so far, but to be on the safe side, enter the following:
apachectl stop

cd $NEXT_ROOT/Library/WebObjects/Executables

./WOServices stop
If you have standalone (EOF/WO) apps running, kill them, too. Furthermore, gnutar has to be available for the patch script. If it is not, you can create a link:
ln -s /bin/tar /bin/gnutar
To install the update, you have to download two files: the update itself (WO51SolarisUpdate3.TAR.Z) and the patch script (patcher.sh). Put these two in /opt/install/woupdate and then start the update:
cd /opt/install/woupdate

chmod a+x patcher.sh

./patcher.sh -install WO51SolarisUpdate3.TAR.Z

cd $NEXT_ROOT/Library/WebObjects/WODocumentRoot

cp -R WebObjects /usr/local/apache/htdocs/WebObjects
Edit $NEXT_ROOT/Library/Frameworks/JavaWebObjects.framework/Resources/WebServerConfig.plist :

line 2: change /Library/WebServer/Documents to /usr/local/apache/htdocs

Now comes the fun part: Compiling the adaptor!

[back to Overview]



6. Compile the Apache adaptor for Linux

As the makefiles do not ship with Linux support - is there any sound reason for this, by the way? - you have to add support yourself. Luckily the adaptor sources come with WebObjects.

All of the previous solutions I found broke the script in some way. For example, it was not possible to run the script on Solaris without further modifications. Here we will do a 'clean' solution that adds support for Linux without breaking it for the other platforms.

First, export the OS variable, so the script knows we are on Linux:
export OS=LINUX
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):

# LINUX
ifeq "LINUX" "$(OS)"
ADAPTORS = CGI Apache
# Default path for apxs
APXS = /usr/local/apache/bin/apxs
endif

Save and exit.

The next part is a bit tricky (for me) because here WebObjects 5.1 and 5.2 differ.

<WEBOBJECTS 5.1>


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 "LINUX" "$(OS)"

# If Apache is in a nonstandard location, change this
APACHEINCLUDEFLAGS = -I/usr/local/apache/include

CFLAGS = -O2 -Wall -I../Adaptor ${LDAPACHESSLFLAG} $(DEBUG_FLAG) -DSINGLE_THREADED_ADAPTOR -D$(OS) -DEAPI -DFORKING_WEBSERVER -DAPACHE ${OPENSSLINCLUDEFLAGS} ${APACHEINCLUDEFLAGS} ${OPENSSLLIBFLAGS} -L/lib
APXSFLAGS = -i
LDFLAGS += -G -L/lib -lc ${OPENSSLLIBFLAGS}

all: adaptor

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

mod_WebObjects.so : mod_WebObjects.o ${COMMON_OBJFILES}
# ${APXS} ${APXSFLAGS} -c mod_WebObjects.c ${COMMON_OBJFILES}
# ${APXS} ${APXSFLAGS} 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
# ${APXS} ${APXSFLAGS} -c mod_WebObjects.c

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!

</WEBOBJECTS 5.1>
 

<WEBOBJECTS 5.2>

Open $NEXT_ROOT/Developer/Examples/WebObjects/Source/Adaptors/Apache/Makefile and cut it around line 29, that means after the ifeq "SOLARIS" "${OS}"  ... endif block, delete all following lines until the end of the file. Then append the lines below to the end of the file so it looks like this:

ifeq "LINUX" "${OS}"
ENABLE_SSL_SUPPORT =
OPENSSL_INCL_FLAGS =
OPENSSL_LIB_FLAGS =
APACHE_INCL_FLAGS = -I/usr/local/apache/include
CFLAGS +=-DEAPI ${APACHE_INCL_FLAGS}
LDFLAGS += -G -L/lib -lc ${OPENSSL_LIB_FLAGS}
endif

CFLAGS += ${OPENSSL_INCL_FLAGS}
APXSFLAGS = -i


all: mod_WebObjects.so

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

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

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

include ../Adaptor/make.postamble

</WEBOBJECTS 5.2>

From here on it is the same again for both versions.

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.

Gratulations, you are almost done!

[back to Overview]



7. Configure Apache for WebObjects

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:
apachectl configtest
If it says "Syntax OK", you are fine. Else, try to find and correct the errors it reports.

[back to Overview]



8. Start Apache und WO Services

Starting Apache is easy:
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]



9. 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]



10. Cleaning up 

Remember those installation folders you created in step 1? Now you can safely delete them unless you want to install again:
rm -rf /opt/install/apache

rm -rf /opt/install/java

rm -rf /opt/install/woupdate
Important:
Be absolutely sure you type the path names in correctly; rm -rf takes no prisoners...

[back to Overview]

 

11. Troubleshooting 

Q: When I try to compile the adaptor sources, I get the following error and compilation stops:
In file included from ../Adaptor/appcfg.c:64:
/usr/include/unistd.h:734: conflicting types for `gethostname'
../Adaptor/appcfg.c:57: previous declaration of `gethostname'
make[1]: *** [appcfg.o] Error 1
make: *** [CGI] Error 2
What does this mean?

A: You have forgotten to export the OS variable. Do export OS=LINUX before compiling.

+ + + + +

Q: When I try to compile the adaptor sources, I get the following error and compilation stops:
Makefile:79: *** missing separator. Stop.
make: *** [Apache] Error 2


A: On the line the error message specifies (79 in this example), add a TAB character at the beginning. Just adding several 'space' characters will not help. TAB characters (ASCII character no. 9) can be entered this way:

1. Press and hold the left ALT key on the keyboard
2. Hit the '9' key on the numerical keyblock; 'Numlock' must be on.
3. Release the ALT key.
+ + + + +

Q: During compilation, a lot of warnings are displayed. Do I have to worry about that?

A: There are two different things displayed:

mod_WebObjects.c:242: warning: `setOption3' defined but not used

You can probably comment out this method when compiling under Linux but I am not sure if you may need this on Solaris or OSX. My goal was to make the sources compatible on every platform.

cc: <filename>.o: linker input file unused since linking not done

Probably linking works different or is not needed on Linux. If you know which line to tweak in the makefile, please send me the changes and I will update the how-to.

+ + + + +

Q: I cannot connect to an application when it is run from the command line, i.e. not via Monitor, what can I do?

A: Just add -WODirectConnectEnabled YES as an argument when starting the application and then connect via http://host:port.

+ + + + +

- no more troubles to shoot so far, waiting for new questions to arise :-)

 [back to Overview]



Revision list

1.5: 2003-03-02
- added support for WebObjects 5.2 installation as well
- updated Apache and Java SDK version numbers and hyperlinks


1.4: 2002-08-01
- cloaked most "mailto:" links to make it more difficult for spammers (should have done this right from the start)

1.3: 2002-06-30
- added two questions to the troubleshooting section
- added a warning for the Apache security hole and updated the how-to for Apache 1.3.26
- added security warning at the end of step 2
- added 'how to create a tab on the keyboard' in the troubleshooting section

1.2: 2002-06-18
- added changes to appcfg.c to avoid a compiler warning

1.1: 2002-06-14
- added some troubleshooting stuff
- updated relevant parts of the how-to to use Update 3 for WebObjects instead of Update 2

1.0: 2002-06-09
- first (working) release

0.9: 2002-06-08
- first release, waiting to pass self-test


(END OF HOW-TO)