HOWTO: Manage the KP3 Webspace with CVS

by Walter F.J. Müller

This document describes how the content of the KP3 webspace is managed with the help of CVS.

2. Getting started

Login to repository
Setup the working directory

3. Editing a file

Checkout a directory
Commit the changes
Update the reference copy

4. Inspecting revision history

1. Introduction

Most HTML documents served by the KP3 web server are stored under

   /u/kp3web/www/...

For a couple of reasons, the most important being the lack of a working implementation of access control lists with a functionality equivalent to the ones in VMS, all files are owned by the single uid:gid of kp3web:kp3web.

Clearly, the responsibility of maintaining the various documents is spread across several people, rising the issue of how to organize access and update of files. Two simple scenarios quickly turn out to be infeasible:

All changes are done under the kp3web account. Think about customizing your favorite editor in a shared account....
All maintainer are part of the kp3web group, get granted group write access, and work from their personal accounts. Such a scheme worked fine under VMS, using ACL's, but simply doesn't fly very well under Linux.

The pattern "several persons work on a common set of files" calls for using a revision control system, in our case CVS. The basic scheme is

all files are stored in a CVS repository
The web server exports a reference copy of all files
each maintainer checks out a working copy of the files in his/her responsibility and edits those files in the personal account.
CVS transactions allow to
- commit changes done to files in the working directory to repository
- and to update the working copy seen by the web server.

2. Getting started

Login to repository

Access to the CVS repository is protected and requires a CVS account and a CVS password. If you maintain a part of the webspace, get in touch with Walter F.J. Müller to get an account setup. Note, that by convention the CVS account name will be the same as your local Linux account name. However, the password will for security reasons be different.

Before any CVS access to the kp3web repository you'll have to login with the command

   cvs -d :pserver:<cvs_account>@www-kp3.gsi.de:/u/kp3web/cvsroot login

where <cvs_account> stands for your CVS account name. You'll be prompted for the CVS password.

Setup the working directory

The next step is to create and setup your private working directory. I recommend to call it kp3web, like the repository. The commands

   mkdir ~/kp3web
   cd ~/kp3web
   cvs -d :pserver:<cvs_account>@www-kp3.gsi.de:/u/kp3web/cvsroot co -l .

create the directory and the establish connection between the working directory and the repository. Note, that the CVS command ends with a trailing `dot' and uses the -l (lower case letter l) option.

Granted, the first two CVS commands look long and ugly. The good news is, that from now on you'll never have to specify the lengthy -d option or the auto-generated CVS password again. CVS stores the repository - password relation and never ask for a password again. Also, the connection between a working directory and a repository is permanently stored in control files, so CVS knows for all future commands that the ~/kp3web directory is associated with a certain repository.

3. Editing a file

Checkout a directory

Now assume, the document

   http://www-kp3.gsi.de/www/doc/indra/vacuum/valves.html

has to be updated. The easiest way is to checkout the whole directory containing the document to be handled into your working directory. The command

   cd ~/kp3web
   cvs co www/doc/indra/vacuum

will do the trick. Note, that there is no leading / before www.

Commit the changes

After the file has been changed and tested, e.g. by inspecting it with Netscape using a file:/... URL, it's time to commit the modifications. In contrast to the checkout, which handles always whole directories, the commit is done usually file by file:

   cd ~/kp3web/www/doc/indra/vacuum
   cvs ci -m "a meaningful comment" valves.html

The text following the -m option should briefly but precisely describe what was changed.

Update the reference copy

The final step is now to update the reference copy, that is make the change visible for the web server. This is simply done with the command

   kp3web_update

Inspecting now

   http://www-kp3.gsi.de/www/doc/indra/vacuum/valves.html

again, don't forget to click the `reload' button, should produce the updated document.

4. Inspecting revision history

There are various CVS commands to retrieve information about full revision history of each file. More convenient though is to use the cvsweb interface. To see what all happened to the file we edited in chapter Editing a file just access

   http://www-kp3.gsi.de/cgi-bin/cvsweb/kp3web/www/doc/indra/vacuum/valves.html

and you'll get a list of all revisions. The page is loaded with useful links:

following the (download) links will show the document in the various revisions.
following the Revision x.x links will produce a view of the raw HTML text.
following the Diff to previous x.x links will show the changes.

5. Further reading

The CVS documentation is available from the KP3 web server in two forms

Table of Contents Back to HOWTO summary

Walter F.J. Müller

Last modified: Mon Nov 29 17:44:45 CET 1999

Imprint ---- Data privacy protection ---- Haftungsausschluss