Annotation of cvsweb/INSTALL, Revision 3.1
3.1 ! knu 1: 1) To get cvsweb.cgi to work, make sure that you
! 2: have Perl 5 installed and a webserver which is capable
! 3: to execute cgi-scripts.
! 4:
! 5: Currently, you need to have the GNU RCS utilities 'rlog',
! 6: 'rcsdiff' installed (current version is 5.7).
! 7:
! 8: This will change if cvs will be able
! 9: to serve these functions without having a working directory
! 10: [see TODO]
! 11: Note, that the cvsweb.cgi-script needs to have physical
! 12: access to the repository (or a copy of it) therefore;
! 13: rsh/ssh or pserver access doesn't work yet.
! 14:
! 15: 2) copy cvsweb.conf to your configuration directory. If
! 16: you've installed Apache, $ServerRoot/conf (or $ServerRoot/etc
! 17: with versions >= 1.3.0) makes sense.
! 18: Edit cvsweb.conf to fit your needs, esp. set the CVS-Root(s)
! 19: of the Repository(ies) you want to view.
! 20: If your RCS utilities are not in the $PATH of the cgi execution
! 21: environment you need to set it in the 'Misc' section as well.
! 22:
! 23: 3) copy cvsweb.cgi to the cgi-script location of your web server.
! 24: Edit it to make the variable $config (look for 'Configuration Area')
! 25: point to your configuration file.
! 26: If your perl binary isn't located in /usr/bin you have to edit the
! 27: first line of the script as well.
! 28: If you want to let cvsweb.cgi run on WinNT running see (7).
! 29:
! 30: 4) If you want to have CVS-annotate support, make sure the process
! 31: running cvsweb.cgi (the webserver, usually running as 'httpd' or
! 32: 'nobody') has write permission to CVSROOT/history (if it exists) and
! 33: any directory within your repository to place the lockfiles of the
! 34: called cvs-process. I prefer adding the httpd-user to the cvs-group
! 35: (but: adding 'nobody' to this group may not be a good idea for
! 36: security reasons). Make sure, the cvs-binary is in your PATH.
! 37: Note: cvs 1.10 and later supports the LockDir option, allowing you
! 38: to move the lock files to a separate directory. With this option
! 39: cvsweb does not need any write permission to the CVS repository
! 40: directories.
! 41:
! 42: 5) If you do not have the dir.gif, text.gif and back.gif-icons, copy
! 43: them somewhere in your $DocumentRoot and edit the %ICONS-Hashtable
! 44: in cvsweb.conf. You won't need to do this if you have a stock
! 45: Apache installed .. the're located in the default icons-directory.
! 46: The icons distributed with this cvsweb are in the public domain.
! 47: If you think that the default icons are to large, use the corresponding
! 48: miniicons in the icons-directory and change the %ICONS-Hashtable in
! 49: cvsweb.conf.
! 50:
! 51: 6) have fun
! 52:
! 53: 7) If you've Windows NT running, calling of external programs with parameters
! 54: single quoted doesn't work (search for rcsdiff, rlog in
! 55: cvsweb.cgi), you've to replace it with double quotes. Thanks to
! 56: Nick Brachet to point this out.
! 57: I don't know if cvs-annotate works on NT.
! 58:
! 59: > From: Nick Brachet <nick@gradient.com>
! 60: [...]
! 61: > I'm running NT <g> and I had to patch a few things. For example,
! 62: > open(RCS, "co -p$rev '$fullname' 2>&1 |")
! 63: > will fail on NT because the ' are not recognized. Using " will work
! 64: > though.
! 65:
! 66: 8) If you like you can add descriptions to be shown next to each directory
! 67: or module name. These are read from CVSROOT/descriptions.
! 68:
! 69: - Check out a copy of your CVSROOT
! 70: - edit checkoutlist and add a line that says
! 71: descriptions
! 72: - edit descriptions. Add one line for each directory that you would like
! 73: to have a comment for. You can have HTML in the descriptions.
! 74: These lines are relative from the $CVSROOT. Example:
! 75: JVote/ An application to assist with <A HREF="http://www.irtc.org/">IRTC</A> voting
! 76: JVote/images/ Store the images for JVote
! 77: JVote/tools/ Scripts to startup JVote
! 78: - cvs add descriptions
! 79: - cvs commit
! 80: - Set $use_descriptions to 1 in cvsweb.conf.
! 81:
! 82: --------------------
! 83:
! 84: if you got PROBLEMS ..
! 85: ----------------------
! 86:
! 87: If you've trouble to make cvsweb.cgi work ...
! 88: .. if nothing seems to work:
! 89: o check, if you can execute CGI-scripts (Apache needs to have an
! 90: ScriptAlias /cgi-bin or cgi-script Handler defined). Try to
! 91: execute a simple CGI-script that often comes with the distribution
! 92: of the webserver; locate the logfiles and try to find hints
! 93: which explain the malfunction
! 94: o view the entries in the webservers error.log
! 95:
! 96: .. If cvsweb seems to work but doesn't show the expected result
! 97: (Typical error: you can't see any files)
! 98: o check, whether the CGI-script has read-permissions to your
! 99: CVS-Repository. The CGI-script often runs as the user 'nobody'
! 100: or 'httpd' ..
! 101: If you use annotation, the user needs to have write-permissions
! 102: to CVSROOT/history and to the directory the file is in in order
! 103: to place the read-lock.
! 104: If you don't like cvsweb to write into your CVSROOT/history, build
! 105: a fake cvsroot with symlinks to the 'real' CVS-directories and make
! 106: a fake CVSROOT/history as symbolic link to /dev/null.
! 107: If you don't like cvs, called from cvsweb, to place read-locks - let
! 108: cvsweb operate on a copy.
! 109: o does cvsweb find your RCS-utils/cvs-binary(annotate) ? ($ENV{PATH} in
! 110: cvsweb.conf !)
! 111: o cvsweb allows for compression now. It is determined first,
! 112: if the browser accepts gzip-encoding. But - no rule without
! 113: exception - MSIE claims to understand gzip encoded content but
! 114: displays garbage .. so MSIE is disabled now. Maybe you find another
! 115: Browser with this problem, then you should disable compression
! 116: ($allo_compress=0 in cvsweb.conf) and
! 117: report it to me (<zeller@think.de>)
! 118:
CVSweb