How To Install Agilo for Scrum

This page aims to give some specific issues and platform related information, to help you in getting Agilo for Scrum up and running.

We offer four types of downloads for Agilo:

1. Windows Installer for Agilo including Agilo Pro
2. Virtual Machine for Agilo including Agilo Pro
3. Python Eggs for Agilo including Agilo Pro
4. Source code for Agilo 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. Agilo supports the following versions of python: 2.4, 2.5 and 2.6. If you plan to use python 2.4 please pay attention to the additional database installation instructions.

You need to have python installed before installing Agilo.

External libraries & Dependencies

Agilo for Scrum uses other Open Source libraries and tools, and integrates them to provide various functions. Agilo depends on the following libraries and tools:

Libraries and tools:

• Python setuptools download and install the latest version.
• Trac 0.11 a generic ticketing system (0.11.2+ recommended, 0.12 is not yet supported)
• simplejson (Python 2.4+2.5)

Databases:

• SQLite the default used, doesn't require installation, if you use Python 2.4 you will have to install the python access libraries pysqlite2
• PostgreSQL a very solid and performant database
• 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.

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-<version nr>_PRO-py<your python version>.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

Configuration (both Agilo Open + Agilo Pro)

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

sudo trac-admin /var/lib/trac/web 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/web

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 a method that can be used without having to install any additional utility or web server.

You will need to download an additional utility: trac-digest.py to create a digest password file, than starting tracd with authentication enabled:

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/web permission add username TRAC_ADMIN

Now you can start the Trac daemon with authentication:

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

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:

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

Add this section at the bottom of the config file:

[components]
agilo.* = enabled
# the following lines are only required to use Agilo Pro
agilo_common.* = enabled
agilo_pro.* = enabled

Alternatively you can open your browser at http://localhost:8001, login as admin, and enable all the Agilo (Pro) plugins under "Plugins".

Go back to the server console, and do:

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

When you go back to Trac in the browser, a quick reload should bring you in Agilo. For further information on how to configure Trac in complex environment please refer to the Trac Guide.

Specific Platform & Operating System issues

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

• Installing on Windows
• Installing on Mac OS X
• Installing on Linux from source
• Installing on Linux Debian (Etch)

Installing on Windows (XP and Vista)

Once you downloaded the Agilo source archive, you can expand it using a zip utility.
You can expand the Agilo source archive with a zip utility. In recent versions of Windows such a utility is build-in. Right click the source archive and choose 'Extract to...'

1. Download and install setuptools from here

2. Open a command prompt (cmd) and go to the directory where you extracted the Agilo source, if Agilo is in C:\Agilo\ than you will have to run the following commands:

   C:\> cd Agilo
   C:\> python.exe setup.py install
   

You need to have python.exe in the path, normally it is installed in something like C:\Python25\ but depends on what parameters you set during python installation. Agilo should now be able to download and install all the dependencies without problems.

Installing on Mac OS X

Installation on OS X should now be as easy as with Linux sources. Mac OS X comes with Python 2.5 since Leopard (10.5). If you have an older version of OS X we suggest you manually download and install a 2.5 version of python from the python.org website.

To install Agilo, download the python setuptools, and install them (normally it is enough to uncompress them into a folder, than from the command prompt, inside the folder, type python setup.py install). Once you have the Agilo source, just uncompress into a folder, make sure you have easy_install command (comes with setuptools) in the path (e.g: running the command which easy_install), than from inside agilo source dir:

$ python setup.py install

This should work, including downloading an installing Trac and Genshi for you.

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`

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

Installing on Linux Debian (Etch)

First you need to setup trac and get the dependencies for Agilo:

sudo aptitude install trac

Make a place to hold the trac environments:

sudo mkdir /var/trac

Initialize the trac environment (enter the following commands, name the projects, select the defaults):

sudo trac-admin /var/trac/agilo initenv

Set up user authentication (instructions will be for tracd):

sudo htdigest -c /var/trac/.htdigest admin
sudo htdigest /var/trac/.htdigest user1

Give the user 'admin' admin rights in trac:

sudo trac-admin /var/trac/web permission add admin TRAC_ADMIN

Run the built-in trac server:

sudo tracd --port 8000 --auth=*,/var/trac/.htdigest,trac.local \\
-e /var/trac/

This command will run tracd in the foreground so you can easily spot problems. Run tracd help for info on how to run it in the background.

Subversion Integration

The Agilo for Scrum 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-commit hooks.

Examples on how to create these two scripts are provided in the comments of the agilo_svn_commit_hook.py script.

pre-commit hook

Following an example of a pre-commit hook.

#!/bin/sh
REPOS="$1"
TXN="$2"
# Make sure that the log message contains some text.
SVNLOOK=/usr/bin/svnlook
PYTHON_EGG_CACHE=/var/cache/python
TRAC_ENV="/var/lib/trac/test"
LOG=`$SVNLOOK log -t "$TXN" "$REPOS"`
/where/ever/is/agilo_svn_hook_commit.py -s pre -e "$TRAC_ENV" -l "$LOG" || exit 1

post-commit hook

Following and example of a post-commit hook.

#!/bin/sh
REPOS="$1"
REV="$2"
TRAC_ENV='/var/lib/trac/test/'
/var/lib/svn/local/hooks/agilo_svn_hook_commit.py -s post \
-e "$TRAC_ENV" -r "$REV" || exit 1

For more info on how to configure and use Subversion hooks, refer to the Subversion books 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.py which 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 destination ticket, linking it to the current committed changeset.