How to install Agilo for trac

This page aims to give some specific issues and platform related information, to help you in getting Agilo for trac up and running.
We offer four types of downloads for Agilo:

Windows Installer for Agilo for trac including Agilo Pro
Virtual Machine for Agilo for trac including Agilo Pro
Python Eggs for Agilo for trac including Agilo Pro
Source code for Agilo for trac only

The Windows Installer and Virtual Machine are easy ways to get Agilo up and running. For heavy production use we recommend the use of the Python Eggs however. If you use the Windows Installer, you can skip down to Configure Agilo.
The Virtual Machine comes fully configured, read the Virtual Machine manual that comes with the download instead.Read on if you plan to install a Python Egg or if you want to install Agilo from source.

About Python

Python is a dynamic language, developed by Guido van Rossum. Agilo is written in Python and supports python 2.7.
You need to have Python installed before installing Agilo.

External libraries & Dependencies

Libraries and Tools

Python setuptools, download and install the latest version.
Trac, a generic ticketing system (Currently supported version: 1.0.11)

Databases

SQLite, the default used though not recommended for production use, doesn't require installation.
PostgreSQL, a very solid and performing database, recommended for production use.
MySQL, a commonly used db, MySQL has been tested with Agilo, though it is known to be unstable

These dependencies should be downloaded and installed automatically by the agilo setup.py script. If not, manually satisfy the dependencies. You can also find more information about this in trac's installation guide.

Quick Install Agilo / Agilo Pro

The following instructions assume you have Trac already installed and are logged into the Trac server.

Install Agilo Pro

Agilo Pro is an extended version of Agilo which adds more features on top (e.g. a white board for easier task handling and an inline ticket editor in the backlog). If you choose to install Agilo Pro, please skip the "Install Agilo Open" section.

Download the egg file that matches the version of Python you installed on your system, then:

unzip binary_agilo-_PRO-py.egg.zip 

sudo easy_install binary_agilo-...

Install Agilo Open from source

Download the Agilo source code package to your home directory, then:

cd ~ 

tar zxf agilo-source-latest.tar.gz

cd agilo 

sudo python setup.py install

Remember to restart tracd or Apache after installing if you are installing in an existing and running environment.

Configuration (both Agilo Open + Agilo Pro)

If you haven't done so already, create a Trac project (we'll call this project 'my_project'):

sudo trac-admin /var/lib/trac/my_project initenv

Answer the questions, usually the defaults are OK. Now you can launch the server following the command that will be printed on your screen at the end of the project configuration, most likely something like this:

tracd --port 8001 /var/lib/trac/my_project

This launches the Trac daemon and listen on the port 8001 to all addresses. You can now connect with your web browser to: http://localhost:8001/ and see your newly created project.
You will need now to activate authentication and create a system administrator, this operation may differ depending on the platform you are using, and on the authentication method you will be using. Here we mention one of the simplest options.

You will need to download an additional utility: trac-digest.py to create a digest password file. Using the following command you can both generate the password file and add additional users afterwards:

cd /var/lib/trac

python trac-digest.py -u username -p password >> users.digest

Now you will have to grant to the created username the rights to administer the environment:

trac-admin /var/lib/trac/my_project permission add username TRAC_ADMIN

Now you can start the Trac daemon with authentication:

tracd --port 8001 --auth=my_project,/var/lib/trac/users.digest,trac /var/lib/trac/my_project

Enable Agilo

To enable Agilo, the fastest way is to edit your new trac.ini file. Go to the location of the trac.ini file and open it in your editor of choice (in this example the 'nano' editor is used):

cd /var/lib/trac/my_project/conf
nano trac.ini

Add this section at the bottom of the config file:

agilo.* = enabled  

# the following lines are only required to use Agilo Pro

agilo_common.* = enabled

agilo_pro.* = enabled

Go back to the server console, and run:

sudo trac-admin /var/lib/trac/my_project upgrade

When you go back to Trac in the browser and reload the page, you should see the Agilo interface. For further information on how to configure Trac in more complex environments please refer to the Trac Guide.

Specific Platform & Operating System issues

This documentation is the result of a collaborative work between the Agilo Software team and all the Agilo for Trac users that contributed to solve a large amount of issues, participating actively in our User Group.

Installing on Windows

On Windows, you can use a dedicated Windows installer. Just download it here, unzip it and run the extracted executable file.This will create a Menu item to start the Agilo for Trac built-in server.

Notes for Cygwin users

Make sure that the TZ environment variable is not set when running Agilo within a Cygwin process as it may cause Python's built-in time functions not to work properly.

Installing on Mac OS X

We recommend using the binary egg as described previously, but you can use also the installation from source if you need more control over the installation process.

Installing on Linux from source

To install Agilo from source, you should only need a python interpreter and setuptools. Proceed in the following order:

Setuptools: Your Linux distribution may have a standard package for this, just make sure it is at least a 0.6c9
Agilo: For agilo you can also build an egg and copy it only in the plugins folder of the trac projects for which you want to enable it.

Just run:

$ python setup.py install

To install it system wide or build an agilo egg:

$ python setup.py bdist_egg

And then as root:

$ easy_install path/to_generated.egg

This was it, now you should have Agilo correctly installed. Remember to activate it for each project where you want to use it.

Subversion Integration

The Agilo for Trac Subversion Integration, add some features to allow you to change the status of a ticket via the Subversion submit comment, as well as letting you change the remaining_time of a task. To configure it, you will have to activate the two hooks in the subversion repository. To do so, go to your subversion project root, and have a look inside the hooks folder. There you should find a set of sample scripts, you will have to bind agilo script agilo_svn_commit_hook.py to both the pre-commit and the post-commithooks.Examples on how to create these two scripts are provided in the comments of the agilo_svn_commit_hook.py script.

Pre- and post-commit hook

Please have a look into the hook script that was installed with agilo - or look into the source tarball/scripts you downloaded to see examples of how to configure the pre and post commit hooks.
For more info on how to configure and use Subversion hooks, refer to the Subversion book or online groups.

Supported Commands

The agilo scripts supports the following commands, some of which are included as a compatibility with the trac-post-commit-hook.pywhich is a part of the contrib distribution of subversion:

CLOSE COMMANDS = 'close', 'closed', 'closes', 'fix', 'fixed', 'fixes' 
REFER COMMANDS = 'addresses', 're', 'references', 'refs', 'see' 
REMAIN COMMANDS = 'remaining', 'still', 'rem_time', 'time', 'rem'

Commands can be concatenated using and or & and are in the form of:

This closes #34 and #35 and remaining #5:4h. See #43 for more details.

The above comment will do the following:

Closes the ticket #34 and #35, agilo will check the following to allow to close the tickets:

that the tickets have been accepted
that the owner of the ticket is the same as the committer

Set the remaining time of ticket #5 to 4h, checking that the owner of the ticket is the same as the committer
Add a reference to the ticket #43 that will be marked also in the destinationticket, linking it to the current committed changeset.