Developer setup for Trac

This tutorial assumes you have SVN installed. If you don't have SVN installed please go to the ​Subversion website and follow the directions of installation there.

Where to go for more information

It is also a good idea to review a couple of documents before attempting to install a development environment or even to install from the trunk. One such place (currently) is to review the milestones page(s) to see if there are any specific requirements for the version you are setting up.

Specifically, for version 0.12 (the current trunk), you need to use a recent trunk version of Genshi (​[G1072] or later). See milestone:0.12 for more information.

The (automated) tests will require additional packages that may or may not be installed with your OS/Python distribution.

• For unit test, please review UnitTests
• For the functional test, please review FunctionalTests

Setting up the environment

Before we begin to develop in Trac, or even download Trac code, first create a standalone environment.

Note: if you planning to develop using Eclipse you should also check Development with Eclipse and PyDev.

Create a working directory

No matter my operating system, I like to create a projects or working directory for my development efforts. So for example on some systems, I might have:

/Users/myname/projects

On Windows I would have:

c:\projects

Note: I don't create a directory called 'trac' yet. That comes later! In the meantime, cd (change directory) to your projects directory.

Get easy_install

You may already have easy_install if you have "setuptools" installed. Just make sure its version is ≥ 0.6c10. Previous versions do not work correctly with SVN 1.6.

Otherwise go to ​installing-easy-install and follow the instructions there. However, most of the time you just take the text at ​ez_setup.py, save it as ez_setup.py on your hard drive, then from the command-line prompt type:

python ez_setup.py

Get virtual env

From the command-line prompt type:

sudo python -m easy_install virtualenv

Set up a virtual environment

From the command-line prompt type:

virtualenv trac
cd trac
source bin/activate

or for Windows

python -m virtualenv trac
cd trac
cmd /k Scripts\activate.bat

If you have trac installed in /usr/lib or /usr/local/lib, make sure to run the above virtualenv command with —no-site-packages.

You'll see your command-line prompt has changed. That means our environment is ready for Trac.

Installing and configuring Trac

Downloading trac

From the command-line prompt:

svn co http://svn.edgewall.org/repos/trac/trunk/ trac-trunk
svn co http://svn.edgewall.org/repos/genshi/trunk/ genshi-trunk
cd genshi-trunk
python setup.py develop 
cd ../trac-trunk
python setup.py develop
cd ..

Creating your test trac environment

From the command-line prompt:

trac-admin test initenv

note: Press return for every option.

Make anonymous users have full access

trac-admin test permission add anonymous TRAC_ADMIN

note: Don't do this in production!

Installing the trackdeveloperplugin

From the command-line prompt:

svn co http://trac-hacks.org/svn/tracdeveloperplugin/trunk/ tracdeveloperplugin
cd tracdeveloperplugin
python setup.py bdist_egg
cp dist/*.egg ../test/plugins
cd ..

Starting trac in development mode

From the command-line prompt:

tracd -r --port 8000 test

Note: The -r command puts Trac into refresh mode so your code changes will show up quickly. See also the auto_reload trac.ini flag which should be used for the changes in Genshi templates to be picked-up as well.

To run tracd or work in the virtual environment, you must switch to the virtual environment each time a new shell is opened.

source bin/activate

Web stuff

Switch to your browser and go to this URL:

​http://127.0.0.1:8000/test

Now lets follow a few more steps

• Go to web admin
• Hit the admin link
• Logging
  • Set type to console
  • level to debug

Alternative frontend: mod_python

Virtualenv can also be used with Apache and mod_python, but as mod_python will be a system install it will not be aware of the virutalenv without some configuration. For development this is useful as one Apache can serve various development versions in a more permanent way. This method will use the system Python, but will add the libraries from the virtualenv.

Step 1: Make a new frontend script that for instance can be stored in the virtualenv 'bin' directory.

#myvirtualtrac.py

import os
import site
site.addsitedir('/path/to/my/virtualenv/lib/python2.4/site-packages')

from trac.web.modpython_frontend import handler

Step 2: Update Apache config to use this script - add or update options according to the default mod_python setup like for instance found in TracModPython.

# Extend the path so Apache will find your script on path
PythonPath "['/path/to/my/virtualenv/bin'] + sys.path"

# Make mod_python use new frontend instead of trac.web.modpython_frontend
PythonHandler myvirtualtrac

Alternative frontend: mod_wsgi

Using Apache, mod_wsgi is a very good alternative to mod_python. Setting this up follows the same pattern, but for development escpecially there is one major advantage: It can quite easily be set up to auto-reload on code changes.

Step 1: Update a default TracModWsgi setup to make a deamonised process, and as of mod_wsgi 2.0 (this setup depends on ≥ 2.0) there is built-in support for custom paths and similar. Example of a full VirtualHost configuration:

<VirtualHost *:80>
    ServerName virtualtrac.local

    # Update user and group to be whatever on your system is intended to run the deamon
    # Update the paths to point to virtualenv site-packages (for trac+++) and bin (for script)
    WSGIDaemonProcess virtualtrac user=www group=www threads=25 python-path=/path/to/my/virtualenv/lib/python2.4/site-packages:/path/to/my/virtualenv/bin

    WSGIScriptAlias / /path/to/my/virtualenv/bin/virtualtrac.wsgi

    <Location />
      WSGIReloadMechanism Process
      WSGIProcessGroup virtualtrac
      WSGIApplicationGroup %{SERVER}
      Order deny,allow
      Allow from all
    </Location>

    # Authentication
    <LocationMatch (/[^/.]+/login)>
      # Note: Change settings with regards to auth method, paths and domain
      AuthType Digest
      AuthName "virtualtrac"
      AuthDigestDomain /trac http://virtualtrac.local
      AuthDigestProvider file
      AuthUserFile /path/to/access.htdigest
      Require valid-user
    </LocationMatch>

</VirtualHost>

Step 2: Go to ​http://code.google.com/p/modwsgi/wiki/ReloadingSourceCode and save the long Python script that follows the text 'Example code for such an automatic restart mechanism…'. Save it as /path/to/my/virtualenv/bin/monitor.py

Step 3: A basic WSGI frontend script, save as /path/to/my/virtualenv/bin/virtualtrac.wsgi

import sys
sys.stdout = sys.stderr

import os
os.environ['TRAC_ENV_DIR'] = "/path/to/trac/project"
# or, alternatively for multiple projects
#os.environ['TRAC_ENV_PARENT_DIR'] = "/parent/path/to/many/projects"
os.environ['PYTHON_EGG_CACHE'] = '/path/to/a/temp/to/cache/eggs'

import trac.web.main

import monitor
monitor.start(interval=1.0)
# Additionally monitor easy-install.pth to restart whenever installs are done
monitor.track('/path/to/my/virtualenv/lib/python2.4/site-packages/easy-install.pth')

application = trac.web.main.dispatch_request