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.
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 Trac 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, a generic ticketing system (0.11.2+ recommended, 0.12 supported since Agilo Pro 1.3.1)
simplejson (only if you are using Python 2.4 or 2.5)
Databases:
SQLite, the default used though not recommended for production use, 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 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 tracs install guide for Trac 0.11 and for Trac 0.12.
The following instructions assume you have Trac already installed and are logged into the Trac server.
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-...
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.
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
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
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.
This documentation is the result of a collaborative work between agile42 team and all the Agilo for Trac users that contributed to solve a large amount of issues, participating actively in our User Group.
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...'
Download and install setuptools from here
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.
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), then from inside agilo source dir:
$ python setup.py install
This should work, including downloading an installing Trac and Genshi for you.
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.
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
(Please note: some versions of htdigest require you to add a a realm parameter of 'trac-local' )
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.
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.
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.
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 destination ticket, linking it to the current committed changeset.