Sunday, September 23, 2012

Run Tomcat as a Start-Up Service Daemon in Mac OS X

Before you begin:

The instructions below are to be followed at your own discretion and at your own risk. It is up to you to execute the commands outlined  in this tutorial and is strongly advised that if you do not understand the implications or repercussions one or more of the following instructions, that you do not proceed.

Note that I am on Mac OS X Snow Leopard (version 10.5.8). If you are on a different version of OS X, please consult the documentation specific to your version prior to following this tutorial.

Some of the lines below require altering sensitive system files and processes. Make sure that you are comfortable altering these files and processes before you proceed and that you understand the consequences.

All the commands below are intended to be executed in a terminal window and it is assumed that you are using the default bash terminal for Mac OS X. If you are using another terminal, it is up to you to adjust the commands to fit your terminal.

Now, let's get started...

If you would like to have Tomcat as a start-up service daemon when your system boots up, follow the steps below. These steps assume Tomcat is installed in /Library/Tomcat/Home on your machine and that you have set the $CATALINA_HOME environment variable to /Library/Tomcat/Home. For more information on installing Tomcat on Mac OS X, see "Build and Install Tomcat 7 FROM Source on Mac OS X".

Mac OS X uses launchd to launch daemons at system start-up. To make use of launchd, we will need to make two files:
  1. Create a file and give execute permissions to it. sudo touch $CATALINA_HOME/bin/
    sudo chmod a+x $CATALINA_HOME/bin/
  2. Add the following code to the file and save it: #!/bin/bash
    # NOTE: this is an OSX launchd wrapper shell script for Tomcat (to be placed in $CATALINA_HOME/bin)

    function shutdown() {
        echo "Shutting down Tomcat"
        $CATALINA_HOME/bin/ stop

    echo "Starting Tomcat"
    export CATALINA_PID=/tmp/$$

    # Uncomment to increase Tomcat's maximum heap allocation
    # export JAVA_OPTS=-Xmx512M $JAVA_OPTS

    . $CATALINA_HOME/bin/ start

    # Allow any signal which would kill a process to stop Tomcat

    echo "Waiting for `cat $CATALINA_PID`"
    wait `cat $CATALINA_PID`
  3. Create a property list file called org.apache.tomcat.plist. sudo touch /Library/LaunchDaemons/org.apache.tomcat.plist
  4. Add the following code to the property list file. As you can see, this file contains properties that will help launchd successfully run the file that we created above. <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "">
    <plist version="1.0">
  5. Now load the property list file into launchd sudo launchctl load /Library/LaunchDaemons/org.apache.tomcat.plist When you run the command above it will start Tomcat if it isn't already running.
  6. If you need to restart Tomcat simply run the following command: sudo $CATALINA_HOME/bin/ This will stop the current running Tomcat process and launchd will start a new one.
    *Note: This is the same command I had you create a stop-tomcat alias for in "Build and Install Tomcat 7 From Source on Mac OS X".
  7. If you need to stop Tomcat for any length of time, or if you need to prevent Tomcat from starting as a system process, simply unregister it from launchd with the following command sudo launchctl unload /Library/LaunchDaemons/org.apache.tomcat.plist
For a great run-down on how launchd works check out this post on Nathan's Blog. You can get into the details by taking a look at the "About Daemons and Services" section on Apple's developer website.

Well, that wraps it up for this tutorial. I appreciate any comments.