[[PageOutline]]

= How to install the latest version of the Agile-Trac =

== Introduction ==

The Agile-Trac plugin is a combination of a [http://trac.edgewall.org/wiki/TracPlugins Trac plugin] and a patch for [http://trac.edgewall.org/ Trac]. This makes the installation of the plugin a little more complicated than usual, but still relatively straight-forward. The reasons for requiring a patch in addition to the plugin are detailed on the InitialDiscussion page. Over time it is hoped that this requirement will be removed.

== Prerequisites ==

  * [http://peak.telecommunity.com/DevCenter/EasyInstall#installing-easy-install easy_install (setuptools)]
  * [http://trac.edgewall.org/wiki/TracDownload Trac 0.11 or later]

== Step 1: Install the plugin ==

The easiest way to install the plugin is to use `easy_install`.

{{{
easy_install http://svn.agile-trac.org/BRANCH/AGILE-TRAC/SOURCE/0.11/REL/
}}}

==== Upgrading the Agile-Trac Plugin ====

If you already have Agile-Trac installed you can use the `-U` flag to upgrade your plugin to the latest one,

{{{
easy_install -U http://svn.agile-trac.org/BRANCH/AGILE-TRAC/SOURCE/0.11/REL/
}}}


== Step 2: Install the patch ==

The easiest way to 'patch' your [http://trac.edgewall.org/ Trac] install is to,

=== 2.1 Locate and change to the [http://trac.edgewall.org/ Trac] installation directory ===

'''Note:''' The location of your [http://trac.edgewall.org/ Trac] install will depend on the version number, for example you might have [http://trac.edgewall.org/browser/tags/trac-0.11/RELEASE Trac 0.11] or a newer version like [http://trac.edgewall.org/browser/tags/trac-0.11.1/RELEASE Trac 0.11.1].

==== Windows ====

This will depend on your installation, for example with [http://trac.edgewall.org/browser/tags/trac-0.11/RELEASE Trac 0.11], this may work.

{{{
cd C:\Python25\Lib\site-packages\Trac-0.11-py2.5.egg
}}}

==== Linux ====

'''Do these commands as a user of sufficient privileges, for example as `root`.'''

This will depend on your distribution. For example in Debian Testing for [http://trac.edgewall.org/browser/tags/trac-0.11/RELEASE Trac 0.11] you might type:

{{{
cd /usr/lib/python2.5/site-packages/Trac-0.11-py2.5.egg/
}}}

=== 2.2 Rename the `trac` folder contained in your existing [http://trac.edgewall.org/ Trac] installation ===

==== Windows ====

Either use Windows Explorer to change the name

{{{
move trac trac_orig
}}}

==== Linux ====

{{{
sudo mv trac trac_orig
}}}

=== 2.3 Use [http://subversion.tigris.org/ svn] to checkout the patched version of trac from this site ===

There is a single unified patch that can be used to replace all trac versions on the 0.11 branch, so far this is up-to-date with the following releases:

  * [http://trac.edgewall.org/browser/tags/trac-0.11/RELEASE Trac 0.11]
  * [http://trac.edgewall.org/browser/tags/trac-0.11.1/RELEASE Trac 0.11.1]
  * [http://trac.edgewall.org/browser/tags/trac-0.11.2/RELEASE Trac 0.11.2 or Trac 0.11.2.1]
  * [http://trac.edgewall.org/browser/tags/trac-0.11.3/RELEASE Trac 0.11.3]
  * [http://trac.edgewall.org/browser/tags/trac-0.11.4/RELEASE Trac 0.11.4]
  * [http://trac.edgewall.org/browser/tags/trac-0.11.5/RELEASE Trac 0.11.5]

{{{
svn co http://svn.agile-trac.org/BRANCH/AGILE-TRAC/SOURCE/0.11/REL/patch/trac/ trac
}}}

==== Upgrading from an older patch ====

If you are using one of the older versioned patches,

  * http://svn.agile-trac.org/BRANCH/TRUNK/source/agiletracplugin/0.11/patch-0.11/trac/
  * http://svn.agile-trac.org/BRANCH/TRUNK/source/agiletracplugin/0.11/patch-0.11.1/trac/
  * http://svn.agile-trac.org/BRANCH/TRUNK/source/agiletracplugin/0.11/patch-0.11.2/trac/
  * http://svn.agile-trac.org/BRANCH/TRUNK/source/agiletracplugin/0.11/patch-0.11.3/trac/

then you will need to replace it with the new one. 

  1. First moving the old directory away using the same technique described in section 2.2.
  2. Now check out the new unified patch as described above.

== Step 3: Restart your trac server ==

== Step 4: Enable the Agile-Trac plugin ==

Either

  1. Enable from the `Admin` section in your trac web, or
  2. Specify all the Agile-Trac components as `enabled` in your `trac.ini` file,

{{{
[components]
agiletrac.api.agiletracsystem = enabled
agiletrac.env.agiletracsetup = enabled
agiletrac.workflow.agileticketworkflow = enabled
}}}

== Step 5: [http://trac.edgewall.org/wiki/TracUpgrade Upgrade your trac] enviroment ==

{{{
trac-admin /path/to/trac/project upgrade
}}}

== Step 6: Restart your trac server ==

'''Done! '''


= Frequently Asked Questions =

== I receive an 'error: Unexpected HTML page found at ...' message when trying to use `easy_install` to install the plugin ==

The reason for this is that the current stable release of [http://peak.telecommunity.com/DevCenter/setuptools setuptools] does work well with Subversion 1.5.

=== Solution ===

You need to install the latest development branch of setuptools.

{{{
svn co http://svn.python.org/projects/sandbox/branches/setuptools-0.6/
}}}

Then install it as root.

{{{
cd setuptools-0.6
python setup.py install
}}}

== After installing the Agile-Trac plugin, I get an error when displaying the Roadmap page ==

See also ticket:57 and ticket:62.

{{{
Trac detected an internal error:

DatabaseError?: ORDER BY terms must not be non-integer constants
}}}

=== Solution ===

The solution appears to be to make sure you have up-to-date versions of `sqlite3` and `pysqlite2`.