Serving Java from Linux

Preface

Even with all the press coverage of XML and Java I find it strange why expensive software, such as BEA Web Logic or iPlanet, make the claim that only they can run Java applications.  With a little bit of research, I found out that this was not the case.  However, as usual, the documentation on open-source solutions lacked coherence, at least at first.  Although the scope of this document is a little narrow, I hope the following will help you deploy affordable Java servers.  

Introduction

Like other efforts to put together various open-source platforms, putting together a server that supports JSP and Java Servelets requires that you to visit different web sites, download some tarballs, build some sources, if necessary, even install them somewhere and do lots of hand edits of configurations files to make things run together. This article will not cover those skills, but you will need them to do what we will cover here.

In order to not complicate things any further, I have decided to limit the scope of this discussion to installing the Java 2 Platform on Red Hat Linux 7.1.  Some parts of this document may be sourced from other web sites that I have read and helped me when I was learning.  I will point out all the original sources I can at various points in this document.

I am known for making quite a few silly typos.  If you find any part of this document that does not make sense (or more importantly is just plain wrong!), please e-mail me at: henry@sxpress.com. 

Requirements

I started with a Red Hat Linux 7.1 server installation using only the Web Server module.  Then, I added the RPMs relating to MySQL since a web server running just Java without any database support seems pointless.  For the Java installation, you will need these:

• The Jakarta Project - Specially, you want to download files relating to the  Tomcat subproject.  Get the latest binaries and source codes tarball.  You will need both.  As of this writing, the latest version is 3.2.3

• Java SDK - For the purpose of this document, we want the most current SDK, which happens to be Java 2 SDK, Standard Edition, v 1.3.1.  Get the RPM version to save some time.

• apache-devel RPM - get this from the Red Hat 7.1 CD (Disk 2)

• compat-libstdc++-6.2 RPM - get this from Red Hat 7.1 CD (Disk 2), Java SDK 1.3.1 uses this library instead of the newer library that Red Hat Linux 7.1 installs by default.

Installation

I will assume that you have downloaded the above tarballs/RPMs into your home directory.  From here on, I am going to refer to your home directory as ~$username.  You also need root privilege for most of these steps.  You need to do the Java SDK first because Tomcat requires it.

Java SDK

The file that you have downloaded is not actually the RPM.  Sun makes you go through this legal looking documentation, then the file will extract a RPM for you.  Type this in your home directory:

chmod 755 j2sdk-1_3_1-linux-i386-rpm.bin ./j2sdk-1_3_1-linux-i386-rpm.bin

Now, you have to go through the legal looking documentation.  Once you answer "yes", a RPM file will be created.  Now do this:

su
umask 022
rpm -ivh jdk-1.3.1.i386.rpm
ln -s /usr/java/jdk1.3.1 /usr/java/jdk

That's it.  We now move on to Tomcat.

Tomcat

Some parts of the following I first learned about with the help of Jakarta Project's Tomcat - A Minimalistic User's Guide.   In the following sections you will need to edit some files.  To edit files,  I use vi.  If you hate vi, anytime you see vi, just replace it in your mind with your favorite editor.

vi hint:  hit i for insert, the [ESC] key to end insert, and :x to save and exit.  If you made a mistake, hit [ESC] to stop whatever you are doing and :q! to exit without saving.

The Java SDK RPM installed the Java related files in /usr/java/jdk1.3.1.  So, I decided to put the Tomcat related files in the /usr directory as well.  You are still root, so do this:

cd /usr
tar -xzf ~$username/jakarta-tomcat-3.2.3.tar.gz
ln -s jakarta-tomcat-3.2.3 tomcat

The Tomcat package comes with scripts that will start and stop Tomcat.  We are going to enhance this a little bit.  Create this file by vi /etc/init.d/tomcat:

#!/bin/sh
# Startup script for Tomcat
#

# Source function library.
. /etc/rc.d/init.d/functions

prog="tomcat"
TOMCAT_USER=tomcat

start() {
    echo -n $"Starting $prog: "
    su -l $TOMCAT_USER -c '/usr/tomcat/bin/startup.sh'
    echo
}

stop() {
    echo -n "Stopping $prog: "
    su -l $TOMCAT_USER -c '/usr/tomcat/bin/shutdown.sh'
    echo
}

case "$1" in
    start)
        start
        ;;
    stop)
        stop
        ;;
    restart)
        stop
        start
        ;;
    *)
        echo $"Usage: $0 {start|stop|restart}"
        exit 1
esac

exit 0

This will give us control over Tomcat like other daemons on the server.  Now we have to edit the the startup and shutdown scripts which came with the Tomcat package by vi /usr/tomcat/bin/startup.sh (and shutdown.sh).  Insert these lines before BASEDIR:

TOMCAT_HOME=/usr/tomcat
JAVA_HOME=/usr/java/jdk
CLASSPATH=.:$JAVA_HOME/lib/tools.jar
export TOMCAT_HOME JAVA_HOME CLASSPATH

This will setup the proper environment variables for when we use these scripts.  Also remember to edit the first line so that it reads: #!/bin/sh  The Tomcat package ships with a space between the #! and the /bin/sh. Now, we need to do some miscellaneous things so that the scripts will work:

/usr/sbin/useradd tomcat
chmod 755 /etc/init.d/tomcat
ln -s ../init.d/tomcat /etc/rc3.d/S12tomcat
chmod 755 /usr/tomcat/bin/startup.sh
chmod 755 /usr/tomcat/bin/shutdown.sh
chmod 755 /usr/tomcat/bin/tomcat.sh

I also like to keep the logs and the working files in the /var directory:

mkdir /var/tomcat
mkdir /var/tomcat/logs
mkdir /var/tomcat/work
chown -R tomcat:tomcat /var/tomcat
ln -s /var/tomcat/logs /usr/tomcat/logs
ln -s /var/tomcat/work /usr/tomcat/work

Finally, when Tomcat runs, it automatically creates some files so we need to make sure that the tomcat username can create these files:

chown -R tomcat:tomcat /usr/tomcat/conf
chown -R tomcat:tomcat /usr/tomcat/webapps

Before you start up Tomcat, you need to install the backward compatibility RPM:

cd ~$username
rpm -ivh compat-libstdc++-6.2-2.9.0.14.i386.rpm

Now we are ready to start Tomcat.

/etc/init.d/tomcat start

You should see some messages on the console.  If something is wrong, you will see error messages.  The error messages are usually voluminous; you will not miss them. 

Another way to check to make sure Tomcat is running properly is to do a ps -ef. You will see a lot of Tomcat related processes being run by the tomcat username.

Assuming that you want to use Java to develop applications in the future, it is also more convenient to setup environment variables automatically every time you (and other users) login.  For bash, do this vi /etc/profile and add this section:

# Java/Tomcat Environment
TOMCAT_HOME=/usr/tomcat
JAVA_HOME=/usr/java/jdk
export TOMCAT_HOME JAVA_HOME
PATH="$PATH:/usr/java/jdk/bin"

Mod_jk

Technically speaking, your server can already serve Java pages.  However, according to Tomcat's own documentation, the web server that comes with Tomcat is not very good. Apache is a more robust web server.  So, we are going to use the Apache web server to do all the static pages and use Tomcat only for Java related files.  To accomplish this, we need a module that will pass the processing of Java files from Apache to Tomcat.  This is mod_jk.

We will also take advantage of the fact that Red Hat Linux 7.1 ships with an Apache server to which you can dynamically add modules.  We will make a mod_jk module to plug into the existing Apache server.  First, we get mod_jk from Tomcat's source tarball and we need apxs which is in the apache-devel RPM.  You are still the root user to type:

cd ~$username
rpm -ivh apache-devel-1.3.19-5.i386.rpm
cd /usr
tar -xzf ~$username/jakarta-tomcat-3.2.3-src.tar.gz
cd jakarta-tomcat-3.2.3-src/src/native/apache1.3

Setup the environment variables so that the makefile will work, then run make: (these are for bash, if you are not using bash or sh, these will not work)

TOMCAT_HOME=/usr/tomcat ; export TOMCAT_HOME
JAVA_HOME=/usr/java/jdk ; export JAVA_HOME
cp Makefile.linux Makefile
make

This will create mod_jk.so  Copy this file to Apache's module directory:

cp mod_jk.so /etc/httpd/modules

That's it.  Now, we have to configure the Apache server.

Apache

By default, the Apache server does not run on boot up.  Let's change that first:

mv /etc/rc3.d/K15httpd /etc/rc3.d/S15httpd

Now edit the Apache configuration file by: vi /etc/httpd/conf/httpd.conf  scroll down to just before the### Section 3: Virtual Hosts bit and insert this line:

include /usr/tomcat/conf/mod_jk.conf-auto

This is the path to the configuration file that Tomcat creates automatically every time it is started.  Unfortunately, it puts the modules in the wrong place so we have to fix that:

ln -s ../../usr/lib/apache /etc/httpd/libexec

This is obviously the lazy way.  You can also write your own mod_jk related configuration lines in httpd.conf.  I chose this method only because the automatically generated configuration file does not do anything bad. 

Testing and Configuration

Before we start modifying anything, we should first find out whether what we have done so far actually works.  To test this, start the Apache web server:

/etc/init.d/httpd start

Then, open your browser and point it to http://yourhostname/examples/  The default Apache/Mod_jk/Tomcat setup created this example directory.  You should see links to the jsp and the servelets directories.  Inside these directories, there are test JSP scripts and Java Servelets that you can run to make sure that Tomcat and Apache are actually working together.

The following will test whether you can specify where the Java related files are. 

Create a test JSP script with vi /var/www/html/test.jsp (This script is based on a script in the Tomcat Package.)

<%
String vPath = request.getRequestURI();
String rPath = getServletConfig().getServletContext().getRealPath(vPath);
%>

<html>
<head>
<title>
jsp test
</title>
</head>

<body>
<p>The virtual path is <%=vPath%></p>
<p>The real path is <%=rPath%></p>
</body>
</html>

The Apache web server already knows about /var/www/html through httpd.conf  You have to manually configure Tomcat to do the same.  Insert the following line in the Tomcat configuration file vi /usr/tomcat/conf/server.xml - scroll to the end and insert these lines right before </ContextManager>:

<Host name="yourhostname">
<Context path=""
         docBase="/var/www/html"
         crossContext="false"
         debug="0"
         reloadable="true" >
</Context>
</Host>

Then, restart Tomcat:

/etc/init.d/tomcat restart

To test if this works, point your browser to http://yourhostname/test.jsp  You can also use the above as a template to add Java support to other web sites on this server.  For example, if you use NameVirtualHost have the following in your httpd.conf:

<VirtualHost IPAddress>
    ServerName hostname
    DocumentRoot directoryname
</VirtualHost>

Then, you also need to add Tomcat:

<Host name="hostname">
<Context path=""
         docBase="directoryname"
         crossContext="false"
         debug="0"
         reloadable="true" >
</Context>
</Host>

Since you add new information to the configuration files of both Apache and Tomcat, you will have to restart both.  

Finish

That's it!  You now have a server that is capable of serving JSP and Java Servlets.  I hope you find this document useful.  Although this article is limited to Red Hat Linux 7.1, the majority of the text should be applicable to any other Unix or Linux system. 

Contracting

If all this is too much for you and you just want this to be done and someone else to take care of it, you should consider contracting SurfXpress (and I will be involved) for a dedicated server solution and negotiate a server management contract with us.  We can provide you with a web server solution package that is capable of doing the above and many other things that you may require.

Contribution

Please send corrections, suggestions, complaints, fix any typo, grammatical errors, etc.  to henry@sxpress.com.

Or, you can contribute to my personal sanity by buying some stuff for me from Amazon.

Licensing

Opencontent.org.I have not given this much thought.  I guess this is covered by the OpenContent License, version 1.0. See http://www.opencontent.org/opl.shtml for the full license. Basically, you can copy, redistribute, or modify this document provided that modified versions, if redistributed, are also covered by the OpenContent License.

No Warranty

A lot of legal stuff should go here.  Basically, it will say that this document is provided as is and there is no warranty of any kind...  See the OpenContent License mentioned above.