Pimping Your Trac on TextDrive, Part II

Apologies for taking so long to post Part II. I had hoped that the templates for the Tags Plugin would be ported to Genshi, or that I’d have time to do so myself, before finishing. Unfortunately neither of those things has happened, and in fact the entirety of trac-hacks.org was down for several weeks. That would have been rather annoying when trying to work through this article…

In Part I, we covered the installation of Trac on a shared host at TextDrive by setting up a user-local Python environment. That, along with PEAK‘s setuptools, made it trivial to install a spanking new version of Trac and its prerequisites (along with a few optional niceties). We also saw a simple authentication set-up, and how to make sure tracd and its HTTP server get restarted if a system reboot is necessary.

Now in Part II we’re going to look at administering and extending Trac with some plug-ins, ranging from small and simple to large, complex tools. Some serve utility functions such as providing attractive web-based frontends for various aspects of Trac configuration, while others add wholly new capabilities to the system. Fortunately, thanks to our preparations in the last article, installing plug-ins is quite easy.

Contents

Don’t Have Trac Yet?

If you haven’t installed Trac yet, what are you waiting for?! Go! The steps in Part I should help you. Even if you’re not using TextDrive for hosting, Trac installation should be largely the same. If you use another shared host, where it may be desirable or altogether necessary to set up your own Python environment, those steps may apply to you too. Just make sure your host’s system Python version is at least 2.3 if you opt to go the virtual-python route, and preferably 2.4 or above. If you have a VPS or some other set up where you have root access, you can just install Trac with the system Python, and be up and running in no time.

Laying the Groundwork – Administering Trac and Users

Installing most plug-ins is dead simple, so before you go off and get a dozen of them, let’s take a minute to do some housekeeping before there’s any extra clutter that might lead to confusion. You may remember me mentioning in the last article that the WebAdmin plug-in is integrated into the core product for Trac 0.11. That saves us the trouble of what would probably be the first additional installation that most people would want to make. There is another component, though, that integrates with WebAdmin and one would almost expect it to be a part of it: the AccountManager plug-in. Let’s go ahead and install it, and then we’ll be ready to take care of the most important configuration steps from the web interface.

$ easy_install http://trac-hacks.org/svn/accountmanagerplugin/trunk

Yep, that’s it. . We just need to enable the plug-in now that it’s installed… but first we need a privileged user.

In the last article, I left you hanging a bit on the subject of user account management, because I intended to show you the AccountManager plug-in here. We’ll have to set up the first user the hard way, but I’ll show you how to make it easier from then on.

Adding the First User

This first bit is a quick review of the simple authentication setup from last time. If you’ve already created your htdigest passwd file with an initial user or two, you’ll just need to add your user(s) to the Trac environment and assign permissions. If not, here’s a quick summary. Use this command to create a password file and add the first user:

$ htdigest -c /home/<youruser>/etc/trac.digest.passwd yourdomain.tld username

Make sure you have an etc directory in $HOME — use mkdir ~/etc first if necessary (or you can use /etc if you have root access on your server). username is arbitrary, but if you’re limiting access to a development team, it’d be sensible to match with svn users. Omit the -c switch on subsequent calls to htdigest for the file.

We’ll now add this user to the Trac environment and give him full admin privileges (consider this the Trac equivalent of root):

$ trac-admin /path/to/your/env permission add <username> TRAC_ADMIN

By default, anonymous users browsing your Trac site will be able to view all the standard components (including your source code!), but they won’t be able to modify anything. We’ll see how to change these settings shortly.

Restarting Trac

Just one more step before we can leave the command-line world for awhile — restarting tracd so that it picks up our new plug-in and user account. The command to launch tracd is just like the one used for the cron job if you set up authentication in Part I.

$ killall python
$ tracd -d -p XXXX --auth \
yourenv,/home/<youruser>/etc/trac.digest.passwd,yourdomain.tld \ 
/home/<youruser>/trac/<yourenv>

The first command is a bit reckless — I’m assuming that you’re not running any other long-running Python processes on your web host (besides tracd). If you are, I probably don’t need to point this out to you, and you probably know how to use the ps command to find which Python process you should kill. Replace the Xs with the port where you’re running tracd. .

Now when you visit your Trac in a browser, you should be prompted for login credentials. Log in with a user that you gave the TRAC_ADMIN privilege to just a moment ago, and you should see a new ‘Admin’ button on the far side of the navigation bar. Congrats, most of the hard work is behind you!

Exploring the Admin Interface

At this point I’d suggest that you browse the admin interface on your own to get acquainted with the settings available there. These cover a great number of configuration options that used to require trac-admin commands or editing of the trac.ini file. Don’t get overzealous and enable anything from the AccountManager plug-in just yet — we’ll do that in a sec, and I’ll explain it as we go.

You can always consult the TracGuide if you want to learn more about a particular option or part of Trac, and you have your own copy on your Trac wiki as well. Of particular interest is the ‘Permissions’ link under the ‘General’ menu, where you can configure permissions as we did before at the command line. Full explanation of the permission settings is available at TracPermissions, and you’ll see how to add users in the next section.

Enabling the AccountManager Plug-in

Under the General >> Plugins section of the Admin tab, you should see the TracAccountManager plug-in listed with a disclosure triangle. Click the triangle to list the components of the plug-in, and enable the following:

  • AccountManagerAdminPage
  • AccountManager
  • SessionStore
  • AbstractPasswordFileStore
  • HTDigestStore
  • HTDigestHashMethod

The homepage for AccountManager at trac-hacks.org gives a breakdown of what each component does. You can also hover over the items for tooltips. To quickly summarize, the AccountManager component is the plug-in core and is required for use. The AdminPage component naturally provides a configuration page in the web interface. The others relate to password management: SessionStore interfaces with Trac’s database for session management and is required for any of AccountManager’s password mechanisms. Similarly, AbstractPasswordFileStore allows the plug-in to work with htpasswd or htdigest password files. Since we’re already working with htdigest, we’ve enabled the components to support this, and we don’t need the others. We’ll revisit a few of them in a little while.

Now it’s time to restart tracd again: use the killall and tracd launch commands described previously, and refresh your browser. You can use the up arrow key or CTRL+P to recall your command history, or in Bash you can type CTRL+R and type ‘tracd’ to search for your last launch command. Don’t forget to kill the old process first.

Go to Accounts >> Configuration and click the HtDigestStore radio button. In the filename field, enter the full path to your password file (e.g. /users/home/youruser/etc/trac.digest.passwd). For realm, enter your domain name as specified when you ran the htdigest command. Click Save, and you can now view and add users in Accounts >> Users. Unfortunately the interface doesn’t allow you to edit users at this time — full name and email are set on each user’s individual Preferences page.

A Friendlier Authentication and Login Set-up

AccountManager has a few more nice features that we’ll take advantage of: using an HTML login form instead of the pop-up you’ve seen thus far, and allowing users to change their password or delete their account. To use these features, we’ll need to enable two more components for TracAccountManager under General >> Plugins:

  • AccountModule
  • LoginModule

Then expand the entry for Trac itself, disable the LoginModule there, and click Apply. We’re supplanting the built-in login module with AccountManager’s. If you wish, you can also enable AccountManager’s RegistrationModule, which will allow anyone to register for an account by visiting the Login page. If you elect to do so, you should definitely read on for info about the SpamFilter plug-in!

Since we’ve added plug-in components, it’s time to restart tracd once more. But now that AccountManager is handling the authentication, we don’t need to tell tracd about our auth config anymore. Instead, you can simply run with a command like this, substituting your port:

$ tracd -d -p XXXX /users/home/<youruser>/trac/test

Important Note!: At this point, you should also change the command in your restart cron job to leave out the authentication information. Remember the crontab -e command? Check that section of Part I if you’ve forgotten, or need a refresher on how to navigate vi for editing the file.

Now users will be presented with a nice login form instead of the pop-up, and an Account tab will appear on their Preferences page for password changes and account deletions. Finally, once we configure Trac’s SMTP settings in a few moments, a ‘Forgot Your Password?’ link will show up on the login page allowing users to reset their passwords.

Your Trac Environment’s Configuration File

You’ll probably want to take care of a few more configuration tasks before moving on to fun times using Trac in full swing. The main config file for your Trac instances will be located at $HOME/trac/<yourenv>/conf/trac.ini if you’ve followed my guides so far. There are a large number of directives that can be specified in this file, and plug-in documentation will often instruct you to make changes as well.

It can become tiresome to log in through a shell and modify this file to make changes, so fortunately there is an IniAdmin plug-in which exposes most, if not all, of the fields from the ini file through the WebAdmin plugin (built-in to Trac 0.11). The [components] section, which is used for plug-in configuration, is already handled by WebAdmin for most cases. You may occasionally find that a plug-in can’t be correctly set up through WebAdmin/IniAdmin, and some changes still require you to restart tracd to take effect, but generally you won’t need to log in over SSH nearly as often. Here’s how I installed IniAdmin:

$ cd ~/trac
$ mkdir src; cd src
$ svn co http://trac-hacks.org/svn/iniadminplugin/0.11 IniAdmin
$ cd IniAdmin
$ python setup.py install

This will install an egg in your local Python environment, and you should be able to enable the plug-in through the admin area of your Trac site. You may need to restart tracd as described previously in this guide. Once it’s up and running, you’ll see all the sections of your trac.ini file listed as links in the admin navigation of your site. Most of the options are explained in the wiki section for TracIni.

Configuring Notifications

With the IniAdmin plug-in installed, we can comfortably take care of SMTP settings for getting notifications working. The instructions here are pretty specific to TextDrive — you’ll need to adapt them as required if you’re setting this up elsewhere.

First, I recommend that you set up a dedicated auto-mail user for your domain through webmin at TextDrive. You can also use this for anything in addition to Trac where you might want to send automated emails. I’ll cover this in brief, so consult the E-mail section of the TextDrive knowledgebase if you’re not sure how to do something.

  1. First, create a mail alias on the virtual server for your domain, with a mailbox name of no-reply (or whatever you like).
  2. For an alias destination, choose Write to file.. and enter /dev/null in the field. This might change to indicate “Delete mail” after you submit the form for the first time — that’s what we’re doing here. Any mail sent to no-replyyourdomain.com@ will disappear into oblivion.
  3. Now create a real mail user for sending mail. I use a username like postmaster-abbrev (use some unique abbreviation of your choosing) and set the ‘Real name’ to something like ‘Automailer’ so you can easily recognize it.
  4. Give the user a password and disable all access for FTP, Subversion, DAV and MySQL.
  5. Be sure that primary email address is enabled, and you’ll probably want to set some fairly low quota.

Now on to Trac. Click the ‘notification’ link under ‘trac.ini’ in your site’s admin. You can mostly set these options as you see fit. Here are the ones you’ll probably want to make sure to set:

  1. smtp_enabled should be true for this whole deal to work
  2. smtp_user and smtp_pass should be set accordingly for the user you created above
  3. set smtp_server to ‘localhost’ and smtp_port to ‘587’ (this will use TextDrive’s secure SMTP)
  4. set use_tls to true
  5. use your no-reply address for smtp_from and smtp_replyto
  6. I like to use ‘MyProject Trac’ for smtp_from_name
  7. I also prefer to set use_public_cc to false to protect users’ privacy as much as possible.

That should do it. Again, you may need to restart tracd, then try a test ticket to see if your notifications are working as expected.

SVN Post-commit Hook

This part is optional but highly recommended. You may know that Subversion features hooks to trigger scripts when certain actions occur (see the SVN Book to learn more). The Trac repository contains a user-contributed script that will automatically respond to text in commit messages like “closes #13” or “references #53” by creating links to the referenced tickets by number, and closing them if appropriate. You can read the detailed comment at the beginning of the script itself for further info.

Here’s what you’ll need to get this working with our setup:

$ cd ~/svn/<your-repo>/hooks
$ svn co http://svn.edgewall.org/repos/trac/trunk/contrib/trac-post-commit-hook
$ nano trac-post-commit-hook
... change the top line as follows ...
#!/users/home/<youruser>/python/bin/python
... save and exit with CTRL-O then CTRL-X ...
$ chmod 770 trac-post-commit-hook

Then, edit the file post-commit in the same directory, so that the body of the script looks something like this, edited appropriately:

REPOS=”$1”
REV=”$2”

#

  1. Trac post-commit hook to close tickets from the commit message and stuff
  2. #
    export PYTHONPATH=’/users/home//python/lib/python2.4:/users/home/samwise97/python/lib/python2.4/site-packages’
    TRAC_ENV=”/users/home//trac/

    /users/home//python/bin/python /users/home//svn//hooks/trac-post-commit-hook \ -p “$TRAC_ENV” -r “$REV”

Be sure to leave the shebang line at the top. The last step for getting this to work will require you to submit a ticket to TextDrive support. The trac-post-commit-hook file needs to be owned by the ‘www’ user in order for it to get executed correctly.

Backing Up

One of the nice things about the way Trac project environments are set up is that back-ups are easy as py (nyuck nyuck!). The directory containing the environment contains everything that you’d want to back up for a project: configuration, customized templates, attached files, and the project database. Just create a tarball of the environment directory and copy it elsewhere. You can create a script to do this, and use cron to run it periodically. The TextDrive knowledgebase article for database back-ups can give you an idea of how to get started.

And Wrapping Up

By now, you should have quite a nice Trac site for your software projects. We’ve seen how to install Trac with a custom Python environment, how to configure it, and how to extend it with plug-ins.

There are numerous other useful plug-ins, such as a SpamFilter, a simple Pastebin (which needs a tiny edit for 0.11 that I submitted here), or the versatile TagsPlugin. Installing these should be much the same as those that we’ve seen already, and you’ll find instructions at the links given. You might also like to customize your site templates and CSS — the Elixir project’s site is a nice example.

Recent versions of Trac also have expanded support for alternate versioning systems in place of Subversion. I’ve written another article concerning the use of the Mercurial distributed VCS and using it with Trac.

Another ambitious project (by the creator of Trac) is Bitten, a distributed continuous integration and build system integrated with and built heavily around Trac. I’m keen to play with this in the future, and I’ll surely chronicle my experiences when I have the chance.

I hope you’ve found these guides useful, and that Trac serves you well.

there is a bug in easy_install

Hi,

I found that there is a bug with the 0.9.5 build of Mercurial, it is not easy_installable http://www.selenic.com/mercurial/bts/issue799

Rеally like the webѕite and

Rеally like the webѕite and we have bookmɑrked it, please include much more content.

Hi, all is going perfectly

Hi, all is going perfectly here and ofcourse every one is sharing data, that’s truly fine, keep up writing.

I bought it but can’t

I bought it but can’t understand how to use it..please guide me.
ipad 3

I am thoroughly impressed by

I am thoroughly impressed by the way you present your article..
ipad 3

Your blog is probably one of

Your blog is probably one of the most effective . Complete effect of the blog is simply dramatic .
Bloomington Locksmith

Very infomative post

Very infomative post indeed….thanks a lot for your time and perspective!
pneu agricole
atv tires

Why not writing another part

Why not writing another part of the article including the updates?
kerry from android development

I like your style. Keep up

I like your style. Keep up the good work.
bannière

WOW just what I was looking

WOW just what I was looking for. Came here by searching for supervision

Post new comment

The content of this field is kept private and will not be shown publicly.
By submitting this form, you accept the Mollom privacy policy.