HowTo: Install Tomcat on OS X using Apache

Recently I've had to do some SOA development using Java and Tomcat. I've never dipped my toes into Java web service development so it's a new world to me. Compared to ASP.NET it seems very convoluted with many different frameworks and conflicting/incomplete/outdated tutorials. I ended up using Axis2 as the framework but wanting to develop on OS X I had to install a servlet container to host my web services. I also wanted to integrate this into Apache for various reasons. After some research and searching here is a process I came up with to install Tomcat on OS X using Apache.

These instructions are for OS X 10.4 (Tiger) with JDK 1.5 and Tomcat 5.5:

Step 1: Download Tomcat and JK source

You can download Tomcat from this link

In order to integrate Tomcat with Apache you need to use the JK Apache module. I downloaded the source for the module and compiled it. You can download the JK Apache module source from this link

Step 2: Install Apache Tomcat

First unpack apache tomcat (double click the file in the Finder) then move folder to /usr/local (or optionally /Library)

sudo mv apache-tomcat-5.5.20 /usr/local

Next create a symbolic link in /usr/local for tomcat. I do this to make it easier to update tomcat versions later.

sudo ln -s apache-tomcat-5.5.20 tomcat

Step 3: Build and install the JK module for Apache

Unpack JK module (double click the file in the Finder) and then open a Terminal and change to the directory that contains the JK source code native directory. You need to build the module from source code to do this issue these commands:

./configure --with-apxs=/usr/sbin/apxs --enable-EAPI

Note: You need the Xcode Tools installed to do this: You can download the Xcode Tools for Free from Apple

Now change to the apache-1.3 folder and run make:

cd apache-1.3
make -f Makefile.apxs

This will build the mod_jk.so file that Apache will use to load Tomcat. You now need to copy the mod_jk.so to the Apache library directory:

sudo cp mod_jk.so /usr/libexec/httpd
sudo chmod 755 /usr/libexec/httpd/mod_jk.so

Step 4: Configure Apache to load JK module

Now time to update the Apache config file to load mod_jk.so when Apache is started. The Apache config file is located at /etc/httpd/httpd.conf

Add this to the LoadModules section of the file:

LoadModule jk_module          libexec/httpd/mod_jk.so

In the AddModules section add this:

AddModule mod_jk.c

Step 5: Create the tomcat worker config file

Again open a Terminal and change to /usr/local/tomcat/conf and create a worker.properties file:

sudo touch worker.properties

Edit the newly created worker.properties file and add the following:

# Setup for Mac OS X
workers.tomcat_home=/usr/local/tomcat
workers.java_home=/Library/Java/Home
worker.list=workername
ps=/
worker.workername.type=ajp13
worker.workername.host=localhost
worker.workername.port=8009
worker.workername.socket_keepalive=1

Step 6: Configure JK Module

Now let's edit the Apache config file again and configure the JK module.

sudo nano /etc/httpd/httpd.conf

Add the following to the bottom of the httpd.conf file:

# Tomcat configuration
<IfModule mod_jk.c>
    JkMount /servlets-examples/* workername
    JkWorkersFile /usr/local/tomcat/conf/worker.properties
    JkLogFile /var/log/mod_jk.log
    JkLogLevel debug
    <Location /*/WEB-INF/*>
        AllowOverride None
        deny from all
    </Location>
</IfModule>

To make sure there are no errors in your httpd.conf file:

sudo apachectl configtest

If there are errors or warnings it will let you know.

Step 7: Setup Tomcat Environment variables

Edit /etc/bashrc file and add the following:

export JAVA_HOME=/Library/Java/Home
export CATALINA_HOME=/usr/local/tomcat
export PATH="$PATH:$CATALINA_HOME/bin"

To add your new environment variables without rebooting you can source your bashrc file:

source /etc/bashrc

Step 8: Test Tomcat

Okay now we are ready to test that tomcat is installed and working. First we will test that Tomcat will run standalone, which means not through Apache. If it's working in standalone mode then we can move on to testing the JK module that allows Tomcat to work through Apache. First thing we need to start up Tomcat:

/usr/local/tomcat/bin/startup.sh

To test if Tomcat is working go to tomcat webpage in browser.

http://localhost:8080

By default the standalone mode will listen on port 8080. You can shutdown the tomcat server with:

/usr/local/tomcat/bin/shutdown.sh

Now lets test that Tomcat works with Apache. Restart Apache and make sure there are no errors in the /var/log/httpd/errors log.

sudo apachectl restart

To test that tomcat works via mod_jk open a browser to the following URL:

http://localhost/servlets-examples/

Test out a few examples to make sure they execute. If they do then you have successfully configured Tomcat to work with Apache!

Step 9: Enable a Manager in Tomcat

Enable a manager user to access to manager tool by default the Tomcat server restricts access to the manager web application but does not define a user that has manager privileges. We need to alter the tomcat-users.xml configuration file to create a user that has this security role.

sudo nano /usr/local/tomcat/conf/tomcat-users.xml

Then add the following (substitute whatever username and password you want this user to have)

<user username="admin" password="secret" roles="tomcat,manager"/>

Shutdown and restart tomcat and then try and access the manager tool

sudo /usr/local/tomcat/bin/shutdown.sh
sudo /usr/local/tomcat/bin/startup.sh

Then open a browser to the URL:

http://localhost/manager/html

You will be prompted for a username/password. Enter the username and password for the manager user you created above. You should now have access to the management tool where you can Start/Stop/Reload/Deploy Web applications.

Note that in order to use Tomcat you will always need to start it up. There are ways to start it up automatically when OS X boots but that's outside to scope of these instructions.

RogueWolves