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. -------------------------------------------------------------------