Phase.org

So, everyone's got their sandboxes and dev servers, and they can all code merrily away and share their code. So far, so good. There are two things we now need: planning and documentation. I'll concentrate on the latter for the moment, by means of a Team Wiki.

There's a lot of odds and ends of documentation that needs to be shared in a dev team; things like Where The Code Lives, How The Servers Work and Those Important Planning Decisions. One way of doing this is just to stick all the docs in a shared drive on the server, but I've never seen that work so well; people can't find the docs they need and don't spot new documents and changes - and equally can't comment on any document or change. This strategy also tends to discourage minor hints and notes which can be invaluable. I find that a wiki works well to solve this problem, and the one I tend to use is Trac.

To be fair, calling Trac a wiki is selling it a bit short; it's also a ticket-tracking system and repository browser, and it ties these elements together well. The Trac site can fill you in on a bit more detail, but for the moment we'll just consider it as as useful location for project documentation.

Installing Trac, thanks to the magic of Ubuntu, is dead simple; just type (as root) aptitude install trac. Ain't Linux great?

Actually, in this case, no. Trac can be awkward to fully set up; the ubuntu and debian packages are (at the time of writing) at least a little broken, and you have to do a bit of magic to finish the setup. Here's the full process that currently works for my Ubuntu servers:

Install Trac, Python and ClearSilver

Most of trac's installation really is achieved with aptitude install trac, but there's still a fair bit of configuration to do.

Possible errors

Skip this block for now and come back to it if the next steps throw errors. You may get lucky and find it's all been fixed.

One common error is that Clearsilver doesn't properly install its python library in the Ubuntu package. The solution (usually in response to an error in neo_cgi.so) is to install the clearsilver library from source and ensure that you add the –with-python=/python/2.5/dir option when you configure it. Full details on that (and other possibe solutions) at https://launchpad.net/ubuntu/+source/clearsilver/+bug/86685

Create your trac project(s)

(you can have multiple projects within one trac install)

This is done with a command-line tool called trac-admin. You need to chose a location for your trac's data files; I tend to go with /opt/trac/whatever.

As trac will be operated via apache, the apache user needs to have full read/write access to all files. So, as root:

root@devbox:/opt/trac# trac-admin uberproject initenv and answer the questions it asks; for more info, trac-admin –help

then

root@devbox:/opt/trac# chown -R www-data:www-data uberproject

Set trac up in apache at a suitable URI

Add the following stanzas to an apache virtual server's config file, eg that for our devbox example:

<Location /trac>
   SetHandler mod_python
   PythonInterpreter main_interpreter
   PythonHandler trac.web.modpython_frontend
   PythonOption TracEnvParentDir /opt/trac/
   PythonOption TracUriRoot /trac
</Location>

Note that there are two ways of specifying the location of the trac files. You can set a path to a single trac as TracEnv /full/path/to/trac (eg TracEnv /opt/trac/uberproject) or have the potential for Trac to automatically find multiple trac sets under one parent directory with the newer TracEnvParentDir, which we use in the above example. Note that getting the wrong directory, or using the wrong directive, will lead to some very confusing errors

Assign user permissions

to allow developers to access the appropriate tools

This is done in a couple of places, and depends on how much public access you want to allow. We'll assume you only want known users to access your system and have no public read access. If you want fully public access, just skip the next steps.

Firstly, you need to create HTTP basic auth protection to your trac URI, as follows:

<LocationMatch "/trac/[^/]+">
  AuthType Basic
  AuthName "Trac"
  AuthUserFile /etc/apache2/trac.htpasswd
  Require valid-user
 </LocationMatch>

You'll also need to set up the htpasswd file as covered previously.

You can then, for each user requiring particular rights, go into trac-admin's interactive mode (root user will allow you to manage the files now owned by the web browser):

root@devbox:/opt/trac# trac-admin uberproject
[...]
Type: '?' or 'help' for help on commands.

Trac [/opt/trac/uberproject]>

Again, I'm not going to duplicate the trac manual here; do as it suggests and type help; look in particular at the 'permission add' command.

Having done all this, you can restart apache and visit your new trac system in a browser.

Once you've got Trac running, all can join in. The features you'll initially find the most useful are the Wiki and the Timeline. I'll introduce the timeline first, because it's simple as well as useful. Simply, it gives you a summary of who changed what and when; it's a combination of subversion's change log and the wiki's revision history, and provides a good way of working out both what you did (or when you did it) and keeping up with other developers' changes. This includes keeping track of who's creating good documentation and change messages, and who isn't.

The wiki is rather more basic than (say) Wikipedia and the syntax is quite old-fashioned (although there's a reasonable internal guide). Page names are generally CamelCase and new pages are created simply by clicking a link to, or visiting the address of, a page that doesn't yet exist. However it's lightweight and fairly easy to use.

In the next installment, I'll go into a little more detail on these, as well as some hints on using the system.