by Shane Bryzak
Introduction
Welcome to the first of a series of tutorials. Today I'm going to be walking through the steps for setting up Apache HTTPD with JBoss Application Server, using Tomcat's mod_jk connector. The environment I'm using is a vanilla install of Fedora 7 (available from fedoraproject.org), but the steps should be similar for other Linux and unix environments. If you're running Windows, this tutorial probably won't help you much... sorry!.
The first step is to download all the packages you need. At the time of writing, I'm using the following versions of these packages:
- Apache HTTPD - Version 2.2.4
- JBoss AS - Version 4.2.0.GA
- mod_jk (JK) - Version 1.2.23
For Apache HTTPD and the Tomcat Connector, you need to download the source version of these as we're going to compile them ourselves. You can download these using the following links:
There are a couple of other pre-requisites before we get started. First of all, you need to have the development tools installed for whatever environment you're using, as we're going to be compiling some of the software. This includes tools such as gcc, make, etc. Secondly, you need to have Java 1.5 JDK installed - I'm using Sun's JDK Version 1.5.0 Update 12.
Once you have downloaded each of the packages from the above links, you should have something like this:
Installing Apache HTTPD
Let's start by installing Apache. This will probably be the most complex of the three products to install, as there are a lot of configuration options both in compiling it and after installation. First, untar the httpd package:
Then change into the directory that is created:
Next we're going to compile Apache, which actually consist of a couple of steps; first we need to configure it with the options that we wish to use, and then we build it.
For the configuration step, I'm going to use the following options:
- --prefix=/usr/local/apache2 - This option is used to configure where Apache will be installed. \
- --enable-so - This option enables DSO (Dynamic Shared Object) support, which we need to use the Tomcat connector.
- --enable-ssl - This option enables SSL. You don't need this, and can leave it out if you like. However, it's a nice thing to have and I will explain at the end of the tutorial how to set up a self-signed certificate so that you can serve secured content.
So, using the above options we execute configure like this:
If all goes well, you should get no errors. If you encountered errors, then I suggest you check the configuration options again and if they all look ok, then it's Google time (this type of troubleshooting is beyond the scope of this tutorial, sorry!). The next step is to run make, which will compile Apache.
This is the longest step, and may take a couple of minutes to complete.
Once the build is complete, run make install to install Apache into the configured directory:
Testing our installation
Now that we've successfully installed Apache, we can change into the target directory and start it up to make sure installation was successful:
Using a web browser, we can browse to the server and see Apache's default "It works!" message:
Congratulations for getting this far. Next, let's install JBoss AS.
Installing JBoss Application Server
This step is relatively painless and straight-forward, as installing JBoss is pretty much as simple as unzipping a single file. Change into the /usr/local directory (or wherever you want to install it) and unzip the JBoss AS package here:
To make things easier, we'll create a symbolic link for the JBoss directory. 
Next we can start up JBoss. Change into the jboss directory and run bin/run.sh:
After a bunch of other log messages, you'll see a message that JBoss has started successfully: 
Once JBoss has started, we can use a web browser to confirm that it is running by browsing to port 8080: 
To start up JBoss when the system boots up (which is something I highly recommend), follow the instructions in this wiki entry from the JBoss wiki. The next step now that we have both Apache and JBoss installed and running successfully, is to get them talking to each other using the Tomcat Connector.
Installing the Tomcat Connector
This section describes how to install mod_jk, the Tomcat connector that allows requests made to Apache HTTPD to be forwarded through to our JBoss server. We'll start by extracting the Tomcat Connector source:
Once it's extracted, switch into the directory that is created:
Let's see exactly what the connector package contains:
To install the connector, we need to change into the native directory and compile it much the same way as we compiled Apache HTTPD. The --with-apxs options tells the configure script where to find apxs (APache eXtenSion tool), which was created when we installed Apache. Let's change into the native directory now, and run the configure script:
After configure is complete, the next step is to run make to compile the source:
And then finally make install:
We can confirm that the build was successful by checking that the Apache modules directory now contains mod_jk.so:
To actually use the new module, we need to configure Apache to load it. Open the conf/httpd.conf file in your Apache directory with your favourite editor:
Find the section where DSO modules are configured, and insert a new line containing the following LoadModule directive:
LoadModule jk_module modules/mod_jk.so
We also need to configure the options for the JK connector. I usually stick these settings near the end of the file:
JkWorkersFile /usr/local/apache2/conf/workers.properties
JkShmFile /var/log/httpd/mod_jk.shm
JkLogFile /usr/local/apache2/logs/mod_jk.log
JkLogLevel info
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
Let's take a quick look at each of these options:
- JkWorkersFile - This option tells mod_jk where to find workers.properties, which is a configuration file that controls how Apache connects to JBoss AS.
- JkShmFile - The location of the shared memory file.
- JkLogFile - The log file for mod_jk.
- JkLogLevel - Controls how much detail gets logged - possible values are info, error and debug.
- JkLogStampFormat - The timestamp format used in the log file.
Next we'll create our workers.properties. There are lot of configuration options available for this file, but for this example we're going to keep it as simple as possible. For more advanced usage, see the connectors documentation. Using your favourite editor again, create a workers.properties file in your apache2/conf directory:
Type or paste in the following configuration:
worker.list=worker1
worker.worker1.type=ajp13
worker.worker1.host=localhost
worker.worker1.port=8009
This configuration file is about as simple as it gets. It defines one "worker", named worker1, and tells it that it will be connecting to our JBoss server on localhost, port 8009, using the ajp13 (Apache JServ Protocol, version 1.3) protocol. We're not quite done yet. The last step is to edit httpd.conf once again, and create a VirtualHost entry that uses our worker. Add the following lines to the end of the file:
NameVirtualHost *:80
DocumentRoot /www/www.acme.com
ServerName www.acme.com
ErrorLog logs/www.acme.com-error_log
TransferLog logs/www.acme.com-access_log
JkMount /* worker1 allow from all
This configuration instructs Apache to forward all requests made for www.acme.com to our JBoss server. In practice, this configuration would be much stricter about which requests are forwarded to JBoss, as the configuration shown by this example is quite unsecure.
Testing the connector
Once all of the configuration changes have been made, restart Apache.