HOWTO: Running as an OS X StartupItem or via Launchd

Last modified 8/29/2006.

This document describes how you can run CourseForum or ProjectForum under Mac OS X either from a command line, or so that it automatically starts running when your system starts up. This is in contrast to the normal method of running with a user interface, and may make more sense in some environments.

Running from the command line

If you're comfortable with using Terminal, its easy to get CourseForum or ProjectForum running from the command line. The application on OS X is an 'application bundle', which contains a daemon (command line) version. To run it from Terminal, use a command like either:

nohup /Applications/CourseForum.app/Contents/MacOS/courseforum-server &

nohup /Applications/ProjectForum.app/Contents/MacOS/courseforum-server &

When doing this, you need to make sure your working directory is set to the directory where your data files are stored, i.e. "~/Library/Application Support/CourseForum", or "~/Library/Application Support/ProjectForum".

Note: The command line program's name is "courseforum-server" for both CourseForum and ProjectForum.

Running via Launchd

Use launchd (described here) for OS X 10.4 or later.

Starting with OS X 10.4 (Tiger), Apple introduced a system-wide daemon called "launchd", which provides a unified facility for managing automatically run processes. For Unix geeks, think of it as a one-size-fits-all replacement for cron, rc.d, init, and more. There are several good launchd overviews available on the Internet.

To run ProjectForum via launchd, which will ensure it starts up when the machine first boots, and is automatically restarted in case it ever stops, follow these steps. You'll need to perform these steps using 'sudo' from the Terminal.

1. Choose a directory where you'd like ProjectForum's data files to be stored. In the example, we'll use "/usr/local/projectforum".
2. Choose a user you'd like to have the program run under. In the example, we'll use "pfuser", with a group of "pfuser".
3. Create "/usr/local/projectforum".
4. If needed, copy your existing "Group Data" folder to /usr/local/projectforum.
5. Change ownership of all data files with "chown -R pfuser:pfuser Group\ Data".
6. Locate the "courseforum-server" binary in the ProjectForum application, and place it in the directory, e.g. "/bin/cp /Applications/ProjectForum.app/Contents/MacOS/courseforum-server /usr/local/projectforum/".
7. Download the file com.projectforum.pf.plist and place it within "/Library/LaunchDaemons".
8. Make any changes to the file that are needed with a text editor.
9. Start things going with "launchctl load /Library/LaunchDaemons/com.projectforum.pf.plist".

Creating a StartupItem

Use StartupItems (described here) for OS X 10.3 or earlier.

Under versions of OS X previous to Tiger (10.4), StartupItems are used to run programs when the system first starts up. This allows them to be started even without someone logging in to the computer, or to stay running across different users.

Here are the steps needed to create a StartupItem. In this example, we'll do this for ProjectForum, though CourseForum would be similar. We'll be storing the data in the directory /usr/local/projectforum, and we'll be running ProjectForum as the 'root' user (the normal case for programs run as StartupItems).

NOTE: Because StartupItems require special permission, you will need to perform these steps using 'sudo' from the Terminal.

1. Create a directory called "projectforum" in "/usr/local". If needed, copy in your existing "Group Data" folder, and then do "chown -R root:wheel Group\ Data".
2. Create a directory called "ProjectForum" in "/Library/StartupItems". Note that you may need to create the "/Library/StartupItems" directory as well.
3. Create a text file named "ProjectForum" inside "/Library/StartupItems/ProjectForum", containing the following:

   #!/bin/sh
   . /etc/rc.common
   # This script will start up ProjectForum
   ConsoleMessage "Starting ProjectForum"
   export HOME=/usr/local/projectforum
   cd /usr/local/projectforum
   nohup /Applications/ProjectForum.app/Contents/MacOS/courseforum-server -nologo -port 3455 &
        

4. Change the permissions on that file, via "chmod 555 /Library/StartupItems/ProjectForum/ProjectForum".
5. Create the text file "/Library/StartupItems/ProjectForum/StartupParameters.plist" containing the following:

   {
       Description = "ProjectForum";  
       Provides = ("ProjectForum");
       Requires = ("Portmap");
       OrderPreference = "None";
   }
        

6. On restart, ProjectForum should automatically start.
7. If you'd like to start ProjectForum manually (instead of requiring a restart), you can do so via "SystemStarter start ProjectForum".
8. If you'd like to stop ProjectForum manually, you can just kill the process, via "killall courseforum-server".