Having to work with Tomcat for an important project I am working on, I installed it on my Mac. However, in the beginning, I didn't make much effort: I just uncompressed the official archive in my /usr/local, and I was able to start and stop Tomcat manually, that's all... But today I decided to learn a few things about Mac OS X, trying to install it properly. Let's see what I did!

Updated

• Friday, January 30, 2009: added instructions to create an admin user for Tomcat; corrected and enhanced instructions for permissions; added comments on deploying applications which need access to the filesystem; added link to Lambda Probe; corrected the StartupItems files; many thanks to Derk Norton for suggesting some of those corrections.

This how-to is based on my experience installing Tomcat 6.0.16 on a Mac OS X 10.5.2 system.

Download and uncompress Tomcat

First, download from Tomcat's website the version of Tomcat you want to use. Choose the .tar.gz file in the Core section of the Binary Distributions. Let's say you just downloaded it to your Downloads directory (usually /Users/username/Downloads/). Open a Terminal and execute the following commands:

% cd /usr/local
% sudo tar xvzf ~/Downloads/apache-tomcat-6.0.16.tar.gz
% sudo ln -s apache-tomcat-6.0.16 tomcat

You also need to create an admin user for Tomcat. I will assume you are familiar with vim, but you can use any other text editor. Let's edit the right file:

% sudo vim /usr/local/tomcat/conf/tomcat-users.xml

Then replace its content by the following:

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

Of course, you can replace the word pass by any password you want to use.

Tomcat should already be working, but we should not run it as root, since it may be a huge security issue. That is why we need to first create an unpriviledged user as well as its primary group.

Creating an unpriviledged user

We will be using the command line utility dscl for this. First, you need to choose the User ID and the Group ID, which must be a positive integer, lower than 500, since User IDs above 500 are reserved to normal users. You just have to pick a number between 0 and 500 which is not yet used by any other user or group. Check this out with the commands:

% dscl . -list /Groups PrimaryGroupID
% dscl . -list /Users  UniqueID

For this how-to, I will be using the number 100. We can create the group and the user with the following commands:

% sudo dscl . -create /Groups/_tomcat PrimaryGroupID 100
% sudo dscl . -create /Groups/_tomcat RealName "Tomcat Users"
% sudo dscl . -create /Groups/_tomcat Password \*
% sudo dscl . -create /Users/_tomcat  UniqueID 100
% sudo dscl . -create /Users/_tomcat  PrimaryGroupID 100
% sudo dscl . -create /Users/_tomcat  HomeDirectory /usr/local/tomcat
% sudo dscl . -create /Users/_tomcat  UserShell /usr/bin/false
% sudo dscl . -create /Users/_tomcat  RealName "Tomcat Administrator"
% sudo dscl . -create /Users/_tomcat  Password \*

Choosing /usr/bin/false as the UserShell, and setting the Password to "*" turns this account unusable as a standard user account.

Changing ownership

Since Tomcat will be run as the _tomcat user, you must change the ownership of some directories and files. Just run the following commands:

% cd /usr/local/tomcat
% sudo chown -R root:wheel .
% sudo chmod 644 conf/*
% sudo chown root:_tomcat conf/tomcat-users.xml
% sudo chmod 640 conf/tomcat-users.xml
% sudo mkdir conf/Catalina
% sudo chown _tomcat:_tomcat conf/Catalina
% sudo chown _tomcat:admin logs temp webapps work
% sudo chmod 2770 logs temp webapps work
% cd -

This way, Tomcat should have the right permissions for all the directories it needs to write into, and at the same time, you won't need to use root privileges to read the logs, and so on.

But be careful when developing an application which needs to have access to some directories in the filesystem (for storing files inside the web application for example): you might need to give Tomcat specific permissions on those directories for this to work.

Yet, from now on, the simplest way to avoid Unix permissions headaches is to deploy your web applications only using tools such as the Tomcat Manager, or the excellent Lambda Probe.

Setting Tomcat as a StartupItem

Now, we must create a little startup script which will help us managing Tomcat for tasks such as starting, stoping and restarting. On Mac OS X, we can put such scripts in /Library/StartupItems/. Once more, I will use vim, but you can just use your favorite text editor:

% cd /Library/StartupItems/
% sudo mkdir Tomcat
% cd Tomcat/
% sudo vim Tomcat

Then, you need to copy-paste the following script:

#! /bin/sh
#
# /Library/StartupItems/Tomcat/Tomcat
#
# A script to automatically start up Tomcat on system bootup
# for Mac OS X.

# Suppress the annoying "$1: unbound variable" error when no option
# was given
if [ -z $1 ] ; then
    echo "Usage: $0 [start|stop|restart] "
    exit 1
fi

# Source the common setup functions for startup scripts
test -r /etc/rc.common || exit 1
. /etc/rc.common

# Tomcat's path
CATALINA_HOME=/usr/local/tomcat

StartService () {
    if [ "${TOMCAT}" = "-YES-" ]
    then
        ConsoleMessage "Starting Tomcat Servlet/JSP Server..."
        cd /
        sudo -u _tomcat $CATALINA_HOME/bin/startup.sh
    fi
}

StopService () {
    ConsoleMessage "Stoping Tomcat Servlet/JSP Server... "
    cd /
    sudo -u _tomcat $CATALINA_HOME/bin/shutdown.sh
}

RestartService () {
    ConsoleMessage "Restarting Tomcat Servlet/JSP Server... "
    cd /
    sudo -u _tomcat $CATALINA_HOME/bin/shutdown.sh
    sleep 5
    sudo -u _tomcat $CATALINA_HOME/bin/startup.sh
}

RunService "$1"

Then, you have to make this file executable:

% sudo chmod +x Tomcat

Then, you must create another file:

% sudo vim StartupParameters.plist

with the following content:

{
    Description     = "Tomcat Servlet/JSP Server";
    Provides        = ("Tomcat");
    Requires        = ("Resolver");
    OrderPreference = "None";
    Messages =
    {
        start   = "Starting Tomcat Servlet/JSP Server... ";
        stop    = "Stopping Tomcat Servlet/JSP Server... ";
        restart = "Restarting Tomcat Servlet/JSP Server... ";
    };
}

We now have a startup script, but we still need to say to Mac OS X to launch Tomcat at boot time... You just have to do this:

% sudo sh -c 'echo "TOMCAT=-YES-" >> /etc/hostconfig'

Using the startup script

From now on, each time you boot your system, Mac OS X will launch Tomcat as the user _tomcat. But if you want, you can also manage it manually. For example, to start Tomcat, you can run:

% sudo /Library/StartupItems/Tomcat/Tomcat start

Enjoy!