I recently set up an installation of ViewVC on my Dreamhost account.  I also found out how to implement a few useful features, and I’m going to share this process here in the hope that you find it useful and in the hope that I can find it when I want to do it again.

This guide will require that you are comfortable doing basic things in the Linux shell (like creating directories, moving files, and basic text editing).  They assume that you are logged into the shell; that’s required for the installation.

Part 1: Install ViewVC

I recommend creating three folders; src, bin, and opt; in your home directory.  Keep program sources and installation files in src, installed programs in opt, and program binaries in bin.

Download ViewVC to your server (in your ~/src folder):

wget http://viewvc.tigris.org/files/documents/3330/46029/viewvc-1.1.1.tar.gz

Extract the archive, change to the new directory, and then run:

./viewvc-install

For the installation path, enter /home/username/opt/viewvc-1.1.1 or something like that.  Don’t enter anything for DESTDIR.

To make ViewVC Web-accessible, first create the subdomain and parent folder where you want ViewVC to reside.

Note, though, that if you want example.com/browse (for example) to be ViewVC, you don’t need to actually create a folder called browse - that folder is sort of a virtual directory we’ll “create” in a few moments.  Also note that if you want ViewVC to be private, you need to create a (real) directory that will be password-protected (in Part 2).

Then, copy /home/username/opt/viewvc-1.1.1/bin/cgi/viewvc.cgi to that Web-accessible directory.

Part 2: Configuring ViewVC

You can follow Dreamhost’s instructions on password-protecting directories to password-protect the directory in which you just installed viewvc.cgi.  Easy as pie.

Next, edit /home/username/opt/viewvc-1.1.1/viewvc.conf. The file is very well-documented; configure and customize as you see fit.

Part 3: Pretty URLs

There are two parts to pretty-URL setup.  First, go to the folder that contains viewvc.cgi and put this code into .htaccess:

RewriteEngine on
RewriteRule ^browse$ viewvc.cgi
RewriteRule ^browse/(.*)$ viewvc.cgi/$1

Second, you have to tell ViewVC what its new name is.  In the same directory, edit viewvc.cgi.  Go down, almost to the bottom of the file, and just before the comment go do the work add:

os.environ['SCRIPT_NAME'] = "/browse"

Part 4: Template Modifications

This is entirely personal preference, but I wanted my name in ViewVC’s footer with my email address.  To do this, edit /home/username/opt/viewvc-1.1.1/templates/include/footer.ext.

I also wanted to get rid of the huge ViewVC logo on each page.  To do this, I just edited it out of header.ext in the same folder.

Part 5: Pretty Code Colors

ViewVC uses the Pygments module for code coloring.  Of course, Dreamhost doesn’t have this installed, but Python makes it easy to create a virtual environment and install “eggs” into it.

First, tell bash to look for binaries in your custom bin directory:

export PATH="${HOME}/bin:${PATH}"

And add this line to ~/.bash_profile:

export PATH="${HOME}/bin:${PATH}"

Change to your ~/src directory and download virtualenv:

wget http://pypi.python.org/packages/2.4/v/virtualenv/virtualenv-1.3.3-py2.4.egg

Create a new directory called virtualenv-1.3.3-py2.4 and move virtualenv-1.3.3-py2.4.egg into it. Change into the directory. These commands will then set up virtual environments for Python 2.5 and Python 2.4.

unzip virtualenv-1.3.3-py2.4.egg
/usr/bin/python2.5 virtualenv.py $HOME
/usr/bin/python2.4 virtualenv.py $HOME

Python 2.5 at Dreamhost doesn’t have Subversion bindings; 2.4 does. We’ll set up Pygments for 2.4:

easy_install-2.4 Pygments

Finally, change to the Web directory containing viewvc.cgi. Edit that file; change the top line to read:

#!/home/username/bin/python2.4

And your pretty code colors magically happen.

Part 6: Make It Faster

You can make Apache serve static content like images and stylesheets; this is faster than letting viewvc.cgi handle it. Edit /home/username/opt/viewvc-1.1.1/viewvc.conf and set the option docroot = /viewvc_static.

In the Dreamhost control panel, go to Domains => Remap Sub-Dir and create a mapping from (your ViewVC domain/folder)/viewvc_static to /home/username/opt/viewvc-1.1.1/templates/docroot.

Enjoy.