= Developer setup for Trac =
This tutorial assumes you have SVN installed.  If you don't have SVN installed please go to the [http://subversion.tigris.org/ Subversion] website and follow the directions of installation there.

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

=== 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 ===
Go to [http://peak.telecommunity.com/DevCenter/EasyInstall#installing-easy-install installing-easy-install] and follow the instructions there.  However, most of the time you just take the text at [http://peak.telecommunity.com/dist/ez_setup.py 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:
{{{
easy_install virtualenv
}}}

=== Set up a virtual environment ===
From the command-line prompt type:
{{{
virtualenv trac
cd trac
source bin/activate
}}}

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 trac-trunk
python setup.py develop 
cd ../genshi-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.

=== 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.

{{{
#!python
#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 tracdev 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`

{{{
#!python

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
}}}