Trac on Windows

I recently set up a Trac server on Windows, here’s how I did it.

1. Prerequisites

I used a fresh Server 2003 image (not 2008 for licensing related reasons)

On top of this the packages which need to be installed are:

Apache 2.2 (http://httpd.apache.org/download.cgi#apache22)
mod_auth_sspi (http://sourceforge.net/projects/mod-auth-sspi/)
mod_wsgi for Python 2.6 (http://code.google.com/p/modwsgi/wiki/DownloadTheSoftware?tm=2)
Python 2.6 (http://www.python.org/download/releases/2.6/)
setuptools 0.6c11 (http://pypi.python.org/pypi/setuptools)
Trac 0.12 (http://trac.edgewall.org/wiki/TracDownload)
Genshi 0.6 (http://genshi.edgewall.org/wiki/Download)

2. Installation

Most of these packages have Windows installers available, which simplifies matters. I installed in the order above, with the following additional steps:

To install mod_auth_sspi/mod_auth_wsgi the .so files were copied to:

C:\Program Files\Apache Software Foundation\Apache2.2\modules

The modules needed to be activated in the Apache configuration file:

LoadModule sspi_auth_module modules/mod_auth_sspi.so
LoadModule wsgi_module modules/mod_wsgi.so

3. Configuring Trac

I decided to keep my trac installation in the directory C:\trac, along with this the only other directory which needs to be backed up is:

C:\Program Files\Apache Software Foundation\Apache2.2

The database backend for Trac was chosen as sqlite, for simplicity. Unfortunately there isn’t yet a set of bindings between Trac and MS SQL, though the sqlite option is just as good for this purpose.

To initialise the Trac project the following commands need to be run:

C:\>mkdir C:\trac
C:\>cd C:\Python26\Scripts
C:\Python26\Scripts>trac-admin C:\trac initenv

At this point you can test the setup with:

C:\Python26\Scripts>tracd --port 8000 C:\trac

Try navigating to:

http:\\localhost:8000\

The main configuration file for Trac can be found at:

C:\trac\conf\trac.ini

(Or wherever you chose to put your trac instance).

One thing you’ll likely want to customise early on is to set a project-specific banner image, the configuration section to look for is:

[header_logo]
alt = Logo alt-text
height = 50
link = /
src = site/development.png
width = 400

Note that the path “site/development.png” actually appears to refer to:

C:\trac\htdocs\development.png

The “link” parameter is relative to your document root, e.g. in this case it’ll take us to the top level index of the Trac site.

4. Configuring Apache

It is possible to just use Trac with its own web server, but this is probably not a very efficient use of resources. The next steps detail getting Apache to serve the Trac site instead.

In order to use Trac with WSGI (and consequently with Apache) you need to deploy the trac environment so that it can be served by Apache. This process creates various files under the C:\trac\htdocs and C:\trac\cgi-bin directories, including the file trac.wsgi. This file plugs into the WSGI module as defined in the httpd.conf to enable the trac subsystem to be served via this method. The command to deploy your trac instance is:

C:\Python26\Scripts>trac-admin /trac deploy /trac

(You can change the last parameter if you want to put the deployed files somewhere else).

We also need to modify our httpd.conf (Apache’s configuration file) in order to serve the Trac site. This file can typically be found here:

C:\Program Files\Apache Software Foundation\Apache2.2\conf\httpd.conf

After enabling the mod_wsgi and mod_auth_sspi modules (see above) we need to modify the configuration file to add:

DocumentRoot "C:/trac/htdocs"

WSGIApplicationGroup %{GLOBAL}
Order deny,allow
Allow from all


WSGIScriptAlias / "C:/trac/cgi-bin/trac.wsgi"



Options Indexes
AllowOverride None
Order allow,deny
Allow from all

AuthName "Trac Server"
AuthType SSPI
SSPIAuth On
SSPIAuthoritative On
SSPIOfferBasic Off
SSPIUsernameCase lower

require valid-user

(Note that this should replace any existing directive in the configuration file. Also note that if you are using Virtual Hosting with Apache then the configuration would likely be quite different, but include the same basic concepts.)

The first Directory section sets up access to the WSGI application (Trac), and then sets the WSGIScriptAlias for the root directory. Any requests for the root directory will thus be served by WSGI, and therefore by the Trac application.

The second section (which only comes into play if we have the sspi_auth_module (mod_suth_sspi) installed. This configures access permissions to use Domain authentication. This means that your windows domain users shouldn’t need to log in to Trac, or at least they can do so using their domain credentials. Note the “SSPIUsernameCase lower” directive. This will convert the entire username string to lowercase before passing it to Trac as the authenticated user. Since Trac’s access controls are case-sensitive and Windows domain accounts are not we have to ensure that users logging in with uppercase characters all get mapped to the same user in Trac.

The other SSPI directives indicate that SSPI should be enabled and authoritative (so we are not going to consult any other authentication methods below SSPI, e.g. Basic auth). Finally the “require valid-user” directive indicates that any domain-authenticated user should be able to access this resource. Since we will be defining fine-grained access controls at the Trac level this is sufficient.

Once the configuration file is saved you should be able to start (or restart) Apache and navigate to http://localhost/ – you will be prompted for your domain login credentials if needed and you should see “logged in as domain\user.name” at the top-right when accessing Trac.

5. Configure Trac access permissions

To set up user permissions I’d recommend using the administration functions built into Trac itself (and accessible via the website). In order to use these you need to define at least one administrator using the command line utilities. The steps to do this are:

C:\Python26\Scripts>trac-admin /trac permission add domain\user.name TRAC_ADMIN

You can confirm the user’s permissions by this command:

C:\Python26\Scripts>trac-admin /trac permission list domain\user.name

Remember, these usernames are case-sensitive, so ensure that you use all lowercase to match with the usernames as they will be passed in from Apache.

6. Conclusion

After doing this and logging into Trac as the admin user defined you should see a new Admin option in the Trac top-bar. This will let you configure further user permissions.

At this point you should have a fully functioning Trac installation, and you can go about customising it as per the Trac documentation:

http://trac.edgewall.org/wiki/TracGuide