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:
- Replace '
/Users/myname/conf/crowd-x.x.x' with the path to your Crowd installation. The string occurs four times in the above script. - 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. - In the above script, we have specified '
root' as theUserName. 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.shandcrowd.plisthave the necessary file privileges. - Check the console logging and log file for any abnormalities.