Joel’s Writings

Having to use 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 StartupItem files; many thanks to Derk Norton for suggesting some of those corrections.
• Saturday, September 4, 2010: replaced instructions about setting up Tomcat as a StartupItem by instructions to set it up as a launchd job; added a section about Tomcat 7.

This tutorial is based on my experience installing Tomcat 6.0.29 on a Mac OS X Snow Leopard 10.6.4 system, and I have not tested those instructions with other versions of the operating system.

Downloading and uncompressing 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:

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:

Then replace its contents by the following:

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

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 unprivileged user as well as its primary group.

Creating an unprivileged 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:

For this tutorial, I will be using the number 107. We can create the group and the user with the following commands:

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

Setting permissions

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

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.

However, I think that a good way to avoid a lot of 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 launchd job

If we want to have Tomcat start up automatically at boot time, or if we simply want to easily start it and stop it without having to think about details like paths and permissions, it’s a good idea to use it as a launchd job.

The first big thing we need to do for that is to create a wrapper script that will start Tomcat and not return until the Tomcat process exits, which is not what the startup.sh and catalina.sh scripts do, as they launch Tomcat as a background process.

To do that, let’s first create a new shell script in Tomcat’s bin directory:

Then put the following content:

/usr/local/tomcat/bin/tomcat-launchd.sh

Then, we need to create a configuration plist file for the Tomcat launchd job:

Then put the following content:

/Library/LaunchDaemons/org.apache.tomcat.plist

Using launchd to manage Tomcat

The first thing we need to do is load this configuration file:

Tomcat should be launching as the user _tomcat, and if you go to http://localhost:8080/ using your favorite browser, you should get to the homepage of your new Tomcat server.

With the above launchd configuration file, Tomcat is pretty much guaranteed to always be running on your system: it will be restarted automatically for you, by launchd, even if it exits for any reason (for example, a crash, or a reboot). The key that controls the fact that Tomcat is launched at boot time is actually the key named RunAtLoad. So, if you don’t like this behavior, you can always set that key to false, and reload the configuration:

You should run those two commands to reload the configuration anytime you make a change to the plist file.

Now, let’s say that you want to just restart the Tomcat server (maybe because you changed some of Tomcat’s configuration files). With the above launchd configuration file, all you have to do is this:

Indeed, you don’t even need to do an equivalent start call, because launchd will take care of relaunching the Tomcat server. That is because we set the key KeepAlive to true. If you prefer to be able to really shut down Tomcat, then you can just change that key to false, reload the launchd configuration, and then, to achieve the same result, you’ll have to run two commands now:

Of course, if you omit the start command, then the server will be permanently shut down (until the next reboot, if you still have the key RunAtLoad set to true).

You can customize the behavior of launchd with regard to Tomcat even further, but I suggest you just check out launchd plists’s man page if you want to learn more about that.

Update for Tomcat 7

Tomcat 7 is around the corner. It’s still considered beta software at the moment (at time of writing, the latest released version of Tomcat is 7.0.2), but it seems to work pretty well. I tried to see if those instructions would work with Tomcat 7, and apparently, they do, except for one thing. The content you need to put in the tomcat-users.xml file is a little different:

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

The difference is that I had to replace the role manager by manager-gui. Tomcat’s migration page explains that difference very well.

Other than that, you should be able to install Tomcat 7 on your Mac using those instructions.

Enjoy!