Installing and Running Trac on Gentoo

Trac is included in portage as of 2004/04/29. Installing is as simple as:

  emerge trac

Past that, normal Trac configuration should apply.

Someone's put together a really nice guide to setting up trac on gentoo ​here.

There were a couple of little things that were required to make Trac on Gentoo work.

• Make sure your berkdb and python use flags are set to 'true'!

• If you have any trouble, go down to the bottom and start emerging components this is how I figured out that the svn bindings for Python weren't building, etc.. Be sure to run the python update script if needed.

• Once built, your alias for /trac will be different from the TracInstall doc. It'll look something like this:

Alias /trac "/var/www/yourdomainhere/htdocs/trac/"

This makes Trac all pretty, like you're used to seeing! Otherwise it's got essentially no layout.

2005-03-18: It looks like the link to the "​really nice guide" doesn't work.
There is still a version on Google Cache. Maybe we should copy it to this page!?

Installing Trac on Gentoo for multiples projects

I wanted to use Trac for each development project I had, and configure the Apache 2 webserver on my Gentoo Linux box to create a (name-based) virtual host that would hold every Trac instance (more information on virtual hosts can be found here). The following is what I did, as root, to make the whole thing work.

Say the development vhost is known as dev.domain.tld. Basically I wanted to access to each project website via ​http://dev.domain.tld/projectX/.

1. Emerging Trac

Since mod_python support is a new feature of 0.7.1 and is still experimental, I'm not going to use it and I'll stick with a simple CGI installation. You'll see that using a CGI installation together with webapp-config on a single vhost causes a restriction: the version of every Trac instance has to be unique. Using mod_python may throw away this restriction, I'll update this document as soon as I test it.

emerge trac

Obviously, I had to edit /etc/portage/package.keywords to make stuff available to Portage, because I'm running a stable (x86) version of Gentoo.

app-text/silvercity ~x86 dev-libs/clearsilver ~x86 www-apps/trac ~x86

2. Installing each instance of Trac

Say I have now a bunch of projects, known as project1, project2, … I use the webapp-config tool to install each instance of Trac 0.7.1:

webapp-config -I -h dev.domain.tld -d project1/trac trac 0.7.1 webapp-config -I -h dev.domain.tld -d project2/trac trac 0.7.1 …

Don't forget the /trac part for the directory path.

For each project, symlinks (or hardlinks, depending on your webapp-config configuration) are created in /var/www/dev.domain.tld/htdocs/projectX/trac/ and /var/www/dev.domain.tld/htdocs/projectX/trac/css/, making images and css files available in the web space, under ​http://dev.domain.tld/projectX/trac/ and ​http://dev.domain.tld/projectX/trac/css/. Symlinks are known to work with Trac.

Furthermore, a symlink (or hardlink) to trac.cgi is created each time in /var/www/dev.domain.tld/cgi-bin/, regardless of the instance. This webapp-config issue can be restricting if you want to install different versions of Trac on the same vhost, because this way you get only one trac.cgi per vhost. As a result, you need to install the same version of Trac everywhere on your vhost.

3. Setting up Subversion repositories and Trac environments

Now, let's create Subversion repositories, one for each project we have. 3.1. Creating Subversion repositories

Let's say we want our repositories to live under /var/svn/. Issue the following commands to create a repository for project1:

svnadmin create /var/svn/project1
chown -R apache /var/svn/project1

Changing the ownership of the repository is important: as svn commits will be handled by Apache, the apache user needs to have write access to the repository.

Also, if you built Subversion from Apache 2.0.50, you may want to do the following (that's because APR from Apache 2.0.50 has a bug and set created directories to 1755 instead of regular 0755):

find /var/svn/project1 -type d -exec chmod 755 {} \;

Repeat these steps for each project you have. 3.2. Creating Trac environments

Each project needs a Trac environment too, and we want them to live under /var/lib/trac/. If it doesn't already exist, we create the directory:

mkdir /var/lib/trac/

Then we create a Trac environment for project1 by doing:

trac-admin /var/lib/trac/project1/ initenv

Just answer the question to fill you needs, and indicates the right Subversion repository created in the previous step. Adjust the ownership of var/lib/trac/project1/, because Trac needs to write in it:

chown -R apache /var/lib/trac/project1/

Repeat the above steps for each project you have.

4. Configuring Apache

Here is my configuration for the name-based vhost. 4.1. Vhost configuration

The first part of the configuration is relative to the vhost itself:

<VirtualHost *:80>
        ServerName dev.domain.tld
        DocumentRoot /var/www/dev.domain.tld/htdocs

        <Directory /var/www/dev.domain.tld/htdocs>
                AllowOverride all
                Options +Indexes +FollowSymLinks

                <IfModule mod_access.c>
                        Order Deny,Allow
                </IfModule>
        </Directory>

        <Directory /var/www/dev.domain.tld/cgi-bin>
                Options +FollowSymLinks

                <IfModule mod_access.c>
                        Order Deny,Allow
                </IfModule>
        </Directory>

Here I set the name-based vhost and the access policies. Note that +Indexes on htdocs/ isn't needed; however, in case webapp-config created symlinks, +FollowSymLinks is necessary, both on htdocs/ and cgi-bin/. 4.2. Per-project configuration

Next, there are per-project specific directives that define a project. This example has to be repeated for each project.

###
### project1
###
Alias /project1/dox /var/www/dev.domain.tld/htdocs/project1/dox

<Location /project1/svn>
      <IfDefine SVN>
              DAV svn
              SVNPath /var/svn/project1
              SVNIndexXSLT /project1/trac/svnindex.xsl
      </IfDefine>

      <LimitExcept GET PROPFIND OPTIONS REPORT>
              AuthType Basic
              AuthName "project1::svn"

         <IfModule mod_auth_ldap.c>
              AuthLDAPURL ldap://ldap.domain.tld:389/ou=users,dc=domain,dc=tld?uid?one
              Require group cn=project1,ou=dev,ou=groups,dc=domain,dc=tld
         </IfModule>
      </LimitExcept>
</Location>

<Location /project1>
         SetEnv TRAC_ENV "/var/lib/trac/project1"
</Location>

<Location /project1/login>
         AuthType Basic
         AuthName "project1::trac"

       <IfModule mod_auth_ldap.c>
            AuthLDAPURL ldap://ldap.domain.tld:389/ou=users,dc=domain,dc=tld?uid?one
            Require group cn=project1,ou=dev,ou=groups,dc=domain,dc=tld
       </IfModule>
</Location>

Alias /project1/trac /var/www/dev.domain.tld/htdocs/project1/trac
ScriptAlias /project1 /var/www/dev.domain.tld/cgi-bin/trac.cgi

As you can see, I make a big use of Locations and Aliases. Now, some comments. 4.2.1. Trac stuff

We need several directives to make Trac work. The first thing is to set the TRAC_ENV environment variable. This variable indicates to trac.cgi the location of the Trac environment corresponding to project1 in the filesystem. Actually, I'm storing every Trac environment under /var/lib/trac/, so the projectX Trac environment can be found under /var/lib/trac/projectX/.

That's why we set the TRAC_ENV for the entire /project1 web space, with the following:

        <Location /project1>
                SetEnv TRAC_ENV "/var/lib/trac/project1"
        </Location>

Then we redirect every request for /project1/* to trac.cgi with the ScriptAlias directive:

        ScriptAlias /project1 /var/www/dev.domain.tld/cgi-bin/trac.cgi

This needs to be placed at the very end of the project configuration, because it is a default redirection for every request made to /project1/*. Special configuration for some URIs will be placed before this directive to be taken in account.

A needed escaping URI is /project1/login, used by Trac to authenticate users. I've set a Location for it, and placed the authentication stuff inside:

<Location /project1/login>
       AuthType Basic
       AuthName "project1::trac"

       <IfModule mod_auth_ldap.c>
          AuthLDAPURL ldap://ldap.domain.tld:389/ou=users,dc=domain,dc=tld?uid?one

          Require group cn=project1,ou=dev,ou=groups,dc=domain,dc=tld
       </IfModule>
</Location>

AuthType, AuthName and Require directives are needed, then you may use the user referential you want (here I'm using a LDAP server). I'm telling Apache that a user may authenticate if he belongs to the project1 group. This way, you can create groups for each project you have, and make users belong to the groups corresponding to the projects they work on.

The last thing to make Trac work is to map a URI to the images and css files location, again to escape the trac.cgi handler.

        Alias /project1/trac /var/www/dev.domain.tld/htdocs/project1/trac

As we installed the Trac instance to /project1/trac it should work. Well, actually we need to modify the trac.ini configuration file for Trac, in order to change the way URIs are generated. Just edit /var/lib/trac/project1/conf/trac.ini:

htdocs_location = /project1/trac

Ok, that should be enough to use Trac. Point a browser to ​http://dev.domain.tld/project1 and voila. 4.2.2. External components to Trac

Then I felt the need to add external pages to Trac, like a Doxygen component that would contain the generated documentation from the code source of project1. I wanted to find this documentation under /project1/dox.

We need to escape trac.cgi again, by setting a new Alias before the ScriptAlias directive. There we map the /project1/dox web space to the /var/www/dev.domain.tld/htdocs/project1/dox file space.

        Alias /project1/dox /var/www/dev.domain.tld/htdocs/project1/dox

By the way, I've automated the creation of the Doxygen documentation by using the post-commit hook of Subversion, and doing a checkout followed by a "doxygenation" inside /var/www/dev.domain.tld/htdocs/project1/dox.

Last but not least, I wanted to make the Subversion repository accessible via /project1/svn, with anonymous checkouts and authenticated commits. We need a Location to place the mod_dav_svn stuff and the authentication directives.

<Location /project1/svn>
       <IfDefine SVN>
           DAV svn
           SVNPath /var/svn/project1
           SVNIndexXSLT /project1/trac/svnindex.xsl
       </IfDefine>

       <LimitExcept GET PROPFIND OPTIONS REPORT>
            AuthType Basic
            AuthName "project1::svn"

        <IfModule mod_auth_ldap.c>
            AuthLDAPURL ldap://ldap.domain.tld:389/ou=users,dc=domain,dc=tld?uid?one
            Require group cn=project1,ou=dev,ou=groups,dc=domain,dc=tld
        </IfModule>
       </LimitExcept>
</Location>

As you can see, I'm storing my Subversion repositories under /var/svn/, so I set the name of the project1 repository to /var/svn/project1. Obviously, it is the filepath I will use when I create the project1 Trac environment.

Instructions for limiting the write access to the repository can be found on the SVN Book. I'm using the same authentication scheme than the previous one, to be consistent between Trac users and SVN users. 4.2.3. Integrating these external components inside Trac

We can use the per-project templates of Trac to integrate, for example, the Doxygen documentation inside Trac. They are located under /var/lib/trac/project1/templates/. We may want to insert a link to /project1/dox in the header, and have the following site_header.cs:

<?cs
####################################################################
# Site header - Contents are automatically inserted above Trac HTML
?>
<div>
<a id="dox" href="/<?cs var:project.name?>/dox">Doxygen documentation</a>
</div>

And why not using a per-project css file? Let's edit site_css.cs:

<?cs
##################################################################
# Site CSS - Place custom CSS, including overriding styles here.
?>
@import url("<?cs var:htdocs_location ?>css/<?cs var:project.name?>.css");

This way, we can create a /var/www/dev.domain.tld/htdocs/project1/trac/css/project1.css file (among with symlinks), and personalize the Trac layout. These per-projects file won't be deleted by webapp-config, so it's a good thing.

5. Conclusion

By copy/pasting the configuration for one project, we can set up as many projects as we want, each with their own web space, Subversion access, authentication scheme (users referential and authentication method) and layout.

Corrections and suggestions about this documentation are welcome.