How to Install Trac on Mac OS X

Trac is a project management and bug tracking system from Edgewall Software. Trac is free, open source, and popular. However, Trac lacks a good Mac OS X install guide. This article walks through how to install Trac on Mac OS X.

Trac - Integrated Source Code and Project Management

This article assumes you are familiar with Mac OS X’s Terminal.app and issuing commands on the command line.

This article assumes you are using OS X 10.8 or later and have Xcode installed along with the command line tools. Xcode and the command line tools are needed because we will need to build a few items from source code.

Install Trac

Installing Trac itself on OS X 10.8, aka Mountain Lion, is surprisingly easy. Trac and its python dependencies can be installed with a single command:

sudo easy_install Trac

This command installs the latest Trac. Two new binaries are added to your /usr/local/bin/ folder, trac-admin and tracd. A couple of python egg files will have also be added to /Library/Python/2.7/site-packages/.

You are now ready to create a Trac project.

Create a Trac Environment

I am going to create a single Trac instance to oversee all my personal projects.

sudo /usr/local/bin/trac-admin /Users/Shared/projects/trac initenv

This command asks a few questions about your new environment. When asked about the database connection, leave the answer blank; this will default to using the recommended SQLite database for storage:

Project Name [My Project]> Personal Projects
Database connection string [sqlite:db/trac.db]> (leave empty)

With the environment set up, a new folder has been created containing your Trac files.

Test the Trac Environment

You can now serve Trac using the stand alone tracd process. This is not recommended for product sites but is a good test to check your Trac environment has been created properly.

sudo /usr/local/bin/tracd --port 8000 /Users/Shared/projects/trac

Having run this command, point your browser at http://127.0.0.1:8000

If all has gone well, you will see your Trac environment. If you are the only user of this Trac installation, this stand alone server may be enough. You could create a launchd job ticket to manage the server process and stop here.

Trac and Apache httpd

We want to run Trac at speed on a production suitable set up. This means using a web server such as Apache httpd, LiteSpeed, or Nginx.

Mac OS X includes Apache httpd 2 as standard. This makes our choice easy, we will use Apache.

Install mod_fcgid on Mac OS X

Mac OS X comes with Apache httpd 2 but does not include a FastCGI module. We need either the mod_fastcgi or mod_fcgid module to serve Trac.

Both modules can be built for Apache httpd 2 on Mac, but mod_fcgid is actively updated and has a more complete install script.

Work through these commands to download the latest mod_fcgid, build the module, and install it ready for use:

svn checkout http://svn.apache.org/repos/asf/httpd/mod_fcgid/trunk mod_fcgid
cd mod_fcgid
./configure.apxs
sudo ln -s /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/ /Applications/Xcode.app/Contents/Developer/Toolchains/OSX10.8.xctoolchain
make
sudo make install

The soft link, ln -s, above is needed to fix an Apple bug.

mod_fcgid’s install script adds the appropriate LoadModule line to Apache’s httpd 2’s configuration file at /etc/apache2/httpd.conf:

LoadModule fcgid_module libexec/apache2/mod_fcgid.so

Apache httpd needs to be restarted before the new module will be loaded. We will do this once we have finished updating the Apache httpd configuration.

Create the Trac cgi-bin

The web server needs a special CGI compatible script to pass Trac requests to. Trac nicely provides a deploy command to make this step easy:

sudo /usr/local/bin/trac-admin /Users/Shared/projects/trac deploy /usr/local/trac
sudo chmod +x /usr/local/trac/cgi-bin/trac.fcgi

The deploy command has created a folder of web server related content at /usr/local/trac. This is the folder we need Apache httpd to interact with; we extend execute rights to the trac.fcgi file to allow the web server to run the Trac script.

Create the Authentication File

Trac supports users and privileges. We only want specific users to be able to alter settings, create tickets, and interact with our Trac service.

To support users, we create a file containing user credentials. The passwords are digests and can not be recovered. If you forget your password, it can not be retrieved; you will need to create a new password.

The following command creates an htdigest formatted file:

sudo htdigest -c /usr/local/trac/users.htdigest "Trac" firstname.lastname

Add an Administrator

Tell Trac to provide administrator privileges to the user with:

sudo /usr/local/bin/trac-admin /Users/Shared/projects/trac permission add firstname.lastname TRAC_ADMIN

Add Trac Users

To add users, or to change an existing user’s password, run the htdigest command without the create, -c, flag:

sudo htdigest /usr/local/trac/users.htdigest "Trac" firstname.lastname

Configure Apache httpd

Apache httpd needs to be told how to serve Trac. We do this by creating a new file at /usr/local/trac/trac.conf:

sudo touch /usr/local/trac/trac.conf

Use your preferred text editor to add the following contents to this file:

# Minimal mod_fcgid Trac configuration for Apache httpd on Mac OS X
<IfModule mod_fcgid.c>

	<Location "/trac">

		# Authenticate users
		AuthType Digest
		AuthName "Trac"
		AuthUserFile /usr/local/trac/users.htdigest
		Require valid-user

		Order allow,deny
		Allow from all

	</Location>

	ScriptAlias /trac /usr/local/trac/cgi-bin/trac.fcgi/

</IfModule>

The configuration snippet above has been stripped back to a working minimum.

This Apache configuration file snippet needs to be included whenever Apache httpd launches. Do this by appending an Include line to the base of the main Apache httpd configuration file, /etc/apache2/httpd.conf:

Include /usr/local/trac/trac.conf

Start Apache httpd

By default, the Apache httpd server does not automatically launch on Mac OS X. Thankfully, Apple have already provided a suitable launchd job ticket to manage the httpd service. All we need to do is load it with a launchctl command:

sudo launchctl load -w /System/Library/LaunchDaemons/org.apache.httpd.plist

The write, -w, flag ensures any Disabled key is ignored and the launchd job ticket is loaded.

Is all has gone well, you can visit your Apache httpd hosted Trac environment at http://127.0.0.1./trac.

You will need to log-in using the username and password you provided to the htdigest step above.

Dealing with Problems

If you Trac environment does not appear in your browser, what then? By default, Apache httpd appends errors to the following log file, /var/log/apache2/error_log.

There is a good chance the problem will be documented in the error log file.

Set Up Trac

Congratulations, Trac is now running on your Mac. You can now start setting up Trac to match your needs.