Start Confluence automatically on OS X using launchd

For long-term use, you should configure Confluence 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 Confluence automatically on Mac OS X when running Tomcat.

On this page:

Using launchd with Tomcat

The Confluence standalone distribution 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 Confluence"
        $CATALINA_HOME/bin/catalina.sh stop
}

date
echo "Starting Confluence"
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 which 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 Confluence start, and then type ctrl-C and see Confluence 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/confluence-2.1.3-std</string>
                <key>JAVA_HOME</key>
                <string>/Library/Java/Home</string>
        </dict>
        <key>Label</key>
        <string>com.atlassian.confluence</string>
        <key>OnDemand</key>
        <false/>
        <key>ProgramArguments</key>
        <array>
                <string>/Users/myname/conf/confluence-2.1.3-std/bin/launchd_wrapper.sh</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
        <key>ServiceDescription</key>
        <string>Confluence</string>
        <key>StandardErrorPath</key>
        <string>/Users/myname/conf/confluence-2.1.3-std/logs/launchd.stderr</string>
        <key>StandardOutPath</key>
        <string>/Users/myname/conf/confluence-2.1.3-std/logs/launchd.stdout</string>
        <key>UserName</key>
        <string>root</string>
</dict>
</plist>

Notes:

1. Replace '/Users/myname/conf/confluence-2.1.3-std' with the path to your Confluence 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 Confluence Manually

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

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

Troubleshooting

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

RELATED TOPICS

Start Confluence automatically on system startup