[Warning: This guide needs to be updated. 09.08.2009]

v0.5

Because I’m tired of my peers thinking that the process is difficult, I decided to write a quick guide detailing the process of installing tomcat on rhel5 and configuring mod_jk with apache.

RHEL5 provides tomcat5 via RHN, unless you have access to another secure and maintained repository that provides tomcat, I recommend using RedHat’s package.

To install tomcat:

yum install tomcat5
/etc/init.d/tomcat5 start
chkconfig --levels 345 tomcat5 on

This will install and start the tomcat5 web server on port 8080. The redhat tomcat rpms are nearly identical in implementation to the jpackage rpms. $CATALINA_HOME is still /usr/share/tomcat5. That directory contains symlinks to other places.  So /usr/share/tomcat5/conf is a link to /etc/tomcat5.

To test the installation, I use the tomcats sample webapp which can be acquired and deployed like so:

wget http://tomcat.apache.org/tomcat-5.5-doc/appdev/sample/sample.war
mv sample.war /usr/share/tomcat5/webapps

The cool thing about .war files is the way tomcat interacts with them. Simply moving the sample.war to $CATALINA_HOME/wabapps will deploy the web base application. Tomcat will automatically extract, or explode sample.war to $CATALINA_HOME/wabapps/sample.

You can access the newly deployed application via the tomcat web server.

http://foo.bar:8080/sample/

If you have installed the tomcat5-webapps package, you will notice some other directories populating the webapps directory. There is a special webapp directory called ROOT which represents the root of the tomcat server, which can always be accessed by going to the root of the server.

http://foo.bar:8080/

Unless you plan on running tomcat on port 80, you are going to want apache to hand off, or connect, requests to the tomcat server. This is where mod_jk comes into the picture. mod_jk is an apache module known as a connector.

First, download the correct binary for your architecture and install it:

wget http://archive.apache.org/dist/tomcat/tomcat-connectors/jk/binaries/linux/jk-1.2.23/mod_jk-1.2.23-apache-2.2.x-linux-i686.so

***
For x86_64 change to:

wget http://archive.apache.org/dist/tomcat/tomcat-connectors/jk/binaries/linux/jk-1.2.23/mod_jk-1.2.23-apache-2.2.x-linux-x86_64.so
***

chmod +x mod_jk-1.2.23-apache-2.2.x-linux-i686.so
cp -av mod_jk-1.2.23-apache-2.2.x-linux-i686.so /etc/httpd/modules/mod_jk.so

vim /etc/httpd/conf.d/mod_jk.conf

LoadModule jk_module modules/mod_jk.so

JkWorkersFile /etc/httpd/conf/workers.properties
JkShmFile /var/log/httpd/mod_jk.shm
JkLogFile /var/log/httpd/mod_jk.log
JkLogLevel info


vim /etc/httpd/conf/workers.properties

workers.tomcat_home=/usr/share/tomcat5

workers.java_home=/usr/lib/jvm/java

worker.list=jkworker

worker.jkworker.port=8009
worker.jkworker.host=localhost
worker.jkworker.type=ajp13

Now restart apache:

/etc/init.d/httpd configtest
/etc/init.d/httpd restart

At this point you have everything you need to run jsp pages and servlets with tomcat, while still hanging on to familiar httpd virtual hosting and configuration. If you have not read the tomcat documentation on connectors, then you should at this point.

In order to use mod_jk to connect to a tomcat webapp, we need to mount it via the apache configuration. The JkMount directive takes care of this for us. To demonstrate this run the following:

mkdir /usr/share/tomcat5/webapps/test/

vim /usr/share/tomcat5/webapps/test/index.jsp

Hello, I am a jsp script!

<%
// get client locale
java.util.Locale locale = request.getLocale();

// get Dateformat for client’s locale
java.text.DateFormat dateFormat =
java.text.DateFormat.getDateTimeInstance(
java.text.DateFormat.LONG,
java.text.DateFormat.LONG, locale);

%>

The time is:
<%=dateFormat.format( new java.util.Date() ) %>

Now add the following somewhere in the apache configuration:

JkMount /test/* jkworker

JkMount works similar to the apache alias directive. It can be used in the main configuration or virtualhost context. For testing purposes, you can append the mount line to your mod_jk.conf file.

Restart apache and hit the following:

http://localhost/test/

Tomcat ships with a web based administration webapp and also a manager webapp that can be used to deploy other webapps. To use these features, you need to install them from rhn if they have not already been installaed:

yum install tomcat5-admin-webapps

In order to access these webapps, you need to first authenticate. In tomcat, you can define users and user roles. Users and roles are defined in $CATALINA_HOME/conf/tomcat-users.xml (/etc/tomat5/tomcat-users.xml). The admin webapps require authenticated users to have certain roles before they are granted access. For the admin webapp, a user who has the role ‘admin’ is granted access. For the manager webapp, the user will need the ‘manager’ role.

By default, the admin and manager roles are not created so you must define them and assign a user to them. I typically create an ‘admin’ user and give that user both the admin and manager roles. Open up /etc/tomat5/tomcat-users.xml and edit it to look like this:

<?xml version=’1.0′ encoding=’utf-8′?>
<tomcat-users>
<role rolename=”admin”/>
<role rolename=”tomcat”/>
<role rolename=”manager”/>
<role rolename=”role1″/>
<user username=”admin” password=”SuperSecretPassword” roles=”admin,tomcat,manager”/>
<user username=”tomcat” password=”tomcat” roles=”tomcat”/>
<user username=”both” password=”tomcat” roles=”tomcat,role1″/>
<user username=”role1″ password=”tomcat” roles=”role1″/>
</tomcat-users>

Now you can access both the manager and the admin panel with the admin user. Try this out:

httpd://yourdomain.net:8080/admin
httpd://yourdomain.net:8080/manager

If you don’t want to type the port, you can mount the apps with JkMount /admin/* jkworker or JkMount /manager/* jkworker.

At present, this guide is far from complete. However, I think something like this would have helped me the first time I had to install tomcat on a shared server. Please feel free to post comments and flames.

jrod@blacknode.net