Bed's Stuff

Trac is an excellent open source tool that allows you to manage a software project;s development life cycle, incorporating a wiki with issue/bug tracking while integrating with a source control service such as subversion. Months ago I had set up a subversion server which was working great on my iMac. I then wanted to setup a Trac server to go along with it so I could manage all aspects for my projects properly. Here's how I did it.

Installing and setting up Trac

Trac is written in the python scripting language, also requiring a number of other third party libraries. While a compatible version of python comes pre-shipped with OS X 10.6, these prequisite libraries do not. However its extremely easy to install trac along with all its prequisites by using python's great 'easy_install' feature. Simply fire up a command line by launching Terminal.app and run the following command:

sudo easy_install trac

This will download and install everything you need for you without further input, so let it do its thing and when its finished we are ready to create our Trac environment. Because I had previously set up my subversion server under a dedicated OS X user 'svn', I wanted to run trac under the same user. Thus I was going to create my trac environment in the /Users/svn/trac/newproject directory and do so by ensuring it was created with appropriate permissions for the svn user. This can be done by prefixing any command with 'sudo -u svn', which will run the command as the svn user. For steps on setting up a dedicated user for this purpose see my previous subversion howto. Run the following command (after ensuring /Users/svn/trac/ has been created) in the terminal:

sudo -u svn trac-admin /Users/svn/trac/newProject initenv

This will create a whole bunch of directories and files and you can then run the standalone Trac server manually to check that these first steps have worked:

sudo -u svn tracd --port=8000 /Users/svn/trac/newProject

This will make the trac server listen on TCP port 8000, so we can then browse in Safari or the browser of choice to http://127.0.0.1:8000 and see that we have a trac server running. Its not terribly useful yet however, as we still need to create users, assign administrator privileges to somebody and setup our components and milestones. Press control-c in Terminal to kill the currently running server.

Adding Users

Even if you're the only one who will be using your trac environment, its a good idea to set up a proper user for yourself. The easiest way to do this is by using tracd with Apache .htpasswd files. We can create a .htpasswd file using the htpasswd command.

sudo -u svn htpasswd -c /Users/svn/trac/newProject/.htpasswd username

This will then prompt for a password to set for the user. For any additional users we can run htpasswd again, just leaving out the -c switch (which tells it to create a new file):

sudo -u svn htpasswd /Users/svn/trac/newProject/.htpasswd another_username

Now that we have configured users and passwords, we need to tell the trac server to use them when running. We can do this by adding the --basic-auth paramater to tracd when we launch it:

tracd --port=8000 /Users/svn/trac/newProject --basic-auth=newProject,/Users/svn/trac/newProject/.htpasswd,/Users/svn/trac/newProject

Now we can browse to http://127.0.0.1:8000 again and see that this time we get prompted to login first. We can do so, but we still can't administer our project yet. We need to give at least one of our users administrator privileges so they can define our project's components, milestones and such. We can do this using by running the following command (this can be done while our existing tracd is still running, so there's no need to kill it first):

trac-admin /Users/svn/trac/newProject permission add username TRAC_ADMIN

This will give username full administrator privileges to your trac environment. After running the command you can just refresh your browser and see the admin tab appear on the page. For a comprehensive guide to the various privileges you can give to users, see this page. You can now configure all aspects of your project directly from your browser.

Integrating with Subversion

Trac can integrate with your local subversion repository, to configure this we need to edit the trac.ini file for the project. In my case this can be found at /Users/svn/trac/newProject/conf/trac.ini. With your favourite text editor find the line that says

repository_dir =

For me this was line 172 of the file, it will be under the section labeled

[Trac]

Simply put the full path to your svn repository here, so in my case its:

reposistory_dir = /Users/svn/repos

and ensure that the line beneath it reads:

repository_type = svn

Restart tracd and refresh your browser to see that the "Browse Source" tab now lets you do exactly what it claims to do.

Automatic Startup
The final step in our trac server setup is to make the tracd service run automatically at system startup. To do this we can create a launchd service using Lingon. You can grab the latest version from Sourceforge. For more details on using Lingon see this previous article I put together, but for this task we just need to add a new User Daemon. Run Lingon, click the New button and select User Daemons. Fill out the dialog as follows:

Name: org.trac.tracd What: /usr/local/bin/tracd --port=8000 /Users/svn/trac/newProject --basic-auth=newProject,/Users/svn/trac/newProject/.htpasswd,/Users/svn/trac/newProject

and be sure to tick the "Keep it running all the time" and "Run it when it is loaded by the system" checkboxes. Click the save button and restart your Mac. If everything has been done right you should be able to instantly load trac in your web browser. Now you can focus on managing and implementing your project.