vitalif
/
viewvc-4intranet
mirror of https://github.com/vitalif/viewvc-4intranet
1
0
Fork 0
Code Issues Releases Wiki Activity
viewvc-4intranet/INSTALL

489 lines
19 KiB
Plaintext
Raw Blame History

CONTENTS
--------
TO THE IMPATIENT
INSTALLING VIEWCVS
APACHE CONFIGURATION
UPGRADING VIEWCVS
SQL CHECKIN DATABASE
ENSCRIPT CONFIGURATION
CVSGRAPH CONFIGURATION
IF YOU HAVE PROBLEMS...
TO THE IMPATIENT
----------------
Congratulations on getting this far. :-)
Required Software And Configuration Needed To Run ViewCVS:
For CVS Support:
* Python 1.5.2 or later
(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
(http://www.python.org/)
* Subversion, Version Control System, 1.2.0 or later
(binary installation and Python bindings)
(http://subversion.tigris.org/)
Optional:
* a web server capable of running CGI programs
(for example, Apache at http://httpd.apache.org/)
* MySQL to create and query a commit database
(http://www.mysql.com/)
(http://sourceforge.net/projects/mysql-python)
* Enscript, code colorizer
(http://people.ssh.com/mtr/genscript/)
* CvsGraph 1.4.0 or later, graphical CVS revision tree generator
(http://www.akhphd.au.dk/~bertho/cvsgraph/)
GUI Operation:
If you just want to see what your CVS repository looks like with
ViewCVS, type "./standalone.py -g -r /PATH/TO/CVS/ROOT". This
will start a tiny webserver serving at http://localhost:7467/.
PLEASE NOTE: This requires Python with thread support enabled and
the Tkinter GUI. If you don't have one of these, omit the '-g' option.
Standard operation:
To start installing right away (on UNIX): type "./viewcvs-install"
in the current directory and answer the prompts. When it
finishes, edit the file viewcvs.conf in the installation directory
to tell viewcvs the paths to your CVS repositories. Next,
configure your web server to run <INSTALL>/cgi/viewcvs.cgi, as
appropriate for your web server. The section `INSTALLING VIEWCVS'
below is still recommended reading.
INSTALLING VIEWCVS
------------------
1) To get viewcvs.cgi to work, make sure that you have Python 1.5 or
greater 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).
You need to have RCS installed. Specifically, "rlog", "rcsdiff",
and "co". This script was tested against RedHat's rcs-5.7-10.rpm
Someone running HP-UX reported problems, that rcs doesn'nt honour
the setting of $PATH to find the diff utility. Please test, if
"rcsdiff -u" works. If not you might have to recompile RCS.
Note, that the viewcvs.cgi script needs to have READ-ONLY, physical
access to the CVS repository (or a copy of it). Therefore, rsh/ssh or
pserver access to the repository will not work.
For the more human readable diff formats you need a modern diff utility.
If you are using Linux, this is no problem. But on commercial unices
you might want to install GNU-diff to be able to use unified or
side-by-side diffs.
If you want to use cvsgraph, you have to obtain and install this
separately. See below. This was tested with cvsgraph-1.5.1.
For the checkin database to work, you will need MySQL >= 3.22,
and the Python DBAPI 2.0 module, MySQLdb. This was tested with
MySQLdb 0.9.1.
2) Installation is handled by the ./viewcvs-install script. Run this
script and you will be prompted for a installation root path.
The default is /usr/local/viewcvs-VERSION, where VERSION is
the version of this ViewCVS release. The installer sets the install
path in some of the files, and ViewCVS cannot be moved to a
different path after the install.
Note: while 'root' is usually required to create /usr/local/viewcvs,
ViewCVS does not have to be installed as root, nor does it run as root.
It is just as valid to place ViewCVS in a home directory, too.
Note: viewcvs-install will create directories if needed. It will
prompt before overwriting files that may have been modified (such
as viewcvs.conf), thus making it safe to install over the top of
a previous installation. It will always overwrite program files,
however.
3) Edit <VIEWCVS_INSTALLATION_DIRECTORY>/viewcvs.conf for your specific
configuration. In particular, examine the following configuration options:
cvs_roots
default_root
rcs_path
mime_types_file
There are some other options that are usually nice to change. See
viewcvs.conf for more information. ViewCVS provides a working,
default look. However, if you want to customize the look of ViewCVS
then edit the files in <VIEWCVS_INSTALLATION_DIRECTORY>/templates.
You need knowledge about HTML to edit the templates.
4) The CGI programs are in <VIEWCVS_INSTALLATION_DIRECTORY>/www/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 <VIEWCVS_INSTALLATION_DIRECTORY>/www/cgi/*.cgi scripts
after the install (unlike the other files in ViewCVS, the scripts under www/
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 ViewCVS
directly into your published HTTP directory tree (due to the MySQL
passwords in viewcvs.conf).
5) That's it for repository browsing. Instructions for getting the
SQL checkin database working are below.
APACHE CONFIGURATION
--------------------
1) Find out where the web server configuration file is kept. On
SuSE Linux it is /etc/httpd/httpd.conf, On RedHat Linux 7.3 it
is /etc/httpd/conf/httpd.conf. On other unices you may look
at /usr/local/etc or /etc/local. Use the vendor documentation
or the find utility, if in doubt.
Either METHOD A:
2) The ScriptAlias directive is very useful for pointing
directly to the viewcvs.cgi script. Simply insert a line containing
ScriptAlias /viewcvs <VIEWCVS_INSTALLATION_DIRECTORY>/www/cgi/viewcvs.cgi
into your httpd.conf file. Choose the location in httpd.conf where
also the other ScriptAlias lines reside. Some examples:
ScriptAlias /viewcvs /usr/local/viewcvs-1.0/www/cgi/viewcvs.cgi
ScriptAlias /query /usr/local/viewcvs-1.0/www/cgi/query.cgi
continue with step 3).
or alternatively METHOD B:
2) Copy the CGI scripts from
<VIEWCVS_INSTALLATION_DIRECTORY>/www/cgi/*.cgi
to the /cgi-bin/ directory configured in your httpd.conf file.
continue with step 3).
and then there's METHOD C:
2) Copy the CGI scripts from
<VIEWCVS_INSTALLATION_DIRECTORY>/www/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"
need to have been specified for the directory.)
continue with step 3).
or if you've got Mod_Python installed you can use METHOD D:
2) Copy the Python scripts and .htaccess file from
<VIEWCVS_INSTALLATION_DIRECTORY>/www/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.
Note: If you are using Mod_Python under Apache 1.3 the tarball generation
and enscript colorizing features may not work because they use
multithreading. They do work fine with Apache 2.
continue with step 3).
3) Restart apache. On SuSE Linux this is done using the command
rcapache restart and on RedHat Linux this is done using the command
/sbin/service httpd restart
4) Optional: adding access control:
In your httpd.conf you can control access to certain modules by adding
directives like this:
<Location "<url to viewcvs.cgi>/<modname_you_wish_to_access_ctl>">
AllowOverride None
AuthUserFile /path/to/passwd/file
AuthName "Client Access"
AuthType Basic
require valid-user
</Location>
This idea is courtesy to Nick Bauman from http://www.cortexity.com/
If you use access control, it is recommended that you disable the
checkout_magic option so people can't "sneak in" with URLs like
http://<server_name>/viewcvs/*checkout*/<module_name>
http://<server_name>/viewcvs/~checkout~/<module_name>
and get access to seeing the file contents.
UPGRADING VIEWCVS
-----------------
Please read the file upgrading.html in the website subdirectory or
at <http://viewcvs.sourceforge.net/upgrading.html>.
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 ViewCVS,
there are some additional steps required to get the database working.
1) You need MySQL >= 3.22, and the Python module MySQLdb 0.9.0 installed.
Python 1.5.2 is REQUIRED by MySQLdb, therefore to use this part of
ViewCVS you must be using Python 1.5.2.
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 <VIEWCVS_INSTALLATION_DIRECTORY>/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 "ViewCVS". This script
creates the database and sets up the empty tables. If you run this on a
existing ViewCVS database, you will lose all your data!
4) Edit your <VIEWCVS_INSTALLATION_DIRECTORY>/viewcvs.conf file.
There is a [cvsdb] section. You will need to set:
enabled = 1 # Whether to enable query support in viewcvs.cgi
host = # MySQL database server host
database_name = # the name of the database you created with
# make-database
user = # the read/write database user
passwd = # password for read/write database user
readonly_user = # the readonly database user -- it's pretty
# safe to use the read/write user here
readonly_passwd = # password for the readonly user
5) 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. Add the line:
ALL <VIEWCVS_INSTALLATION_DIRECTORY>/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, you'll need to use a
slightly different command line:
ALL <VIEWCVS_INSTALLATION_DIRECTORY>/loginfo-handler %{sVv} cvsnt
The extra 'cvsnt' parameter tells the handler script to parse the
commit information in a different way.
For Subversion repositories, there is a single script called
svndbadmin that performs both of the above tasks.
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"
<VIEWCVS_INSTALLATION_DIRECTORY>/svndbadmin rebuild "$REPOS" "$REV"
If you allow revision property changes in your repository, create a
post-revprop-change hook script containing the same commands as the
post-commit one. This will make sure that the checkin database
stays consistent when you change the svn:log, svn:author or
svn:date revision properties.
6) You may want to modify the HTML template file:
<VIEWCVS_INSTALLATION_DIRECTORY>/templates/query.ezt
This is used by the query.cgi script to generate part of its HTML output.
At some point the currently hardcoded table output will also vanish.
7) You should be ready to go. Load up the query.cgi script and give
it a try.
ENSCRIPT CONFIGURATION
----------------------
Enscript is program that can colorize sourcecode of a lot of languages.
Linux distributions like for example SuSE Linux from at least 7.0
up to the recently released 7.3 already contain a precompiled and
configured enscript 1.6.2 package.
1) Download genscript from http://people.ssh.com/mtr/genscript/
2) Configure and compile per instructions with enscript.
(I 've not done this, since I'm using the precompiled package
delivered with SuSE Linux)
3) Set the 'use_enscript' option in viewcvs.conf to 1.
4) That's it!
5) If you want to colorize exotic languages, you might have to
patch 'lib/viewcvs.py' and add a new highlighting file to enscript.
I've done this for Modula-2 and submitted the file to the
enscript maintainer long ago. If interested in this patch for
enscript mailto:pefu@sourceforge.net
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 viewcvs according to instructions in 'INSTALLING
VIEWCVS' section above. The installation directory is where
the 'viewcvs-install' script copied and configured the viewcvs
programs.
2) Download CvsGraph from http://www.akhphd.au.dk/~bertho/cvsgraph/
3) Configure and compile per instructions with CvsGraph. I had
problems with 'configure' finding the gd library. Had to create
a link from libgd.so to libgd.do.4.0.0. On Solaris you might
want to edit the link command line and add the option -R if
you have you libraries at non-standard location.
4) Place the 'cvsgraph' executable into a directory readable by the
userid running the web server. (default is '/usr/local/bin' if
you simply type 'make install' in the cvsgraph directory).
5) Check the setting of the 'cvsgraph_path' option in viewcvs.conf:
/usr/local/bin/ is most often NOT contained in $PATH of the
webserver process (e.g. Apache), so you will have to edit this.
Set the 'use_cvsgraph' option in viewcvs.conf to 1.
6) That's it!
7) There is a file <VIEWCVS_INSTALLATION_DIRECTORY>/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 viewcvs.
SUBVERSION INTEGRATION
----------------------
ViewCVS now supports browsing of Subversion repositories. To use
ViewCVS with Subversion, make sure you have both Subversion itself and
the Subversion Python bindings installed. See Subversion's
installation notes for more details on how to build and install these
items.
Generally speaking, you'll know when your installation of Subversion's
bindings has been successful if you can import the 'svn.repos' module
from within your Python interpreter:
% 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.
>>> import svn.repos
>>>
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 relocation the bindings to some place in that
search path.
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 you've trouble to make viewcvs.cgi work:
=== If nothing seems to work:
o 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
o view the entries in the webserver's error.log
=== If viewcvs seems to work but doesn't show the expected result
(Typical error: you can't see any files)
o check whether the CGI-script has read-permissions to your
CVS-Repository. The CGI-script often runs as the user 'nobody'
or 'httpd' ..
o does viewcvs find your RCS utilities? (edit rcs_path)
=== If something else happens or you can't get it to work:
o check the ViewCVS home page:
http://viewcvs.sourceforge.net/
o review the ViewCVS mailing list archive to see if somebody else had
the same problem, and it was solved:
http://mailman.lyra.org/pipermail/viewcvs/
o send mail to the ViewCVS mailing list: viewcvs@lyra.org
NOTE: make sure you provide an accurate description of the problem
and any relevant tracebacks or error logs.
Reference in New Issue View Git Blame Copy Permalink