Load Balancing Tomcat on Leopard with mod_jk

I’ve just had to setup a test system that load balances a site running on Tomcat across multiple computers. My test bed is 3 mac minis, one working as the ‘head’ running Apache, and the other two in the ‘farm’ handling the load. It was a less than painless exercise, so I thought I’d write up the instructions.

1. Install Tomcat
Download Tomcat from here.
On each farm machine rename the folder to be Tomcat, then move it to the /Library/ directory.
In Terminal:

cd /Library/Tomcat/bin
rm *.bat
rm *.exe
chmod +x *

(You don’t need .bat or .exe files, but you do need other files to be executable).

Edit the file /Library/Tomcat/conf/tomcat-users.xml so that it reads:

<?xml version='1.0' encoding='utf-8'?>
  <role rolename="manager"/>
  <user username="tomcat" password="s3cret" roles="manager"/>

(Note that the username and password are examples from Tomcat – you should probably change them).

Repeat the above for each farm machine.

2. Deploy your application
Open each of your farm machines in turn from your browser, e.g.


You should see a screen that looks something like this:

Welcome screen for a Tomcat installation

Click Tomcat Manager and enter the username and password you defined above. This should show the Tomcat Web Application Manager screen.

Upload the war file of the application you want to run. Once complete you should see a link on the manager page to your application. Click it and make sure it works OK.

Repeat the above for each farm machine.

3. Install mod_jk
Here’s the tricky bit. Mod_jk is the apache module that handles the load balancing. It’s available here, BUT none of the downloads there will work on Leopard. Apache on Leopard runs as 64 bit, which isn’t an option you can download from the Tomcat site. So you have two options:

  • Download the source code and build your own version. This isn’t too hard if you have the relevant tools already installed – look here for an excellent step-by-step on the changes you need to make to build a 64 bit version.
  • Use MacPorts
  • , which appears to have the facility to create a 64 bit version (I haven’t tested this).

  • Download the 64 bit version of mod_jk 1.2.26 that I created. I may update this as I go along, but no guarantees!

Once you have your mod_jk.so file (if it doesn’t end up with that name, change the name) copy it to the /usr/libexec/apache2/ directory of your head machine. It’s worth changing the ownership and permissions of the file to match the other modules using the commands sudo chown root:wheel mod_jk.so and sudo chmod 755 mod_jk.so.

4. Configure Apache
Edit the file /etc/apache2/httpd.conf and add the following lines:

#Added for Load Balancing
LoadModule jk_module libexec/apache2/mod_jk.so
# Path to workers.properties
JkWorkersFile /etc/apache2/workers.properties 

# Path to jk logs
JkLogFile /your-chosen-location/mod_jk.log

# Jk log level [debug/error/info]
JkLogLevel info

# Jk log format
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "

# JkOptions for forwarding
JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories

# JkRequestLogFormat set the request format
JkRequestLogFormat "%w %V %T"

JkMount /your-application balancer
JkMount /your-application/* balancer
#End Added for Load Balancing

Note that you’ll need to set the location for your log file, and the name of your application. It’s a good idea to create the log file (e.g. use touch mod_jk.log in the directory you want it; this makes sure the file can be created, which would otherwise trip Tomcat up.

Now create a new file worker.properties in /etc/apache2 containing the following:






The worker.maintain setting helps determine how long one farm machine will be used before the load switches to another machine. For testing I used 5 (seconds); the default is 60.

5. Start Apache
Tomcat should still be running on each of the farm servers, so start Apache on your head machine by opening System Preferences…Sharing and checking the ‘Web Sharing’ box (if it was already checked then uncheck and recheck it to restart Apache).

6. Test it out
Browse to http://head/your-application – you should see your application!

This post was based on the excellent work found here