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.
- Don’t Have Trac Yet?
- Laying the Groundwork: Administering Trac and Users
- Enabling the AccountManager Plug-in
- A Friendlier Authentication and Login Set-up
- Your Trac Environment’s Configuration File
- SVN Post-commmit Hook
- Backing Up
- And Wrapping Up
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.
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.
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
$ 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.
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
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!
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.
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:
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
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
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.
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:
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.
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.
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.
- First, create a mail alias on the virtual server for your domain, with a mailbox name of
no-reply(or whatever you like).
- For an alias destination, choose
Write to file..and enter
/dev/nullin 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.
- 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.
- Give the user a password and disable all access for FTP, Subversion, DAV and MySQL.
- 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:
truefor this whole deal to work
smtp_passshould be set accordingly for the user you created above
smtp_serverto ‘localhost’ and
smtp_portto ‘587’ (this will use TextDrive’s secure SMTP)
- use your
- I like to use ‘MyProject Trac’ for
- I also prefer to set
use_public_ccto 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.
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:
- Trac post-commit hook to close tickets from the commit message and stuff#
/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.
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.
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.