ViewVC for Debian
=================
Source changes
--------------
The whole windows/ directory is removed. It contained Windows related files
and prebuild DLL library.
Two modes
---------
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/
AllowOverride None
Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
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
AddHandler mod_python .py
PythonHandler handler
PythonDebug On
AllowOverride None
Order allow,deny
Allow from all
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 Thu, 01 Apr 2010 13:03:23 +1100
-- Lev Lamberov Wed, 09 Nov 2016 23:11:11 +0500
Original INSTALL documentation
==============================
CONTENTS
--------
TO THE IMPATIENT
SECURITY INFORMATION
INSTALLING VIEWVC
APACHE CONFIGURATION
UPGRADING VIEWVC
SQL CHECKIN DATABASE
ENABLING SYNTAX COLORATION
CVSGRAPH CONFIGURATION
IF YOU HAVE PROBLEMS...
TO THE IMPATIENT
----------------
Congratulations on getting this far. :-)
Required Software And Configuration Needed To Run ViewVC:
For CVS Support:
* Python 1.5.2 or later (sorry, no 3.x support yet)
(http://www.python.org/)
* RCS, Revision Control System
(http://www.cs.purdue.edu/homes/trinkle/RCS/)
* GNU-diff to replace diff implementations without the -u option
(http://www.gnu.org/software/diffutils/diffutils.html)
* read-only, physical access to a CVS repository
(See http://www.cvshome.org/ for more information)
For Subversion Support:
* Python 2.0 or later (sorry, no 3.x support yet)
(http://www.python.org/)
* Subversion, Version Control System, 1.3.1 or later
(binary installation and Python bindings)
(http://subversion.apache.org/)
Optional:
* a web server capable of running CGI programs
(for example, Apache at http://httpd.apache.org/)
* MySQL 3.22 and MySQLdb 0.9.0 or later to create a commit database
(http://www.mysql.com/)
(http://sourceforge.net/projects/mysql-python)
* Pygments 0.9 or later, syntax highlighting engine
(http://pygments.org)
* CvsGraph 1.5.0 or later, graphical CVS revision tree generator
(http://www.akhphd.au.dk/~bertho/cvsgraph/)
Quick sanity check:
If you just want to see what your repository looks like when seen
through ViewVC, type:
$ bin/standalone.py -r /PATH/TO/REPOSITORY
This will start a tiny ViewVC server at http://localhost:49152/viewvc/,
to which you can connect with your browser.
Standard operation:
To start installing right away (on UNIX): type "./viewvc-install"
in the current directory and answer the prompts. When it
finishes, edit the file viewvc.conf in the installation directory
to tell ViewVC the paths to your CVS and Subversion repositories.
Next, configure your web server (in the way appropriate to that browser)
to run /bin/cgi/viewvc.cgi. The section
`INSTALLING VIEWVC' below is still recommended reading.
SECURITY INFORMATION
--------------------
ViewVC provides a feature which allows version controlled content to
be served to web browsers just like static web server content. So, if
you have a directory full of interrelated HTML files that is housed in
your version control repository, ViewVC can serve those files as HTML.
You'll see in your web browser what you'd see if the files were part
of your website, with working references to stylesheets and images and
links to other pages.
It is important to realize, however, that as useful as that feature
is, there is some risk security-wise in its use. Essentially, anyone
with commit access to the CVS or Subversion repositories served by
ViewVC has the ability to affect site content. If a discontented or
ignorant user commits malicious HTML to a version controlled file
(perhaps just by way of documenting examples of such), that malicious
HTML is effectively published and live on your ViewVC instance.
Visitors viewing those versioned controlled documents get the
malicious code, too, which might not be what the original author
intended.
For this reason, ViewVC's "checkout" view is disabled by default. If
you wish to enable it, simply add "co" to the list of views enabled in
the allowed_views configuration option.
INSTALLING VIEWVC
------------------
NOTE: Windows users can refer to windows/README for Windows-specific
installation instructions.
1) To get viewvc.cgi to work, make sure that you have Python installed
and a webserver which is capable of executing CGI scripts (either
based on the .cgi extension, or by placing the script within a specific
directory).
Note that to browse CVS repositories, the viewvc.cgi script needs to
have READ-ONLY, physical access to the repository (or a copy of it).
Therefore, rsh/ssh or pserver access to the repository will not work.
And you need to have the RCS utilities installed, specifically "rlog",
"rcsdiff", and "co".
2) Installation is handled by the ./viewvc-install script. Run this
script and you will be prompted for a installation root path.
The default is /usr/local/viewvc-VERSION, where VERSION is
the version of this ViewVC release. The installer sets the install
path in some of the files, and ViewVC cannot be moved to a
different path after the install.
NOTE: while 'root' is usually required to create /usr/local/viewvc,
ViewVC does not have to be installed as root, nor does it run as root.
It is just as valid to place ViewVC in a home directory, too.
NOTE: if your system uses a restrictive umask, you might need to
adjust the permissions of the directory structure that
viewvc-install creates so that, for example, the modules in the
lib/ subdirectory are actually readable by the main programs in the
bin/ subdirectory.
NOTE: viewvc-install will create directories if needed. It will
prompt before overwriting files that may have been modified (such
as viewvc.conf), thus making it safe to install over the top of
a previous installation. It will always overwrite program files,
however.
3) Edit /viewvc.conf for your specific
configuration. In particular, examine the following configuration options:
cvs_roots (for CVS)
svn_roots (for Subversion)
root_parents (for CVS or Subversion)
default_root
root_as_url_component
rcs_dir
mime_types_files
There are some other options that are usually nice to change. See
viewvc.conf for more information. ViewVC provides a working,
default look. However, if you want to customize the look of ViewVC
then edit the files in /templates.
You need knowledge about HTML to edit the templates.
4) The CGI programs are in /bin/cgi/. You can
symlink to this directory from somewhere in your published HTTP server
path if your webserver is configured to follow symbolic links. You can
also copy the installed /bin/cgi/*.cgi
scripts after the install (unlike the other files in ViewVC, the scripts
under bin/ can be moved).
If you are using Apache, then see below at the section titled
APACHE CONFIGURATION.
NOTE: for security reasons, it is not advisable to install ViewVC
directly into your published HTTP directory tree (due to the MySQL
passwords in viewvc.conf).
That's it for repository browsing. Instructions for getting the SQL
checkin database working are below.
APACHE CONFIGURATION
--------------------
1) Locate your Apache configuration file(s).
Typical locations are /etc/httpd/httpd.conf,
/etc/httpd/conf/httpd.conf, and /etc/apache/httpd.conf. Depending
on how Apache was installed, you may also look under /usr/local/etc
or /etc/local. Use the vendor documentation or the find utility if
in doubt.
2) Depending on how your Apache configuration is setup by default, you
might need to explicitly allow high-level access to the ViewVC
install location.
>
Order allow,deny
Allow from all
For example, if ViewVC is installed in /usr/local/viewvc-1.0 on
your system:
Order allow,deny
Allow from all
3) Configure Apache to expose ViewVC to users at the URL of your choice.
ViewVC provides several different ways to do this. Choose one of
the following methods:
-----------------------------------
METHOD A: CGI mode via ScriptAlias
-----------------------------------
The ScriptAlias directive is very useful for pointing
directly to the viewvc.cgi script. Simply insert a line containing
ScriptAlias /viewvc /bin/cgi/viewvc.cgi
into your httpd.conf file. Choose the location in httpd.conf where
also the other ScriptAlias lines reside. Some examples:
ScriptAlias /viewvc /usr/local/viewvc-1.0/bin/cgi/viewvc.cgi
ScriptAlias /query /usr/local/viewvc-1.0/bin/cgi/query.cgi
----------------------------------------
METHOD B: CGI mode in cgi-bin directory
----------------------------------------
Copy the CGI scripts from
/bin/cgi/*.cgi
to the /cgi-bin/ directory configured in your httpd.conf file.
You can override configuration file location using:
SetEnv VIEWVC_CONF_PATHNAME /etc/viewvc.conf
------------------------------------------
METHOD C: CGI mode in ExecCGI'd directory
------------------------------------------
Copy the CGI scripts from
/bin/cgi/*.cgi
to the directory of your choosing in the Document Root adding the following
Apache directives for the directory in httpd.conf or an .htaccess file:
Options +ExecCGI
AddHandler cgi-script .cgi
NOTE: For this to work mod_cgi has to be loaded. And for the .htaccess file
to be effective, "AllowOverride All" or "AllowOverride Options FileInfo"
needs to have been specified for the directory.
------------------------------------------
METHOD D: Using mod_python (if installed)
------------------------------------------
Copy the Python scripts and .htaccess file from
/bin/mod_python/
to a directory being served by Apache.
In httpd.conf, make sure that "AllowOverride All" or at least
"AllowOverride FileInfo Options" are enabled for the directory
you copied the files to.
You can override configuration file location using:
SetEnv VIEWVC_CONF_PATHNAME /etc/viewvc.conf
NOTE: If you are using Mod_Python under Apache 1.3 the tarball generation
feature may not work because it uses multithreading. This works fine
under Apache 2.
----------------------------------------
METHOD E: Using mod_wsgi (if installed)
----------------------------------------
Copy the Python scripts file from
/bin/mod_python/
to the directory of your choosing. Modify httpd.conf with the
following directives:
WSGIScriptAlias /viewvc /bin/wsgi/viewvc.wsgi
WSGIScriptAlias /query /bin/wsgi/query.wsgi
You'll probably also need the following directive because of the
not-quite-sanctioned way that ViewVC manipulates Python objects.
WSGIApplicationGroup %{GLOBAL}
NOTE: WSGI support in ViewVC is at this time quite rudimentary,
bordering on downright experimental. Your mileage may vary.
-----------------------------------------
METHOD F: Using mod_fcgid (if installed)
-----------------------------------------
This uses ViewVC's WSGI support (from above), but supports using FastCGI,
and is a somewhat hybrid approach of several of the above methods.
Especially if fcgi is already being used for other purposes, e.g. PHP,
also using fcgi can prevent the need for including additional modules
(e.g. mod_python or mod_wsgi) within Apache, which may help lessen Apache's
memory usage and/or help improve performance.
This depends on mod_fcgid:
http://httpd.apache.org/mod_fcgid/
as well as the fcgi server from Python's flup package:
http://pypi.python.org/pypi/flup
http://trac.saddi.com/flup
The following are some example httpd.conf fragments you can use to
support this configuration:
ScriptAlias /viewvc /usr/local/viewvc/bin/wsgi/viewvc.fcgi
ScriptAlias /query /usr/local/viewvc/bin/wsgi/query.fcgi
4) [Optional] Add access control.
In your httpd.conf you can control access to certain modules by
adding directives like this:
/">
AllowOverride None
AuthUserFile /path/to/passwd/file
AuthName "Client Access"
AuthType Basic
require valid-user
WARNING: If you enable the "checkout_magic" or "allow_tar" options, you
will need to add additional location directives to prevent people
from sneaking in with URLs like:
http:///viewvc/*checkout*/
http:///viewvc/~checkout~/
http:///viewvc/.tar.gz?view=tar
5) Restart Apache.
The commands to do this vary. "httpd -k restart" and "apache -k
restart" are two common variants. On RedHat Linux it is done using
the command "/sbin/service httpd restart" and on SuSE Linux it is
done with "rcapache restart". Other systems use "apachectl restart".
6) Optional: Protect your ViewVC instance from server-whacking webcrawlers.
As ViewVC is a web-based application which each page containing various
links to other pages and views, you can expect your server's performance
to suffer if a webcrawler finds your ViewVC instance and begins
traversing those links. We highly recommend that you add your ViewVC
location to a site-wide robots.txt file. Visit the Wikipedia page
for Robots.txt (http://en.wikipedia.org/wiki/Robots.txt) for more
information.
UPGRADING VIEWVC
-----------------
Please read the file upgrading-howto.html in the docs/ subdirectory.
SQL CHECKIN DATABASE
--------------------
This feature is a clone of the Mozilla Project's Bonsai database. It
catalogs every commit in the CVS or Subversion repository into a SQL
database. In fact, the databases are 100% compatible.
Various queries can be performed on the database. After installing ViewVC,
there are some additional steps required to get the database working.
1) You need MySQL and MySQLdb (a Python DBAPI 2.0 module) installed.
2) You need to create a MySQL user who has permission to create databases.
Optionally, you can create a second user with read-only access to the
database.
3) Run the /bin/make-database script. It will
prompt you for your MySQL user, password, and the name of database you
want to create. The database name defaults to "ViewVC". This script
creates the database and sets up the empty tables. If you run this on a
existing ViewVC database, you will lose all your data!
4) Edit your /viewvc.conf file.
There is a [cvsdb] section. You will need to set:
enabled = 1 # Whether to enable query support in viewvc.cgi
host = # MySQL database server host
port = # MySQL database server port (default is 3306)
database_name = # name of database you created with make-database
user = # read/write database user
passwd = # password for read/write database user
readonly_user = # read-only database user
readonly_passwd = # password for the read-only user
Note that it's pretty safe in this instance for your read-only user
and your read-write user to be the same.
5) At this point, you need to tell your version control system(s) to
publish their commit information to the database. This is done
using utilities that ViewVC provides.
To publish CVS commits into the database:
Two programs are provided for updating the checkin database from
a CVS repository, cvsdbadmin and loginfo-handler. They serve
two different purposes. The cvsdbadmin program walks through
your CVS repository and adds every commit in every file. This
is commonly used for initializing the database from a repository
which has been in use. The loginfo-handler script is executed
by the CVS server's CVSROOT/loginfo system upon each commit. It
makes real-time updates to the checkin database as commits are
made to the repository.
To build a database of all the commits in the CVS repository
/home/cvs, invoke: "./cvsdbadmin rebuild /home/cvs". If you
want to update the checkin database, invoke: "./cvsdbadmin
update /home/cvs". The update mode checks to see if a commit is
already in the database, and only adds it if it is absent.
To get real-time updates, you'll want to checkout the CVSROOT
module from your CVS repository and edit CVSROOT/loginfo. For
folks running CVS 1.12 or better, add this line:
ALL /bin/loginfo-handler %p %{sVv}
If you are running CVS 1.11 or earlier, you'll want a slightly
different command line in CVSROOT/loginfo:
ALL /bin/loginfo-handler %{sVv}
If you have other scripts invoked by CVSROOT/loginfo, you will
want to make sure to change any running under the "DEFAULT"
keyword to "ALL" like the loginfo handler, and probably
carefully read the execution rules for CVSROOT/loginfo from the
CVS manual.
If you are running the Unix port of CVS-NT, the handler script
need to know about it. CVS-NT delivers commit information to
loginfo scripts differently than the way mainstream CVS does.
Your command line should look like this:
ALL /bin/loginfo-handler %{sVv} cvsnt
To publish Subversion commits into the database:
To build a database of all the commits in the Subversion
repository /home/svn, invoke: "./svndbadmin rebuild /home/svn".
If you want to update the checkin database, invoke:
"./svndbadmin update /home/svn".
To get real time updates, you will need to add a post-commit
hook (for the repository example above, the script should go in
/home/svn/hooks/post-commit). The script should look something
like this:
#!/bin/sh
REPOS="$1"
REV="$2"
/bin/svndbadmin update \
"$REPOS" "$REV"
If you allow revision property changes in your repository,
create a post-revprop-change hook script which uses the same
'svndbadmin update' command as the post-commit script, except
with the addition of the --force option:
#!/bin/sh
REPOS="$1"
REV="$2"
/bin/svndbadmin update --force \
"$REPOS" "$REV"
This will make sure that the checkin database stays consistent
when you change the svn:log, svn:author or svn:date revision
properties.
You should be ready to go. Click one of the "Query revision history"
links in ViewVC directory listings and give it a try.
ENABLING SYNTAX COLORATION
--------------------------
ViewVC uses Pygments (http://pygments.org) for syntax coloration. You
need only install a suitable version of that module, and if ViewVC
finds it in your Python module path, it will use it (unless you
specifically disable the feature by setting use_pygments = 0 in your
viewvc.conf file).
CVSGRAPH CONFIGURATION
----------------------
CvsGraph is a program that can display a clickable, graphical tree
of files in a CVS repository.
WARNING: Under certain circumstances (many revisions of a file
or many branches or both) CvsGraph can generate very huge images.
Especially on thin clients these images may crash the Web-Browser.
Currently there is no known way to avoid this behavior of CvsGraph.
So you have been warned!
Nevertheless, CvsGraph can be quite helpful on repositories with
a reasonable number of revisions and branches.
1) Install CvsGraph using your system's package manager or downloading
from the project home page.
2) Set the 'use_cvsgraph' options in viewvc.conf to 1.
3) You may also need to set the 'cvsgraph_path' option if the
CvsGraph executable is not located on the system PATH.
4) There is a file /cvsgraph.conf that
you may want to edit if desired to set color and font characteristics.
See the cvsgraph.conf documentation. No edits are required in
cvsgraph.conf for operation with ViewVC.
SUBVERSION INTEGRATION
----------------------
Unlike the CVS integration, which simply wraps the RCS and CVS utility
programs, the Subversion integration requires additional Python
libraries. To use ViewVC with Subversion, make sure you have both
Subversion itself and the Subversion Python bindings installed. These
can be obtained through typical package distribution mechanisms, or
may be build from source. (See the files 'INSTALL' and
'subversion/bindings/swig/INSTALL' in the Subversion source tree for
more details on how to build and install Subversion and its Python
bindings.)
Generally speaking, you'll know when your installation of Subversion's
bindings has been successful if you can import the 'svn.core' module
from within your Python interpreter. Here's an example of doing so
which doubles as a quick way to check what version of the Subversion
Python binding you have:
% python
Python 2.2.2 (#1, Oct 29 2002, 02:47:30)
[GCC 2.96 20000731 (Red Hat Linux 7.2 2.96-108.7.2)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> from svn.core import *
>>> "%s.%s.%s" % (SVN_VER_MAJOR, SVN_VER_MINOR, SVN_VER_PATCH)
'1.3.1'
>>>
Note that by default, Subversion installs its bindings in a location
that is not in Python's default module search path (for example, on
Linux systems the default is usually /usr/local/lib/svn-python). You
need to remedy this, either by adding this path to Python's module
search path, or by relocating the bindings to some place in that
search path.
For example, you might want to create .pth file in your Python
installation directory's site-packages area which tells Python where
to find additional modules (in this case, you Subversion Python
bindings). You would do this as follows (and as root):
$ echo "/path/to/svn/bindings" > /path/to/python/site-packages/svn.pth
(Though, obviously, with the correct paths specified.)
Configuration of the Subversion repositories happens in much the same
way as with CVS repositories, only with the 'svn_roots' configuration
variable instead of the 'cvs_roots' one.
IF YOU HAVE PROBLEMS ...
------------------------
If nothing seems to work:
* Check if you can execute CGI-scripts (Apache needs to have an
ScriptAlias /cgi-bin or cgi-script Handler defined). Try to
execute a simple CGI-script that often comes with the distribution
of the webserver; locate the logfiles and try to find hints which
explain the malfunction
* View the entries in the webserver's error.log
If ViewVC seems to work but doesn't show the expected result (Typical
error: you can't see any files)
* Check whether the CGI-script has read-permissions to your
CVS-Repository. The CGI-script generally runs as the same user
that the web server does, often user 'nobody' or 'httpd'.
* Does ViewVC find your RCS utilities? (edit rcs_dir)
If something else happens or you can't get it to work:
* Check the ViewVC home page:
http://viewvc.org/
* Review the ViewVC mailing list archive to see if somebody else had
the same problem, and it was solved:
http://viewvc.tigris.org/servlets/SummarizeList?listName=users
* Check the ViewVC issue database to see if the problem you are
seeing is the result of a known bug:
http://viewvc.tigris.org/issues/query.cgi
* Send mail to the ViewVC mailing list, users@viewvc.tigris.org.
NOTE: make sure you provide an accurate description of the problem
-- including the version of ViewVC you are using -- and any
relevant tracebacks or error logs.