Install Ubuntu Hardy Server Edition

I’m not going to tell you exactly how to do this, but at the proper step, the one where it asks what software packages you’d like, select the OpenSSH server and LAMP server packages.

Once the installation is complete and you’ve rebooted, remember to get the latest updates.

sudo apt-get update
sudo apt-get upgrade

Install Subversion and Python Parts

sudo apt-get install \
  libneon27 libsvn1 python-clearsilver \
  python-pysqlite2 python-subversion \
  subversion python-setuptools libapache2-svn \
  libapache2-mod-python python-pkg-resources

Setup Subversion Repository

Before we create our Trac environment, we need to setup our Subversion repository. I set mine up in the /var/lib/svn folder. Assuming this is the location you want to create yours, use the following commands to do so now.

sudo mkdir /var/lib/svn
sudo svnadmin create /var/lib/svn

Before we move on, we need to setup authorization and access to the subversion repository through Apache. First, let’s create the authentication file.

sudo htpasswd -cm /var/lib/svn/.htpasswd youruser

This command creates the file and adds your user to it. It will prompt you for a password.

We are going to setup Apache to serve the repository. Apache needs write access to the repository folder you just created. Let’s do that now:

sudo chown -R www-data:www-data /var/lib/svn

Now, let’s move on to Apache. Create a new file called /etc/apache2/sites-available/svn and populate it with the following:

<Location /svn>
  DAV svn
  SVNPath /var/lib/svn

  AuthType Basic
  AuthName "Subversion repository"
  AuthUserFile /var/lib/svn/.htpasswd

  Require valid-user
</Location>

Save the file and enable the site using the a2ensite command.

sudo a2ensite svn

Also, we’re not going to use the default Apache site. You can disable it now:

sudo a2dissite default

Restart Apache to get everything running.

sudo /etc/init.d/apache2 restart

You can now navigate to the /svn folder on your web server to browse the Subversion repository, i.e. http://yourserver/svn. The browser will prompt you for credentials which match up to those you entered while walking through the htpasswd command.

Install Trac

The quick way to install Trac is using easy_install.

sudo easy_install Trac

At time of writing, this installs Trac v0.11.1 and Genshi v0.5.1.

Setup Trac Environment

Now we’re ready to setup the Trac environment. My location, as with Subversion, will be in /var/lib, i.e. /var/lib/trac. Use the following commands.

sudo trac-admin /var/lib/trac initenv

Be prepared. The init script asks you for some basic information:

• name of your project
• database connection information
• source control repository type
• path to the source control repository (assuming you’ve selected SVN or other file based system supported by Trac)

Once you’ve answered the questions, the script sets up the environment in the directory you specified. You’re now ready to move on to configuring Apache.

Configure Apache

Apache needs write access to the directory and everything underneath. Issue the next command to take care of that.

sudo chown -R www-data /var/lib/trac

We need to tell Apache some things about Trac. Create a new /etc/apache2/sites-available/trac file and populate it with the following contents:

ServerName yourserver

<VirtualHost *>
  DocumentRoot /var/www
  <Location />
    SetHandler mod_python
    PythonInterpreter main_interpreter
    PythonHandler trac.web.modpython_frontend
    PythonOption TracEnv /var/lib/trac
    PythonOption TracUriRoot /
  </Location>
  <Location /login>
    AuthType Basic
    AuthName "Trac Server"
    AuthUserFile /var/lib/trac/.htpasswd
    Require valid-user
  </Location>
</VirtualHost>

Now, you need to enable the site. Create a link in the /etc/apache2/sites-enabled folder to your new file and restart Apache.

sudo a2ensite trac
sudo /etc/init.d/apache2 restart

At this point enough is setup to do a quick test. Try pulling up the trac site by navigating to http://yourhostname/. You should see the base Trac site with some introductory text. However, we’re not done. We need to do some configuration.

Setup admin user

The basic Trac environment includes enough to allow you to check the setup at the end of the last section. Previous versions of Trac required configuration by editing the /path/to/projenv/conf/trac.ini file.  Starting with v0.11, the WebAdmin plugin I used in v0.10 is already included.  In order to get to the WebAdmin, we need to create a user with admin rights.

Switch to the trac environment direction, e.g. /var/lib/trac. Issue the htpasswd command to create the trac.htpasswd file we configured Apache to look at.

sudo htpasswd -c .htpasswd youruser

The command asks you for the password for the user. Enter it to move on.

Once that’s done, let’s set the permissions on the file. While this probably isn’t absolutely necessary at this point, Apache will need access to this file after we install the AccountManager plugin below.

sudo chown www-data .htpasswd

The last thing we need to do is put the user in the TRAC_ADMIN group for the environment. The trac-admin command provides the way to accomplish this.

sudo trac-admin . permission add youruser TRAC_ADMIN

You should now be able to login to your Trac environment using the credentials you setup. You will see new options for creating and removing pages in the environment.  Your new admin rights also provide an Admin link in the menu bar.

Install AccountManager plugin

The AccountManager plugin works in conjunction with the WebAdmin plugin to allow you to manage user accounts for the Trac environment.

A note about installing plugins: I prefer to install the plugin in the Trac environment using the process I will outline next.  There are other methods of installing a plugin and most are documented on the plugin site.

Navigate to a directory on your machine where you will download and build the plugin.  I use a trac-plugins directory under my home directory.

Once there, get the AccountManager plugin from source and build the egg using the following commands:

svn co http://trac-hacks.org/svn/accountmanagerplugin/trunk \
  AccountManager
cd AccountManager
python setup.py bdist_egg

You need to move the egg to the /path/to/projenv/plugins directory.  Using our /var/lib/trac example from the previous command line:

sudo cp dist/TracAccountManager*.egg /var/lib/trac/plugins
sudo chown www-data \
  /var/lib/trac/plugins/TracAccountManager*.egg
sudo /etc/init.d/apache2 restart

Trac automatically enables the plugin with all options selected.  Users with the TRAC_ADMIN permission can enable the plugin using the WebAdmin. Once logged in, navigate to the admin page and select plugins. Expand the TracAccountManager section and check the components you want to turn on.

Before we finish, we need to tell it where to find the htpasswd file we started using. You should now see an Accounts section in the left menu. The first entry under Accounts is Configuration. Select it and enter the path to the htpasswd file, i.e. /var/lib/trac/.htpasswd if you’ve been following these instructions exactly. If not, put in the actual path you used.

Restart Apache to clear cache and such:

sudo /etc/init.d/apache2 restart

Setup SMTP for change Notification

Email notifications of ticket creation and changes is a useful feature. WebAdmin does not support administration of the SMTP settings, so we will have to return to the trac.ini file. This file contains a section [notification]. The package version of this file has SMTP turned off by default. To enable it, you need to provide a few pieces of information.

The [notification] section of the package trac.ini file looks like this:

[notification]
admit_domains =
always_notify_owner = false
always_notify_reporter = false
always_notify_updater = true
ignore_domains =
mime_encoding = base64
smtp_always_bcc =
smtp_always_cc =
smtp_default_domain =
smtp_enabled = false
smtp_from = trac@localhost
smtp_from_name =
smtp_password =
smtp_port = 25
smtp_replyto = trac@localhost
smtp_server = localhost
smtp_subject_prefix = __default__
smtp_user =
ticket_subject_template = $prefix #$ticket.id: $summary
use_public_cc = false
use_short_addr = false
use_tls = false

You need to make changes to the appropriate sections. For example, my internal email SMTP server uses standard ports. I changed the following settings:

• smtp_enabled = true
• smtp_default_domain = my base domain name, e.g. foo.com
• smtp_from = my email address
• smtp_password = my passwd
• smtp_replyto = my email address
• smtp_server = name of my smtp server
• smtp_user = my username

Once you make these changes, restart Apache to ensure Trac looks at the new configuration.

sudo /etc/init.d/apache2 restart

Trac Ready

At this point, Trac should be ready to go. One of the things I like about Trac, though, is that it has a flexible plugin API written in Python! There are a number of plugins, scripts and macros I use.  Some of these:

• PermRedirectPlugin - to gently direct users to a login page when they attempt to access a page requiring permissions
• TracWysiwygPlugin - to make it easier for non-tech folks to edit the pages
• WikiNotificationPlugin - to allow users to subscribe to notifications of updates to wiki pages
• WikiRename - to rename pages, useful if you want to reorganize and you are using a section/sub-section/page organization
• WikiNotification - if your users want to be notified of a change to a wiki page
• TracSvnAuthzAdmin - to administer the Subversion authorization file
• TracIncludeMacro - I use this to build fragments I want to include on many pages
• TracNav - to build custom Table of Contents
• TracWysiwyg - Wysiwyg editor for wiki pages and ticket content
• ..