= Installing Trac with Git on Ubuntu =

The goal of this tutorial is to demonstrate how to setup a Git <-> Trac environment on Ubuntu 10.04.03. A MySQL database and Git Python bindings are going to be used.
Please note that only general instructions are provided, and it's assumed that you have basic knowledge on Linux administration.

'''Note''': for a full installation tutorial on Trac, please read TracInstall

[[PageOutline(2-3,Installation Steps,inline)]]

== Installing the software and its dependencies ==

=== Base packages ===

In order to get Trac and Git installed, you will need to get a few packages listed below. Also, make sure your system is updated.

{{{
sudo apt-get install apache2 apache2-utils libapache2-mod-python python-setuptools python-genshi mysql-server python-mysqldb
}}}

=== Git ===

Installing Git Version Control is pretty straight forward. Just run:

{{{
sudo apt-get install git-core 
}}}

=== Trac ===

There are different ways of installing Trac. But since this tutorial is focused on Ubuntu, you'll do the Ubuntu way:

{{{
sudo apt-get install trac trac-git
}}}

== Configuring ==

This part is maybe the most important section on this tutorial. You'll learn how to synchronize Trac and Git in order to be able to see on your Trac Project website what's going on in your repository and also how to automate some tasks.

=== Git ===

==== Creating the project ====

You may already know how to do this, but let's make a review just in case.

Create a directory to store the Git projects:
{{{
sudo mkdir /var/lib/git
}}}

Create a the project directory:
{{{
sudo mkdir /var/lib/git/YourProject
}}}

Use git to create a project in the previously created folder:
{{{
sudo git init /var/lib/git/YourProject
}}}

In order to perform some changes to the project, Trac needs write access to it:
{{{
sudo chown -R www-data /var/lib/git/YourProject
}}}

=== Setup the MySQL database ===

Before configuring your new Trac project, you'll need to setup the MySQL database.

Log into MySQL database, using the root credentials you've setup during the installation:
{{{
mysql -u root -p
}}}

Once logged in, create the database for Trac:
{{{
CREATE DATABASE trac DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
}}}

Now create the username which Trac is going to use to connect to the database:
{{{
GRANT ALL ON trac.* TO trac@localhost IDENTIFIED BY 'yourpassword';
}}}

You can now exit the MySQL command line.

=== Trac ===

==== Initiate the enviroment

Let's create a directory to contain all the Trac project (just like we did for Git projects).
{{{
sudo mkdir /var/lib/trac
}}}

Create a directory where to store the Trac project in:
{{{
sudo mkdir /var/lib/trac/YourProject
}}}

Use trac-admin to create the new project:
{{{
sudo trac-admin /var/lib/trac/YourProject initenv
}}}

Also you will need to fill in some information, like the project name. It will ask you for the MySQL connection string. Input the following (according to the way we did setup the MySQL database in the step 2.2).
{{{
mysql://trac:yourpassword@localhost/trac
}}}

Be sure to specify git as your Repository type, as svn is the default:
{{{
Repository type [svn]> git
}}}

Pay attention to the question about the location of the Git project. Enter the path as discussed before:
{{{
/var/lib/git/YourProject
}}}

As you did for Git, change the ownership of the project files to Apache's user www-data:
{{{
sudo chown -R www-data:www-data /var/lib/trac/YourProject
}}}

==== Explicit syncronization ====

'''Note''': If you require Explicit Sync, please read TracRepositoryAdmin#ExplicitSync

=== Apache ===

==== Set up Trac handling ====

Apache needs to know how to handle Trac. Add the following block to your /etc/apache2/sites-enabled/000-default config file just before the closing </VirtualHost> Directive:
{{{
<Location /projects> #set up Trac handling
    SetHandler mod_python
    PythonHandler trac.web.modpython_frontend
    PythonOption TracEnvParentDir /var/lib/trac
    PythonOption TracUriRoot /projects
</Location>
}}}

Note that it's pointing to the main Trac directory. It means it will expose all of your Trac projects.

==== Authentication ====

In order to allow users to log in Trac, you will need the following section in your Apache configuration.  Again, place this in /etc/apache2/sites-enabled/000-default just above the closing </VirtualHost> mark:
{{{
<LocationMatch "/projects/[^/]+/login">
    AuthType Basic
    AuthName "Trac"
    AuthUserFile /var/lib/trac/.htpasswd
    Require valid-user
</LocationMatch>
}}}

You should now create the .htpasswd file, with an admin user:
{{{
cd /var/lib/trac
sudo htpasswd -c .htpasswd admin
}}}

Go ahead and restart Apache:
{{{
sudo /etc/init.d/apache2 restart
}}}

Finally, you must grant admin rights to the user you've just created:
{{{
sudo trac-admin /var/lib/trac/YourProject permission add admin TRAC_ADMIN
}}}

== Enable Git module under trac admin ==

You will need to enabled the TracGit GitConnector component in Trac.  To enable the plugin, log into the admin section of your site using a web browser (http://localhost/projects/ or from another host using the IP of your ubuntu box if you do not have a Browser/GUI on your box) using the credentials you previously created.  While logged in as admin, select Admin -> General -> Plugins and at the bottom of the plugin list check "Enable" next to GitConnector.  Click "Apply changes" to activate the plugin.

== Automatic reference to the Git changesets in Trac tickets ==

Something useful is to reference tickets on your commits. That way you can keep a better track of them and also easly access them from the timeline.

Make sure you have the following line in your trac.ini configuration file (under /var/lib/trac/YourProject/conf):
{{{
[components]
tracopt.ticket.commit_updater.* = enabled
}}}

Now, whenever you commit some change related to a ticket, use ''Refs #tn'' to reference this changeset in #tn ticket. For example:
{{{
git commit -m "Refs #123 - added this and that"
}}}

In order to mark a ticket as fixed, use the following:
{{{
git commit -m "Fixes #123 - Removed an infinite loop which was causing the application to freeze"
}}}