Setting Crowd to Start Automatically on Mac OS X

For long-term use, you should configure Crowd to restart automatically when the operating system restarts. On Mac OS X, the system startup program called launchd manages long running processes – daemons or services.

Apple provides an introduction to launchd. Below we tell you how to use launchd to start Crowd automatically on Mac OS X when running Tomcat.

On this page:

Using launchd with Tomcat

The Crowd distribution (not EAR-WAR) ships with Tomcat. There is a mismatch between how launchd expects a daemon to behave, and how the default startup scripts for Tomcat operate:

• OS X's launchd expects the process it starts to run forever, but 'catalina.sh start' starts the JVM to run Tomcat and then exits.
• Tomcat provides 'catalina.sh stop' to shut down Tomcat cleanly by connecting to a socket which Tomcat listens on, but launchd stops daemons by sending them a signal that kills the process immediately if no specific handling is included.

You will need a wrapper shell script and properties list to make launchd work with Tomcat.

Step 1. Add a Wrapper Shell Script

Add the following wrapper shell script to $CATALINA_HOME/bin:

#!/bin/bash

function shutdown()
{
        date
        echo "Shutting down Crowd"
        $CATALINA_HOME/bin/catalina.sh stop
}

date
echo "Starting Crowd"
export CATALINA_PID=/tmp/$$

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

. $CATALINA_HOME/bin/catalina.sh start

# Allow any signal that would kill a process to stop Tomcat
trap shutdown HUP INT QUIT ABRT KILL ALRM TERM TSTP

echo "Waiting for `cat $CATALINA_PID`"
wait `cat $CATALINA_PID`

The above shell script starts Tomcat and then waits for the process to complete, so launchd is happy that Tomcat is still running. The script also installs a signal handler, which calls the shutdown() function to cleanly shut down Tomcat when launchd signals the script.

You can try this script manually: Start the script, watch Crowd start, and then type ctrl-C and see Crowd shut down cleanly. (Note that it will not shut down cleanly if Tomcat has not started yet. It takes a few seconds for Tomcat to start listening on the shutdown socket.)

Step 2. Add a launchd Property List

The launchd property list (.plist) tells launchd how to start Tomcat.

Add the following plist file to /Library/LaunchDaemons, which is the location for system-wide services which are not part of base OS X:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>Disabled</key>
        <false/>
        <key>EnvironmentVariables</key>
        <dict>
                <key>CATALINA_HOME</key>
                <string>/Users/myname/conf/crowd-x.x.x</string>
                <key>JAVA_HOME</key>
                <string>/Library/Java/Home</string>
        </dict>
        <key>Label</key>
        <string>com.atlassian.crowd</string>
        <key>OnDemand</key>
        <false/>
        <key>ProgramArguments</key>
        <array>
                <string>/Users/myname/conf/crowd-x.x.x/bin/launchd_wrapper.sh</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
        <key>ServiceDescription</key>
        <string>Crowd</string>
        <key>StandardErrorPath</key>
        <string>/Users/myname/conf/crowd-x.x.x/logs/launchd.stderr</string>
        <key>StandardOutPath</key>
        <string>/Users/myname/conf/crowd-x.x.x/logs/launchd.stdout</string>
        <key>UserName</key>
        <string>root</string>
</dict>
</plist>

Notes:

1. Replace '/Users/myname/conf/crowd-x.x.x' with the path to your Crowd installation. The string occurs four times in the above script.
2. JAVA_HOME is set to use the default JDK. On OS X version 10.4.4, the default JDK is 1.4.2. You will need to change this value if you want to use a different version of Java. For example, if you want to use JDK 1.5, you will need to change JAVA_HOME to /System/Library/Frameworks/JavaVM.framework/Versions/1.5.
3. In the above script, we have specified 'root' as the UserName. If necessary, change the UserName to the user you want Tomcat to run as.

Starting and Stopping Crowd Manually

To start and stop Crowd manually, use the following commands:

• Start:
  cd /Library/LaunchDaemons
sudo launchctl load -w crowd.plist
• Stop:
  cd /Library/LaunchDaemons
sudo launchctl unload -w crowd.plist

Troubleshooting

• Make sure both files launch_wrapper.sh and crowd.plist have the necessary file privileges.
• Check the console logging and log file for any abnormalities.

RELATED TOPICS

Configuring Crowd