This is a step-by-step guide to installing Tomcat 5.0.x onto OS X 1.4.x. Note that this is the Tomcat branch for the 1.4 JDK and not for the 1.5 JDK. I know the latest versions of OS X now have Java 5 as part of the OS but my work is not yet ready to migrate to Java 5 so I’m staying with Tomcat 5.0 for now. The chances are that these instructions with only tiny and obvious alterations will work for Tomcat 5.5 with Java 5 but I’m not making any promises.

These instructions result in a Tomcat install that does things the RightWay(tm) and results in a Tomcat service that does not run as root, starts on boot, can be turned on and off with /etc/hostconfig, runs headless to allow your web apps to use AWT classes and provides you with nice aliases for starting and stopping Tomcat as well as getting at the main log file.

Step 1 – Install the Files

Download and extract the core package in latest stable binary distribution in the 5.0 branch of Tomcat from (currently 5.0.28). Then fire-up a terminal with root privileges (you can get to root with sudo bash) and move the folder you extracted (jakarta-tomcat-5.0.28) to /usr/local/ with mv jakarta-tomcat-5.0.28 /usr/local/. Then, to make things easier in the future when upgrading tomcat and to make things easier in general you should create a simlink called tomcat to the full name of the tomcat folder with ln -s /usr/local/jakarta-tomcat-5.0.28 /usr/local/tomcat.

Step 2 – Set the Needed Environment Variables

Still with your root terminal open /etc/profile with your favorite editor (for me that would be vi). We now need to add two environment variables, JAVA_HOME to tell Tomcat what JVM to use and CATALINA_HOME to tell Tomcat where to find itself. Because we are installing Tomcat 5.0 and not 5.5 we need to make JAVA_HOME point at the 1.4 JDK and not the 1.5 JDK. To set these variables add the following to the bottom of /etc/profile:

#For Tomcat
export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/1.4.2/Home
export CATALINA_HOME=/usr/local/tomcat

Then re-start your terminal for those changes to be noticable. You should now be able to start Tomcat with sudo /usr/local/tomcat/bin/ and stop it with sudo /usr/local/tomcat/bin/

Step 3 – Creat a Tomcat User and Group

You should create the user using the Accounts pane in the System Preferences App. Since this user will never need to log in you should set the password to something very long and very secure and don’t worry if you won’t remember it! The simplest thing is to call the user tomcat. When you create a user a group with the same name is automatically created as well so we don’t have to do that explicitly.

You now need to set this new user and group to own the Tomcat folder with chown -R tomcat:tomcat /usr/local/jakarta-tomcat-5.0.28.

Step 4 – Create a Startup Item

Again, get yourself a root terminal and go to the folder /Library/StartupItems/. Then create a new folder for the Tomcat startup item with mkdir Tomcat and change into that folder with cd Tomcat. Then, with your favorite editor create a file called Tomcat and add the following content to it:


. /etc/rc.common
export JAVA_HOME="/System/Library/Frameworks/JavaVM.framework/Versions/1.4.2/Home"
export CATALINA_HOME="/usr/local/tomcat"
export JAVA_OPTS="-Djava.awt.headless=true"

if [ "${TOMCAT}" = "-YES-" ]; then
  ConsoleMessage "Starting Tomcat"
  su tomcat - /usr/local/tomcat/bin/

Note that this version of the file runs Tomcat in so called Headless mode to allow you to play with cool graphics stuff from within your Servlets etc. For more see Decapitating java.awt!.

Next using your favorite editor again create another file called StartupParameters.plist and add the following content to it:

    Description     = "Tomcat";
    Provides        = ("Tomcat");
    Requires        = ("Resolver");
    OrderPreference = "None";
    Messages =
        start = "Starting Tomcat";
        stop  = "Stopping Tomcat";

Before we leave this folder we need to ensure that all the permissions are right. The Tomcat folder and both files in it should be owned by root:wheel, the folder should have permissions drwxr-xr-x as should the file Tomcat. StartupParameters.plist should have permissions -rw-r--r--.

Next you need to edit /etc/hostconfig to add the line below to the end of the file:


Step 5 – Create a Controller Script

To easily stop and start tomcat running as our non-root user and headless we need a script. Tomcat often gets very grumpy when running as a non-root user if it does not own everything in it’s folders so my script also sets the ownership of the tomcat folders correctly before starting Tomcat. I called this script and put it in /Library/StartupItems/Tomcat/. The script should contain the following:

use strict;

# Tomcat Controler

# Define constants

my $tomcatStartupItem = '/Library/StartupItems/Tomcat/Tomcat';
my $tomcatHome = '/usr/local/tomcat';
my $tomcatUser = 'tomcat';
my $tomcatGroup = 'tomcat';

# Don't edit any lines below here

# first ensure we are root
my $uname = `whoami`;
unless($uname =~ m/root/){
  print "\nERROR - must be run as root. Please use sudo.\n\n";

# then ensure we have one argument and that it is either 'start' or 'stop'
unless(scalar(@ARGV) == 1){
  print "\nERROR - takes 1 argument, either 'start' or 'stop'\n\n";
my $act = $ARGV[0];
unless($act eq 'start' || $act eq 'stop'){
  print "\nERROR - the argument to tomcatctrl must be either 'start' or 'stop'\n\n";

# then chown the web-apps folder to the right user to ensure we don't have any funny business
my $execString = "chown -R $tomcatUser:$tomcatGroup $tomcatHome/webapps";
print "\nEnsuring the tomcat user owns all the files in the webapps folder:\n   $execString";
print `$execString`."\n";

# if we're bringing tomcat up, do so
if($act eq 'start'){
  $execString = "cd /;$tomcatStartupItem start";
  print "\n\nBringing up Tomcat - $execString\n";
  print `$execString`;

# if we're bring tomcat down, do so
if($act eq 'stop'){
  $execString = "$tomcatHome/bin/ stop";
  print "\n\nBringing down Tomcat - $execString\n";
  print `$execString`;

Before this script will work you will have to make it executable with: sudo chmod 755 /Library/StartupItems/Tomcat/

Step 6 – (Optional) Add Aliases

Rather than adding these aliases globally I think it’s better to just put them into your own account so open up a terminal as yourself. Then use your favorite editor to edit ~/.bash_profile and add the following lines to the end:

# Tomcat Aliases
alias tomcatup="sudo /Library/StartupItems/Tomcat/ start"
alias tomcatdown="sudo /Library/StartupItems/Tomcat/ stop"
alias tomcatlog="tail -f /usr/local/tomcat/logs/catalina.out"

And that’s it! You now have a tomcat install that starts on boot, runs as a non-privileges user and can be easily started and stopped.

Note (added 06 July 2006):

Depending on how you extract the tomcat files from the archive you download from their web page you may have to manually edit the permissions of some files in Tomcat’s bin directory. If you get an error saying something like “ not found” then change into the bin directory and set the permissions to 755:

cd /usr/local/tomcat/bin
sudo chmod 755 *.sh

[tags]Tomcat, OS X[/tags]


This post was initially posted to my old blog here . Comments may no longer be posted there and should be posted here but there are still old comments there that people may be interested in.