= Installing Trac with Subversion on Ubuntu =

The goal of this tutorial is to demonstrate how to setup a Subversion <-> Trac environment on Ubuntu 14.04. The original version of this document was written for 10.04, please see the History link for more details.

A MySQL database and Subversion 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 Subversion installed, you will need to get a few packages listed below. Also, make sure your system is updated.

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

=== Subversion ===

Installing Subversion (SVN) is pretty straight forward. Just run:

{{{
sudo apt-get install subversion
}}}

=== 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 
}}}

== Configuring ==

This part is maybe the most important section on this tutorial. You'll learn how to synchronize Trac and Subversion 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.

=== Creating the Subversion repository for 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 SVN projects:
{{{
sudo mkdir /var/lib/svn
}}}

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

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

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

Start the Subversion server (or use your preferred method):
{{{
sudo svnserve -d
}}}

If you used the command above, you may choose to test that the process is running by issuing:
{{{
sudo lsof -i | grep svnserve
}}}

This should show something like:
{{{
svnserve  13418     root    3u  IPv4 675323469      0t0  TCP *:svn (LISTEN)
}}}

which means the process `svnserve` with PID `13418` was run by `root` and is listening on the `svn` port, which is by default 3690.

Also, checking out revision 0 should be possible:
{{{
svn co svn://localhost/var/lib/svn/YourProject
}}}
The above command will create a directory with the name `YourProject` within your current directory.

'''Note''': until users and authentication have been set up, committing will not be allowed.

=== 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.

=== Initialise the Trac environment ===

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

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

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

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

This command starts a script that requests some information, like the project name and the MySQL connection string. 

The MySQL connection string should look like the following (according to the way we set up the MySQL database in step 2.2).
{{{
mysql://trac:yourpassword@localhost/trac
}}}

Once this is done, you may check the setup by running `tracd`:
{{{
tracd --port=12345 /var/lib/trac/Apollo
}}}

Your browser should show a basic trac install on `http://localhost:12345/Apollo`.

==== Notes ====
You might run into an error when running `trac-admin initenv`, ending in:
{{{
AttributeError: 'NullTranslations' object has no attribute 'add'
}}}

For me, making [http://trac.edgewall.org/ticket/10903#comment:5 this patch] in the listed file solved it.

Pay attention to the question about the location of the Subversion project. This fills the variable `repository_dir` in `trac.ini`. Enter the path as discussed before:
{{{
/var/lib/svn/YourProject
}}}

If the MySQL default engine wasn't InnoDB, you might need to convert the tables that `trac-admin` has just created. Issue the following within your MySQL client:
{{{
USE trac; \
ALTER TABLE `attachment` ENGINE = InnoDB; \
ALTER TABLE `auth_cookie` ENGINE = InnoDB; \
ALTER TABLE `cache` ENGINE = InnoDB; \
ALTER TABLE `component` ENGINE = InnoDB; \
ALTER TABLE `enum` ENGINE = InnoDB; \
ALTER TABLE `milestone` ENGINE = InnoDB; \
ALTER TABLE `node_change` ENGINE = InnoDB; \
ALTER TABLE `permission` ENGINE = InnoDB; \
ALTER TABLE `report` ENGINE = InnoDB; \
ALTER TABLE `repository` ENGINE = InnoDB; \
ALTER TABLE `revision` ENGINE = InnoDB; \
ALTER TABLE `session` ENGINE = InnoDB; \
ALTER TABLE `session_attribute` ENGINE = InnoDB; \
ALTER TABLE `system` ENGINE = InnoDB; \
ALTER TABLE `ticket` ENGINE = InnoDB; \
ALTER TABLE `ticket_change` ENGINE = InnoDB; \
ALTER TABLE `ticket_custom` ENGINE = InnoDB; \
ALTER TABLE `version` ENGINE = InnoDB; \
ALTER TABLE `wiki` ENGINE = InnoDB;
}}}

=== Explicit synchronization of trac and svn ===

'''Note''': For more information about the Explicit Synchronization method, please read TracRepositoryAdmin#ExplicitSync

First, edit the `trac.ini` file, located in `/var/lib/trac/YourProject/conf/`. Modify the `repository_sync_per_request` directive and set it to an empty value.

Now you need to create the Subversion hooks. First, create the ''post-commit'' hook in the `/var/lib/svn/YourProject/hooks/` directory, with the following content:
{{{
#!/bin/sh
export PYTHON_EGG_CACHE="/path/to/cache/dir"
/usr/bin/trac-admin /var/lib/trac/YourProject changeset added "$1" "$2"
}}}

Make sure you give the script execution permissions:
{{{
sudo chmod +x /var/lib/svn/YourProject/hooks/post-commit
}}}

Another important hook script to have is ''post-revprop-change''. The procedures are similar, but the script is slightly different:
{{{
#!/bin/sh
export PYTHON_EGG_CACHE="/path/to/cache/dir"
/usr/bin/trac-admin /var/lib/trac/YourProject changeset modified "$1" "$2"
}}}

Again, make sure you give exec permissions to the script.

Now Trac will be notified about changes you make to your repository and will make them available in the timeline.

=== Instructing Apache to handle Trac ===

Create a new site for your Trac setup.
{{{
sudo cp /etc/apache2/sites-available/000-default.conf /etc/apache2/sites-available/trac.conf
}}}

Apache needs to know how to handle Trac. Use the following block to set up Trac handling:
{{{
<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. You may need to apply this configuration to Apache, then reload the server:
{{{
sudo a2ensite trac
sudo service apache2 reload
}}}

==== Authentication ====

Make sure that the `apache2-utils` package is installed to use `htpasswd`.

In order to allow users to log in to Trac, you will need the following section in your Apache configuration:
{{{
<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:
{{{
sudo htpasswd -c .htpasswd admin
}}}

Go ahead and restart Apache:
{{{
sudo service 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
}}}

=== Automatic reference to the SVN 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 easily access them from the timeline.

Make sure you have the following lines in your `trac.ini` configuration file:
{{{
[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:
{{{
svn commit -m "Refs #123 - added this and that"
}}}

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