ViewVC for Debian
=================

ViewVC is a browser (web) interface for CVS and Subversion version
control repositories.  It generates templatized HTML to present navigable
directory, revision, and change log listings.  It can display specific
versions of files as well as diffs between those versions.

Basically, ViewVC provides the bulk of the report-like functionality you
expect out of your version control tool, but much more prettily than the
average textual command-line program output.

ViewVC can be used in two modes, both of which are supported by this
Debian package:

1. By running the simple stand-alone server "viewvc-standalone", with or
   without a graphical interface, and/or

2. By integrating ViewVC with Apache (or another CGI-enabled HTTP
   server), using either CGI or mod-python.

The second mode is the normal way ViewVC is used.


Stand-alone server
------------------

Running the stand-alone server is as simple as issuing the following
command line:

  viewvc-standalone

You can then point your web browser to http://localhost:49152/viewvc.  A
number of options are available; see viewvc-standalone(1) for more
details.


Integrating with Apache: CGI module
-----------------------------------

By default, the Debian package installs appropriate symbolic links in the
/usr/lib/cgi-bin directory.  If you already have a CGI-enabled HTTP
server installed and configured, all you should need to do is point your
web browser to:

  http://YOUR_WEBSITE/cgi-bin/viewvc.cgi

By default, the configuration file /etc/viewvc/viewvc.conf does NOT have
any CVS or Subversion repositories enabled.  You will need to modify the
cvs_roots and either svn_roots or root_parents variables in that file.

Please note that the ViewVC packages do NOT modify your Apache (or other
HTTP server) configuration.  In particular, if accessing the above URL
shows Python code instead of the ViewVC pages, you will need to enable
CGI processing.  This can be done by running as root:

  a2enmod cgid

and making sure something like the following appears in an appropriate
Apache configuration (such as /etc/apache2/sites-available/default):

  ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/

  <Directory "/usr/lib/cgi-bin">
      AllowOverride None
      Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
      Order allow,deny
      Allow from all
  </Directory>

You will need to restart the Apache web server after making such changes.
See the Apache server documentation for mod_cgi and mod_cgid for more
information.


Integrating with Apache: mod-python module
------------------------------------------

If you are running a high-traffic or high-performance web site, you can
use ViewVC with the Apache mod-python plug-in.  This requires you to
modify the Apache HTTP server configuration (such as in the file
/etc/apache2/sites-available/default).  The appropriate modules are
located in /usr/lib/viewvc/mod-python:

  Alias /viewvc /usr/lib/viewvc/mod-python/viewvc.py
  Alias /viewvc-query /usr/lib/viewvc/mod-python/query.py

  <Directory /usr/lib/viewvc/mod-python>
      AddHandler mod_python .py
      PythonHandler handler
      PythonDebug On

      AllowOverride None
      Order allow,deny
      Allow from all
  </Directory>

You will also need to install the libapache2-mod-python Debian package
and, if needed, enable it:

  a2enmod python

You will need to restart the Apache web server after making such changes.
Once this is done, you should be able to point your web browser to

  http://YOUR_WEBSITE/viewvc

and

  http://YOUR_WEBSITE/viewvc-query

and see the appropriate ViewVC web pages (the second URL is only
applicable if you have installed the viewvc-query package).  You can, of
course, change the URL by changing the first part of the Alias directive.

See the Apache server documentation, as well as documentation for
libapache2-mod-python, for more information.


ViewVC *docroot*
----------------

Ever since release 0.9.4+svn20060318-1, the default configuration in
/etc/viewvc/viewvc.conf makes the ViewVC program itself serve all help
documents, images and style sheets.  These are referenced using *docroot*
as a URL component; see /usr/share/doc/viewvc/docs/url-reference.html for
more information.  By default, the "*docroot*" URL component is mapped to
/etc/viewvc/templates/docroot, which in turn is a symbolic link to
/usr/share/viewvc/docroot.

This state of affairs is somewhat suboptimal, as it causes a performance
hit on the web server: every request for these files needs to go through
the CGI or mod-python module.  It does, however, allow ViewVC to be
shipped more or less "working out-of-the-box", without having to modify
your web server configuration files.

If you wish to avoid the performance penalty of doing things this way,
you will need to uncomment the "docroot" directive in viewvc.conf, give
it an appropriate value and make whatever changes to your HTTP server
configuration you need to expose /usr/share/viewvc/docroot as the value
of "docroot".

Once this is done, content previously served as

  http://YOUR_WEBSITE/cgi-bin/viewvc.cgi/*docroot*/images/logo.png

becomes

  http://YOUR_WEBSITE/$DOCROOT/images/logo.png

where $DOCROOT is the value of the ViewVC "docroot" directive.


 -- John Zaitseff <J.Zaitseff@zap.org.au>  Thu, 01 Apr 2010 13:03:23 +1100