Search:  
Gentoo Wiki

Trac


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc
Warning: There are a lot of bugs in this HOWTO; pay very close attention. Do not only copy and paste the whole thing!

Contents

Introduction

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

Virtual hosting is enabled by the vhosts flag. However, if you do not want to use virtual hosting, dev.domain.tld can be replaced with localhost.

Emerging Trac

The current version (~arch on some platforms) has these USE flags:

www-apps/trac-0.10.4  USE="cgi fastcgi mysql postgres sqlite enscript silvercity vhosts"

If you're using multiple domains on your server, make sure you have the vhosts flag set. The initial portion of this How-To uses the cgi USE flag, but the fastcgi and mod_python methods are covered briefly at the end of this document.


Once the correct USE flags are set:

emerge trac -av

The official sitehas more information about choosing which components to use when installing trac.

Installing each instance of Trac

Note: This step is not necessary for installations that do not use a virtual host. A single instance of Trac can support multiple projects and svn repositories with one installation.

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.10.3.1 is the last version):

webapp-config -I -h dev.domain.tld -d project1/trac trac 0.10.4
webapp-config -I -h dev.domain.tld -d project2/trac trac 0.10.4
...
# To use localhost
webapp-config -I -d project1/trac trac 0.10.3.1

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

For more information about webapp-config:

man webapp-config

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.

Setting up Subversion repositories and Trac environments

Now, let's create Subversion repositories, one for each project we have. If you are already using Subversion and have an existing svn repository, you can skip the svnadmin create step below.

Creating Subversion repositories

For more detailed information on how to create a your repositories, use Subversion as a reference.

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

svnadmin create /var/svn/project1

Creating Trac environments

Each project needs a Trac environment; by default, Gentoo uses /var/lib/trac/.

Create a Trac environment for project1 by doing:

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

trac-admin will then prompt you for information specific to this trac project. When trac-admin asks for the path to your svn repository, use the path that you created with the svnadmin command above.

Once trac-admin is complete, adjust the ownership of /var/lib/trac/project1/, because Trac needs read and write permissions for the directory:

chown -R apache /var/lib/trac/project1/
Note: Now that the Trac environment for your project has been set-up, you may wish to test it. The Trac installation includes a small web server. Although this How-To continues on to configure Apache, we can verify that trac is working by using trac's builtin server:
tracd --port 8000 /var/lib/trac/project1
Then use your web browser to view http://localhost:8000/

Repeat the above steps for each project you have.

Configuring Apache

Here is my configuration for the name-based vhost.

Vhost configuration

Note: This step is only necessary for installations using virtual hosts. If you do not have the vhost USE flag enabled, you can skip this step and continue to the per-project configuration below.


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

File: /etc/apache2/vhosts.d/00_default_vhost.conf
<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/.

Make sure your vhosts.conf file is being loaded by apache. You may need to uncomment the line:

Include conf/vhosts/vhosts.conf

in your main httpd.conf or apache2.conf

Per-project configuration

Next, Apache needs to know some specific directives that define a project. This example should be repeated for each project.

If you are using the vhost USE flag and have multiple virtual hosts, vhost.conf is a resonable place to store each host's configuration:

File: /etc/apache2/vhosts.d/00_default_vhost.conf
        ###
        ### 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>

        # Configure how Trac will authenticate users
        <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.

If you are not using the vhost USE flag, you may wish to keep all of Apache's trac related configuration in a single conf file. Creating the trac.conf file below isn't required, and these configuration options could just as easily be included in /etc/apache2/httpd.conf.

File: /etc/apache2/modules.d/99_trac.conf
        ScriptAlias /trac /var/www/localhost/cgi-bin/trac.cgi

        # This location should match the ScriptAlias above, if you want trac 
        # to be hosted at http://localhost/projects instead of http://localhost/trac
        # change both the ScriptAlias and the Location.
        <Location "/trac">
                SetEnv TRAC_ENV "/var/lib/trac/project1"
                # Comment TRAC_ENV above and uncomment TRAC_ENV_PARENT_DIR
                # below to enable one Trac installation to handle multiple
                # Trac projects
                #SetEnv TRAC_ENV_PARENT_DIR "/var/lib/trac/"
        </Location>

        # Configure how Trac will authenticate users
        <Location "/cgi-bin/trac.cgi/login">
                # Using htpasswd for authentication
                AuthType Basic
                AuthName "trac"
                # Create an htpasswd file for trac users and
                # reference it here:
                AuthUserFile /etc/apache2/trac.htpasswd
                Require valid-user
        </Location>

For more information on Apache configuration of Trac using cgi, see: http://trac.edgewall.org/wiki/TracCgi

Now, some comments.

More Information on Directives for Trac

In the examples shown above, we needed to specify several directives for Trac to work properly.

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 the Location tag the variable is listed under (in this case, project1).

In this example, I'm storing every Trac environment under /var/lib/trac/, so the projectX Trac environment can be found under /var/lib/trac/projectX/.


Note: There is more than one possible location for Apache directives, so the filenames have been left off of the examples below to help avoid confusion. These can be added in any of the conf files processed by Apache.


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

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


We need to set the TRAC_ENV for the entire /project1 web space, using the following:

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

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.


It is necessary to escape the URI /project1/login, which used by Trac to authenticate users. I've set a Location for it, and placed the authentication specifics 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>

The AuthType, AuthName and Require directives are needed. In this example, we are using LDAP, but you can use any supported Apache authentication method.

Here, we are 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.

For more information on Apache authenticaion, see the Apache Documentation or HOWTO Apache2 and mod auth ldap

Mapping Static Resources

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.

File:
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:

File: /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.

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.

File:
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.

File:
        <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.

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:

File: 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:

File: 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.

If you would like to use the default trac css files create the following alias in your apache config.

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

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.

Using FastCGI

FastCGI offers much higher performance than mod_python and vanilla .cgi. It is in portage so just install mod_fastcgi and compile Trac with FastCGI support:

Code: Emerging Trac with FastCGI support
emerge mod_fastcgi
echo "www-apps/trac fastcgi" >> /etc/portage/package.use
emerge trac

Enable FastCGI in your apache config (add this line below any other apache2_opts defines)

File: /etc/conf.d/apache2
APACHE2_OPTS="$APACHE2_OPTS -D FASTCGI"

Most of the Apache vhost config outlined above can be used but you must change the script alias line to point to trac.fcgi:

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

also add somthing along the following lines to httpd.conf

File: /etc/apache/httpd.conf
FastCgiServer /var/www/dev.domain.tld/cgi-bin/trac.fcgi -idle-timeout 120 \
       -initial-env TRAC_ENV=/var/lib/trac/project -processes 5

This will prefork 5 instances of Trac allowing a snappy web experience.

You may encounter a Python error while trying to load the site that refers to TRAC_ENV or TRAC_ENV_PARENT_DIR being unset. This can help the problem if you add it to the top of /var/www/site.name.tld/cgi-bin/trac.fcgi:

File: /var/www/site.name.tld/cgi-bin/trac.fcgi
import os
os.environ['TRAC_ENV'] = "/path/to/project/files"

Use the same directory that you used during trac-admin /path/to/project/files initenv.

Using Mod_Python

Using mod_python makes the config much easier! Make sure mod_python is enabled (Apache Modules mod python) and then the following directives in your httpd.conf file will give support for all of your trac instances. The example assumes you have trac repositories set up in /var/trac and the Apache root in /var/www. The LocationMatch block is if you require authentication. http://localhost/projects should then list all of your trac projects.

File: /etc/apache2/httpd.conf
<Location /projects>
    SetHandler mod_python
    PythonHandler trac.ModPythonHandler
    PythonOption TracEnvParentDir /var/trac
    PythonOption TracUriRoot /projects
</Location>

<LocationMatch "/[^/]+/login">
    AuthType Basic
    AuthName "Trac"
    AuthUserFile /var/www/conf/trac-users
    Require valid-user
</LocationMatch>

Note that the PythonHandler is set to trac.ModPythonHandler - this is correct for Trac 0.8.4 (the current Gentoo emerge as I write this), but will need changing to trac.web.modpython_frontend in Trac 0.9.x.

Notes

Retrieved from "http://www.gentoo-wiki.info/Trac"

Last modified: Wed, 03 Sep 2008 23:52:00 +0000 Hits: 42,489