Virtual Host configuration for Bugzilla

Today I found out that there are simpler things than configuring an Apache virtual host for Bugzilla to live in. With a bit of URL rewriting magic, the basics are moderately difficult to solve. What drove me crazy, though, was that the CGI scripts stubbornly generated links to /bugzilla3/skin/[...], instead of just /skin/[...].

After much digging around in the system, I found out that this behaviour is a Debian specific enhancement to the Bugzilla source code. Unfortunately, the enhancement is as good as undocumented, although clever googling will bring up several references to bug reports from people who obviously had similar problems like me but also did not understand how to work around them. For me the crucial hint came from this article which provides a sample Virtual Host configuration that uses the environment variable X_BUGZILLA_WEBPATH. Although the article does not explain what the variable does, just seeing it used gave me an indicator what to look for on my own system.

And now, without further ado, my glorious :-) vhost configuration:

<VirtualHost *:80>
  ServerName bugs.herzbube.ch
  ServerAdmin webmaster@herzbube.ch
  ErrorLog /var/log/apache2/herzbube.ch/error.log
  CustomLog /var/log/apache2/herzbube.ch/access.log combined

  # Allow access to DocumentRoot, but only in the context of this vhost
  <Directory /usr/share/bugzilla3/web/>
    Allow from all
  </Directory>

  # Makes regular web content live in the vhost root (e.g. /skins)
  DocumentRoot /usr/share/bugzilla3/web

  # This environment variable is used by Bugzilla to generate paths to
  # regular web content. Defaults to "/bugzilla3" if not set. The default
  # is hardcoded in /usr/share/perl5/Bugzilla/Constants.pm (look for lines
  # that set "debian_webpath").
  #
  # Note: This is Debian specific and quite undocumented!
  <IfModule mod_env.c>
    SetEnv X_BUGZILLA_WEBPATH "/"
  </IfModule>

  <IfModule mod_rewrite.c>
    RewriteEngine On
    # Replace the HTML redirect file index.html. The redirect will cause the web
    # client to issue another request, which will then trigger the next rule.
    RewriteRule ^/$ /index.cgi [R,L]
    # And now the real thing: A request for something that ends with ".cgi" is
    # transparently rewritten, i.e. the web client does not see what's going on
    # behind the scenes. This is necessary because the CGI scripts don't actually
    # live in the vhost root - they are available from the location
    #   /cgi-bin/bugzilla3
    # thanks to an alias (set elsewhere) that maps /usr/lib/cgi-bin to /cgi-bin
    # on a global level (i.e. all vhosts have access to this).
    #
    # Note 1: Because the pattern says "[^/]+" instead of simply ".+", it is still
    # possible for clients to access the CGI scripts under the location
    # /cgi-bin/bugzilla3. This could be useful, dangereous, or none of both, I am
    # not sure...
    #
    # Note 2: The "PT" flag is required to make this rewrite rule work in
    # conjunction with the alias to /cgi-bin. For details read the Apache docs
    # for mod_rewrite.
    RewriteRule ^/([^/]+\.cgi)$ /cgi-bin/bugzilla3/$1 [PT]
  </IfModule>
</VirtualHost>