WebObjects/Web Applications/Deployment/Linux

Overview

(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!

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:

a Linux distribution. For our actual installation of WebObjects 5.2, we used SuSE 8.0 Professional now.
Apache 1.3.x: http://httpd.apache.org (the new version was done with version 1.3.27)
Java2 SDK: http://java.sun.com/j2se/1.4.1/download.html (J2SDK 1.4.1_02, standard RPM package)

I am not sure if installing just the JRE for Linux is enough. It definitely does not work for Windows deployment, so I decided to choose the (somewhat bigger) SDK for Linux, too.

WebObjects 5.1 or 5.2 CD for Solaris / Windows (get it at http://store.apple.com)

a working deployment license key; for WebObjects 5.1 you can use a license key from either a WebObjects 5.0 or 5.1 installation IMPORTANT: For WebObjects 5.2 you need a key specifically made that version! License keys for older versions seem to work at first but later on you cannot run any applications. :-(

WebObjects updates:
- WebObjects 5.1 Update 3 (a compressed tarfile and a shell script) for Solaris: http://docs.info.apple.com/article.html?artnum=75277; the complete patch list lives at http://docs.info.apple.com/article.html?artnum=70037
- There is no update for WebObjects 5.2 yet, so I took the update part out for now.

changes to the makefiles that are discussed in step 6 can be downloaded here, if you do not want to apply them yourself. Inside the zipfile there are different folders for WebObjects 5.1 and 5.2.

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):

a: compat (libs needed to run Java)
ap: mc (Midnight Commander, not _really_ needed :)
d: gcc (compiler)
d: gdbm-devel (libs needed to compile the Apache sources)
d: linclude (needed by gcc)
d: make (make command)
n: ftp (ftp client to get files from other systems, way faster that sftp)
n: openssh (ssh server and client tools, when you want to deploy applications later on)
n: smbclnt (to mount shares from Windows boxes)

Here is what you _do not_ need, un-select this before installing (or uninstall these packages if you already have a running system):

n: apache (you are going to make this yourself).
d: java (JDK 1.1.8)
d: javarunt (Java Runtime 1.1.8)

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

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.

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 similar 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)

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.

Start 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. :-)

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
 cdsfdsfs
 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!

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.

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 successfully, 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!

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.

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.

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 similar to the following:

Your application's URL is:

 http://yourhost.yourdomain.com:56789/

Open this URL in a web browser.

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

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:

Press and hold the left ALT key on the keyboard
Hit the '9' key on the numerical keyblock; 'Numlock' must be on.
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 :-)

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