Caucus 4.0 Brief Installation Guide
                           Screen Porch LLC.
                           24 September 1998

I. INTRODUCTION

This is the BRIEF, plain-text version of the Caucus 4.0 Installation
Guide.  It is intended only for knowledgeable system managers and
webmasters who want to get Caucus up and running quickly.

Far more information is available in the official "Caucus 4.0
Installation and Manager's Guide", which is available under
the Caucus FAQ at http://screenporch.com/sp/FAQ.

Questions and comments are also welcome on our technical support
conferences.  Go to http://screenporch.com to
register a userid and join our conferences.


II. INSTALLATION

II.1 Create the Caucus Userid

Create a new userid, called "caucus", with its own home 
directory.  (You may use a different name if you prefer.  The 
installation procedure will adapt to whichever name you 
choose.)  The home directory for Caucus must have enough free 
disk space to contain all of the Caucus programs and data 
files, and all of the anticipated conference data.  A minimum 
of 100 megabytes is recommended.  (The software itself is 
about 20 megabytes, maximum.)

II.2 Unpackage the Software

The software installation is the same whether you are:

  * installing Caucus for the first time
  * upgrading your existing Caucus software

The installation procedure automatically determines if this is 
a new installation of Caucus or an upgrade to an existing 
Caucus site.  If you are upgrading Caucus, your existing 
conferences will not be affected by the upgrade.

Login to the Caucus userid.  You must actually log in to this 
userid; do not use "root" or "su" access.

These instructions in this guide assume that the Caucus home 
directory is in /home/caucus.  In this guide, whenever you see 
the path /home/caucus, replace it with the actual pathname of 
the Caucus home directory on your system.

Cease using Caucus.  If you are upgrading Caucus, all Caucus users 
should exit or quit the program while you are performing the upgrade.
If you are upgrading from Caucus 3.x, login as caucus and type
the commands:

      mv  BIN2/caucus_x  BIN2/caucus_x.old
      ./swebstop

If you are upgrading from an earlier version of 4.0, use the
"shutdown" option from the "manage this site" page.

The Caucus software is delivered in a file called caucus40.t.Z.  
In the Caucus home directory, type the command below to unpackage 
this file.

    zcat caucus40.t.Z | tar xvf -

(You have probably already done this in order to be reading this file.)


II.3 Run the installation script

The software includes an installation script that will 
automatically create the proper script files, set the proper 
file permissions, and so on.  To run the script, type:

    ./cinstall

The script will ask for the hostname (and port number, if 
needed) of your web server.  Be prepared to provide these.

If you have downloaded an evaluation copy of Caucus, the
script will also ask for your activation key, which should
have automatically been e-mailed to you.  If you have not
received an activation key, contact Screen Porch at 703 243 3001,
or sales@screenporch.com.

The cinstall script will produce some warnings and informative 
messages on your screen.  A copy of these warnings is also 
placed in the file caucus.warn.

The cinstall script also creates two scripts called cv2 and 
cv2check.  Cv2 is the script used to run the text interface to 
Caucus.  Cv2check provides a quick summary of how much new 
information there is in the conferences that you belong to.

If you have purchased the unlimited text-interface license 
option for Caucus, and are providing access to the text 
interface to your users, you probably want to copy these 
scripts to a public directory, such as /usr/local or 
/usr/local/bin.  You may also wish to rename the scripts to 
something more mnemonic, perhaps caucus and caucuscheck.

Caucus places certain files in the Caucus userid's public HTML 
directory.  The standard name for this directory is 
public_html.  The Caucus distribution includes a public_html 
directory with the necessary files already in it.  If your 
httpd server uses a different name, rename public_html to that 
directory name now.


II.4   Starting and Using Caucus

To start the Caucus server, run the following commands
from "root":

      rm -f /home/caucus/SOCKET/sweb
      rm -f /home/caucus/SOCKET/sweb0*
      /home/caucus/SWEB/swebd  /home/caucus/SWEB/swebd.conf

You should also add these lines to your system start-up file 
(such as /etc/rc.d/rc.local, or whatever it is called on your host) 
so that the Caucus server will start when your system reboots.

The Caucus installation script creates a default HTML page for 
accessing the Caucus conferences on your host.  It is located 
in /home/caucus/public_html/caucus.html.  The URL for this 
file is typically:

   http://yourhost/~caucus/caucus.html

This file is just a template for how to access Caucus from the 
Web.  If your organization already has a set of web pages, you 
will probably want to integrate this file with your existing 
pages.  You might choose to copy the links in this file to the 
appropriate places on your existing web pages; or you might 
decide to edit the caucus.html file and simply make it look 
more like your other web pages.


III.  CONFIGURE YOUR WEB SERVER

Sections III.1 through III.4 describe, in the abstract, the changes 
that must be made to your web server configuration to make it work 
properly with Caucus.  Subsequent sections describe the 
precise details of these changes for the servers listed above.

Once you have made these changes, your Caucus site will be up 
and running!  But you should continue on and read chapter 4, 
"Userids and Passwords", to understand the implications of 
userids and passwords on the Web.


III.1 Define CGI directories

Caucus uses several different CGI programs in the directories 
SWEB and REG to communicate with the web server.  The best way 
to identify these programs to the web server is to declare 
SWEB and REG as CGI directories.

Specifically, declare the following mappings of URLs to CGI 
directories:

      http://yourhost.com/sweb/   to   /home/caucus/SWEB/
and   http://yourhost.com/reg/    to   /home/caucus/REG/

If for some reason you cannot declare a CGI directory, enable 
your server in some other way to treat the files:

     /home/caucus/SWEB/start.cgi
     /home/caucus/SWEB/swebsock
     /home/caucus/REG/swebsock

as CGI programs.


III.2 Define special "/caucus" URL

Caucus users who have already registered a userid may go 
directly to specific conferences, items, or responses through 
the special URLs shown below.

  http://yourhost.com/caucus                       ("Caucus Center" page)

  http://yourhost.com/caucus/conference_name       (conference home page)

  http://yourhost.com/caucus/conference_name/item  (go to that item)

  http://yourhost.com/caucus/conference_name/item:response 
                                                   (go to that response)

In order to make these special URLs work, the web server must 
be configured  to map URLs that begin "http://yourhost.com/caucus" 
to the CGI file /home/caucus/SWEB/start.cgi.  (This may not be possible 
for all sweb servers.  Users of such servers can still access 
Caucus through the regular caucus.html page.)


III.3 Restrict Access with userids and passwords

Caucus' security requires that each user be identified by a 
unique userid and password.  Caucus uses the standard web 
"access authorization" protocol to implement userid and 
password checking.

To enable access authorization for Caucus, you must declare 
that the directory /home/caucus/SWEB is protected by a userid 
and password database file.  For some web servers, this is 
done automatically by the Caucus installation script.


III.4 Restart your server

Some web servers must be shutdown and restarted before any of 
the previous changes will take effect.  See your web server 
documentation for details.


III.5 NCSA or Apache Web Server Instructions

This section describes the precise details of configuring the 
NCSA or Apache web server to work with Caucus.  It assumes 
that you have already installed your web server and are 
generally familiar with the server configuration files.

Find the httpd configuration file srm.conf.  Edit it, and add 
the lines:

   ScriptAlias  /sweb/   /home/caucus/SWEB/

   ScriptAlias  /reg/    /home/caucus/REG/

Define special "/caucus" URLs.  Also in srm.conf, add the lines:

   ScriptAlias  /caucus/ /home/caucus/SWEB/start.cgi/
   ScriptAlias  /caucus  /home/caucus/SWEB/start.cgi

Restrict Access with userids and passwords.  Access authorization 
for NCSA and Apache servers is set up automatically by the Caucus 
installation script.  It creates the file /home/caucus/SWEB/.htaccess, 
which declares that the directory is password-protected.  That file 
points in turn to the userid and password database file 
/home/caucus/caucus_passwd, which is also set up by the Caucus 
installation script.

You must restart the httpd server in order for these changes 
to take effect.  See your server documentation for details.


III.6 Netscape Enterprise Server 2.x Instructions 

This section describes the precise details of configuring the 
Netscape Enterprise Server, version 2.x, to work with Caucus.  
It assumes that you have already installed your web server and 
are generally familiar with server configuration.

Define CGI directories.  From the server configuration page, 
choose "Programs", sub-selection "CGI directory".  Add entries for:

   URL prefix sweb/,    CGI directory /home/caucus/SWEB/

   URL prefix reg/,     CGI directory /home/caucus/REG/

And choose "save and apply" these changes (replacing 
/home/caucus with the home directory of the Caucus userid on 
your system).

Define special "/caucus" URLs.  From the server configuration page, 
choose "Programs", sub-selection "CGI directory".  Add an entry for:

    URL prefix caucus/,    CGI directory /home/caucus/SWEB/start.cgi

And choose "save and apply" these changes.

Restrict Access with userids and passwords.  In the directory 
/home/caucus/SWEB, create a world-readable file called .nsconfig, 
containing the lines:

  
  RequireAuth userfile=/home/caucus/caucus_passwd realm=Caucus userpat=*
  

From the server configuration page, chose "System Settings", 
sub-selection "Dynamic Configuration Files".  In the "file 
name" field, type ".nsconfig".  Do not change any of the other 
settings or checkboxes in this form.  "Save and apply" these 
changes.

To add userids to the database file, use the shell script 
manager_script.  (Do not use the Netscape server user database 
functions.)  Or your users may self-register a userid and 
password from the link in the caucus.html page.

It is not necessary to restart the Netscape Enterprise server.  
All of the changes will take effect immediately.

You may, however, have to explicitly enable "user document 
directories" (i.e., the public HTML directories) in order for 
Caucus to work.  To do this, from the server configuration 
page, choose "Content Management", sub-selection "User 
Document Directories".  You don't need to make any changes, 
just click on "OK" and "Save and Apply" to enable the user  
document directories.

-------------------------------------------------------------------

IV. OTHER INFORMATION

This is the end of the brief install guide for Caucus 4.0.  There
is much more information about the management and customization
of Caucus, and other topics, in the full install guide.

-------------------------------------------------------------------