This page documents the 1.4 (latest stable) release. Documentation for other releases can be found here.

Trac and mod_python

Trac 0.7.1 and later supports ​mod_python, which speeds up Trac's response times considerably and permits use of many Apache features not possible with tracd/mod_proxy.

Be sure to grab mod_python 3.1.3 and later for SetHandler mod_python directive to work. Also, older versions may generate an internal error. ​#1090

Trac Trunk Configuration

The examples below are written for Trac 0.8.x. If you are running Trac from the trunk source you will need to make a modification to the configuration.

The mod_python handler class is changed in trunk revision [1287] and later, so you'll need to substitute the following line:

   PythonHandler trac.ModPythonHandler

with this one:

   PythonHandler trac.web.modpython_frontend

Simple configuration

Here's a typical Trac CGI/Apache setup:

ScriptAlias /projects/myproject /path/to/python/share/trac/cgi-bin/trac.cgi
<Location /projects/myproject>
   SetEnv TRAC_ENV /var/trac/myproject
</Location>

The equivalent mod_python setup is:

<Location /projects/myproject>
   SetHandler mod_python
   PythonHandler trac.ModPythonHandler
   PythonOption TracUriRoot "/projects/myproject"
   PythonOption TracEnv /var/trac/myproject
</Location>

Note that the option TracUriRoot may or may not be necessary in your setup. Try without first, and if the URLs produced by Trac look wrong, add the TracUriRoot option.

Authentication works the same as for CGI:

<Location "/projects/myproject/login">
  AuthType Basic
  AuthName "myproject"
  AuthUserFile /var/trac/myproject/.htaccess
  Require valid-user
</Location>

Setting up a project on the root of the webserver

To install Trac on the root of the webserver (in a virtual host context for example) and make it available at the http://some-hostname/ URL, use the following:

<VirtualHost trac.example.org>
  ServerName trac.example.org
  Alias /trac /var/www/trac.example.org/htdocs/trac
  <Location />
    SetHandler mod_python
    PythonHandler trac.ModPythonHandler


    PythonOption TracUriRoot "/"
    PythonOption TracEnv /var/trac/myproject
  </Location>
  <Location /login>
    AuthType Basic
    AuthName "My Project"
    AuthUserFile /var/trac/myproject/.htaccess
    Require valid-user
  </Location>
  <Location /trac>
    SetHandler None
  </Location>
</VirtualHost>

The path in the last <Location> block should match your htdocs_location. The directive "SetHandler None" allows us to escape mod_python and have Apache serve the static files (located at /var/www/trac.example.org/htdocs/trac/ on the filesystem in this example). Any other URLs will be handled by mod_python.

Setting up multiple projects

The Trac mod_python handler handler supports a configuration option similar to Subversion's SvnParentPath, called TracEnvParentDir:

<Location /projects>
  SetHandler mod_python
  PythonHandler trac.ModPythonHandler
  PythonOption TracUriRoot /projects
  PythonOption TracEnvParentDir "/var/trac"
</Location>

When you request the /projects URL, you will get a (currently very simple) listing of all subdirectories of the directory you set as TracEnvParentDir. Selecting any project in the list will bring you to the corresponding Trac instance. You should make sure that the configured directory only contains Trac environment directories that match the currently installed Trac version, because that is not checked prior the the generation of the project list.

Setting up multiple projects as the root URL

Let's say you want something like ​http://projects.yourdomain.com which has a list of all of the projects hosted on it. However, you don't want to do manual configuration every time a new project is added. Or, you'd like to minimize it. Here's a quick sample:

Alias /trac/ /usr/share/trac/htdocs/
<Directory "/usr/share/trac/htdocs">
   Options Indexes MultiViews
   AllowOverride None
   Order allow,deny
   Allow from all
</Directory>

<Location />
   SetHandler mod_python
   PythonHandler trac.ModPythonHandler
   PythonOption TracUriRoot /
   PythonOption TracEnvParentDir "/var/trac"
</Location>

<Location /project1/login>
   AuthType Basic
   AuthName "Project1"
   AuthUserFile /var/www/projects.yourdomain.com/security/users
   AuthGroupFile /var/www/projects.yourdomain.com/security/groups
   Require group project1-users
</Location>

<Location /project2/login>
   AuthType Basic
   AuthName "Project2"
   AuthUserFile /var/www/projects.yourdomain.com/security/users
   AuthGroupFile /var/www/projects.yourdomain.com/security/groups
   Require group project2-users
</Location>

<Location /trac>
   SetHandler none
</Location>

A few things to note about this example: all of the users are stored in one file, /var/www/projects.yourdomain.com/security/users. Groups for these users are defined in the groups file, /var/www/projects.yourdomain.com/security/groups. The Trac projects are all stored under /var/trac.

To add a new project, you'll have to create a new user in the user file. Then, create a new group for the project in the group file. Finally, create a new <Location> block with a new Require group directive. That about it.

Note: if there was a way to do conditional processing in configurations (I haven't figured it out, if there is), you could use the following setup:

<Location /*/login>
   ...
</Location>

Troubleshooting

Form submission problems

If you're experiencing problems submitting some of the forms in Trac (a common problem is that you get redirected to the start page after submission), check whether your DocumentRoot contains a folder or file with the same path that you mapped the mod_python handler to. For some reason, mod_python gets confused when it is mapped to a location that also matches a static resource.

Using .htaccess

Although it may seem trivial to rewrite the above configuration as a directory in your document root with a .htaccess file, this does not work. Apache will append a "/" to any Trac URLs, which interferes with its correct operation.

It may be possible to work around this with mod_rewrite, but I failed to get this working. In all, it is more hassle than it is worth. Stick to the provided instructions. :)

mod_python does caching: beware

When using mod_python you have to reload apache before changes to a trac.ini of a project or a projects templates take effect!

Win32 Issues

If you run trac with mod_python on Windows, attachments will not work.

There is a (simple) workaround for this which is to apply the patch attached to ticket ​#554.

OS X issues

There is a mod_python issue on OSX: Look at the end of its README. You need to either define the environment variable DYLD_FORCE_FLAT_NAMESPACE before starting httpd or apply ​this patch to mod_python.

Also note another potential issue where Apache will return a 500 error regardless of what you try to do with mod_python. If you see this, make sure you do not restart using apachectl restart, but instead stop and start the server again. This solves the issue.

---

See also TracGuide, TracInstall, TracMultipleProjects