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.
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.
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
tracd. A couple of python egg files will have also be added to
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
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
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,
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
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,
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
sudo launchctl load -w /System/Library/LaunchDaemons/org.apache.httpd.plist
-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,
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.