Head London

Last week, one of our internal servers developed symptoms of RAM / motherboard failure. The machine was running Debian 3.1 (Sarge) and acted as our main CVS repository, as well as having an install of Gforge 4.5.3 for project management. I really liked Gforge, but some of the other developers found the interface a little monstrous. After a quick meeting, we decided to go for something a little more lightweight to replace it - Trac. I’d been watching this project for a while and had been impressed with how agile and no-nonsense it seemed.

In the end, I had a Debian system running:

• Trac (the latest 0.9.4 release at the time of writing, not the older Debian package)
• Apache2 using FastCGI (specifically libapache2-mod-fcgid)
• Subversion 1.1 (with repositories set to use –fs-type=fsfs, important for reasons which will become clear)
• htpasswd for Trac’s user authentication

One thing I should note at this point - Trac doesn’t really have support for a multiple-project environment yet. Unlike Gforge (or SourceForge if you’re used to that), there is no unified view of multiple projects, their statuses, user tasks from each one sorted by user, etc. There are, however, a whole lot of RSS feeds coming out of it. We’re planning to import those onto our intranet when we get a chance, and that should provide an overall view on a per-user basis. That’s a project for when we get some time though, things are humming here….

You should also note that the setup I’ve detailed below runs on an intranet. It is not meant for use on a public-facing web server. There, now I feel better.

Operating System

Once again, I chose Debian 3.1 (Sarge), the GNU/Linux distro for the discriminating sys-admin. We had an old G4 / 800Mhz tower with a trashed hard drive, so I spent 40 quid and slapped a new 80GB drive into it. Basic install went quickly (compared to, say, the heinous Windows XP), and it was time to install Trac.

Install Apache, Python, and Libraries Using Apt-get

You’ll need to install Subversion for source code management, and a few other packages that take care of things like code colouring in Trac. You also need the Python language and some libraries to interface with Subversion. I just used the versions from Sarge, using apt-get install packagename. The dependencies for Trac were almost all taken straight from the Sarge repositories, namely:

• apache2
• python2.3
• clearsilver-dev (I don’t know if this one is necessary but it’s not hurting anything)
• python2.3-clearsilver
• subversion
• python2.3-subversion
• subversion-tools
• libapache2-mod-fcgid
• libsqlite0
• python2.3-sqlite
• enscript
• docutils
• cvs2svn
• libapache2-mod-fcgid
• python2.3-setuptools
• python-docutils

Obviously I got a lot more dependency packages from the repositories in addition to those listed above, but those are the ones that were actually necessary for me to apt-get. Setting up Apache 2 was a pain-free Debian install. All the other stuff installed without a hitch as well. I didn’t try using the Apache2 WebDAV/Subversion functionality, I’ll leave this for some other time. For convenience, here’s the command that will get what you need from the Debian repositories:

apt-get install apache2 python2.3 clearsilver-dev python2.3-clearsilver subversion python2.3-subversion subversion-tools libapache2-mod-fcgid libsqlite0 python2.3-sqlite enscript docutils cvs2svn libapache2-mod-fcgid python2.3-setuptools python-docutils

Install Trac 0.9.4

Now, Sarge is pretty fantastic, but web packages do tend to go out of date quickly, so I just downloaded the Trac 0.9.4 zip file and installed that. The initial install was extremely easy - I stuck the extracted zip file in /opt/trac, ran python ./setup.py install, and Trac was installed. From there, things got a little more complex, and although it was all fairly simple I did encounter a few troubles. So now I’ve got some tips about doing multiple Trac project installs (about 30 of them to be precise).

Set Up A Subversion Repository

At this point, you’ll be needing to set up a Subversion (or “SVN”) repository, as you can’t make a Trac project without a valid repository to store your source code in.

To add a repository manually, do:

svnadmin create /var/svn/repository --fs-type fsfs

Note: all commands in this guide are issued as the root user unless otherwise noted.

If you’ve already got repositories stored in CVS, you can convert a repository from CVS to SVN:

cvs2svn --fs-type=fsfs -s /path/to/new/svn/repo /path/to/cvs/repo

In the case of our intranet server, the subversion repos are at /var/svn/reponame. Note that I’ve used the flag --fs-type fsfs - this tells Subversion that you want to create the repository and store the repository database in the FSFS filesystem. Although it’s only available on Subversion 1.1 and newer, using FSFS is recommended (by me, anyway) because the default Berkeley DB filesystem has some nasty locking problems when svnserve is used in conjunction with Apache. See here and here for more details.

SVN Repository Permissions and Authentication

After running svnadmin create or cvs2svn, you’ve got a working SVN repository and could theoretically login to it. However, you should set some permissions and change the ownership so the repo can be read by Trac. There could be a lot of different ways of doing this, but I added a user called “svnowner”:

adduser svnowner

You also need to add the www-data user (the web server user in Debian) to the svnowner group:

usermod -Gsvnowner www-data

All repositories should be

chown -R svnowner /var/svn/repositoryname
chgrp -R svnowner /var/svn/repositoryname

In addition, it is necessary to ensure that the “svnowner” group has write permissions on the new Subversion repository. In order to ensure this, run

chmod 775 -R /var/svn/repositoryname

This is so that the www-data user (i.e. the Apache webserver) can read and write to the repos, which is necessary for Trac to work.

Setup Subversion Users

After adding a (new or converted) svn repository, it’s necessary to ensure that users can be added to it and that they have proper commit rights on the files. This sorta sucks: passwords can be added to the file /var/svn/reponame/svnserve.conf (if there’s some reason to have specific passwords and permissions for a particular project) or the password directive in svnserve.conf can just point to the file kept at /etc/subversion/users.list. I chose the latter option, and created a file at /etc/subversion/users.list. It contains simple list of users, having the form:

[users]
dave = davespassword
stu = stuspassword
steve = stevespassword
joey = joeyspassword

This step only needs to be done once, the settings shouldn’t have to be changed unless you want to add a new user.

Set Repository User Access Permissions

Lastly, it’s is also necessary to ensure that the following is uncommented (or simply pasted into the bottom of) the svnserve.conf file for a given repository:

[general]
password-db = /etc/subversion/users.list
realm = intranet

As an example, in the case of the Withers Recruitment site, this file is found at /var/svn/withersrecruit/conf/svnserve.conf. For any repository, it can be found at /var/svn/repositoryname/conf/svnserve.conf.

Once again, to be clear, password-db=/etc/subversion/users.list is just something I made up. It could be changed to whatever file the users are kept in for this repo, and could be different for any repo if you wanted special access permissions for this repository. Same goes for the realm = intranet.

If you’re interested in reading more on the thrilling subject of SVN repository access permissions, check out the docs.

Initialize Your First Trac Project

If you are frightened of the command line, some bad news: there is currently no support in Trac for initializing a project any other way than using the command-line. There are various people looking at multi-project support, which would presumably include project creation. Keep in mind, though, that once a project is set up, Trac is an amazingly easy system to use.

Alright, so let’s create a project. On our intranet, we’re keeping all of our Trac stuff at http://intranet/trac/projectname. Your setup may be different. So, to start a new Trac project, I issue the following command as root:

trac-admin /var/www/trac/projectname initenv

A script will fire up and ask you a bunch of questions about the project:

Project Name: enter a project name here

Database Connection String: just hit enter and accept the default. (This will use an SQLite embedded database. I’ve decided to do it this way because Trac can’t share a single Postgresql database across multiple projects, and it seems like a pain to have to make a new PostgreSQL database everytime I want to add one. On the upside, backups should be pretty simple.

Path to repository: enter the path to the Subversion repository, i.e. /var/svn/. If there isn’t a Subversion repository set up for the project yet, you’ll need to set one up. But of course you’ve been following along so far and there’s one already waiting.

Templates directory: hit enter and accept the default unless you feel like hacking up a new set of templates.

Congratulations! At this point, you should be able to issue the command

tracd --port 8000 /var/www/trac/projectname

and view your new Trac project at http://localhost:8000

If you wanted to, you could stop here. You could even uninstall Apache 2 if you wanted - in this mode, Trac is running from its own internal webserver. However, I wanted the benefits of Apache authentication, and the extra speed of FastCGI, so I kept on going. You can stop the tracd server by hitting ctrl-c on your keyboard.

Next, set database file permissions. Make sure the webserver user (”www-data”) can read and write to Trac’s embedded SQLite database:

chown -R www-data /var/www/trac/
/db

Set the Trac Project’s Administrative Users

User authentication in Trac is taken care of by Apache 2’s htpasswd system. I created a Trac directory in /etc:

mkdir /etc/trac

Once this is done, you can create the initial trac.htpasswd user (this will also create a file /etc/trac/trac.htpasswd).

htpasswd -c /etc/trac/trac.htpasswd username

This will create an Apache2 htpasswd authentication file at /etc/trac/trac.htpasswd. To add another user to this file, run:

htpasswd /etc/trac/trac.htpasswd username

where username is the name of the user you want to add.

Actual permissions within Trac are dependent on the user’s Trac permissions level, as administered by trac-admin command-line utility. This is related to but distinct from the http authentication detailed here - Apache does the authentication, but trac-admin sets the permissions level of an authenticated user. To make a user a full administrator for a site, run

trac-admin /var/www/trac/
permission add username TRAC_ADMIN

For more info on permissions, see the Trac Site’s permissions page.

Setting up Apache2 and FastCGI

Having tangled with FastCGI setup previously when doing experiments with Ruby on Rails, I was dreading this part, but it actually went rather smoothly. Without getting into the details of all the different ways of running Trac (see “optional requirements” on this page if you’re interested in alternatives), FastCGI is the fastest option available, so I opted to use it. To enable the fastcgi module, issue the command:

a2enmod fcgid

This will enable the fastcgi module. Next, you need to set up a site in Apache2 and tell it to use FastCGI. In /etc/apache2/apache2.conf, add the following line:

DefaultInitEnv TRAC_ENV_PARENT_DIR /var/www/trac

This sets an environment variable to tell Trac that there are going to be multiple Trac projects living in this location. If you had only one project, you could make instead make it:

DefaultInitEnv TRAC_ENV /var/www/yourproject

Next, it’s time to get Apache2 serving your files using FastCGI. To do this, you will also need to add another line to apache2.conf telling Apache2 where the Trac fastcgi files are:

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

The last thing you need to do in apache2.conf is to tell Apache2 how to authenticate users on your Trac sites:

[LocationMatch /trac/[^/]+/login]
AuthType Basic
AuthName “Trac”
AuthUserFile /etc/trac/trac.htpasswd
Require valid-user
[/LocationMatch]

Note: square brackets around the “locationmatch” elements in the above code should be replaced with angle brackets, this blog isn’t displaying angle brackets (i.e. html open-close tag brackets) properly.

The above AuthType code is for a multiple-site Trac install like the one I’ve got, a single-site rule would instead swap this into the first line (again enclosed by angle-brackets):

Location "/trac/login"

And make sure to change the final “LocationMatch” tag to “Location” as well. At this point, you should be able to go to http://yourserver/trac/ and view a list of all available Trac projects.