Caucus Installation Guide

(Some people actually install Caucus multiple times on the same server, setting up independent virtual hosts that are completely separate Caucus sites.)

Caucus must be installed by a system administrator with 'root' privileges. Caucus does not, however, run as root, but under and as an ordinary userid via the unix 'setuid' feature.

The installation consists of six steps:

Install MySQL 5.0 or higher
Create a pair of ordinary userids for Caucus.
Install the Caucus software in one of them (the other is used for automatic Caucus email features)
Configure the Apache or other web server to run Caucus
Make Caucus start automatically on server reboot.
Test Caucus.

If you are upgrading an existing Caucus installation, you will only need to perform step II, and possibly V and VI.

I. Install MySQL (required)
Many unix/linux systems today come with MySQL pre-installed. If you do not have MySQL, see the separate Installing MySQL page for detailed instructions.

II. Create userids

Create a new userid, typically called "caucus", with its own home directory, such as /home/caucus. (You may use a different name or home directory if you prefer. The installation procedure will adapt to whichever name you choose.)
Caucus must also have a dedicated unix group that is not used for any other purpose.
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 100MB is recommended. (The software itself is less than 30MB.)
Only the system administrator, or a designated Caucus manager, should know the password to the Caucus userid.
Create a second userid, typically called "caucus_mail". It must use the same group as the "caucus" userid from step II.1. This userid is used for the Caucus "E-mail participation" feature.

For example, if the numeric userids 500 and 501 are available, you could create these userids as root with the following commands:

   adduser -u 500 -d /home/caucus         caucus
   adduser -u 501 -d /home/caucus_mail -g caucus caucus_mail

III. Install (or upgrade) the Caucus kit

The installation procedure is the same whether you are installing Caucus for the first time, or 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.
Unless otherwise stated, all commands in this installation guide must be typed while logged in to your unix system, in a terminal (shell) window, as the "caucus" userid.
Unpackage the software
The Caucus kit is packaged in a file called caucus5.tar. In the Caucus home directory, type the following commands to unpackage this file.
```
     tar xvf caucus5.tar
```
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.
The script will ask for your hostname (and port number, if needed) of your web server, and some other information.
To run the script, type:
```
    ./install
```
and follow the directions.
Check for swebd.conf.new
If you are installing Caucus as an upgrade, look for the files SWEB/swebd.conf and SWEB/swebd.conf.new. Compare the two files with 'diff' or merge2. Swebd.conf.new is the new version created by the installer; if you've made any significant changes to swebd.conf, you should now make the same changes to swebd.conf.new.
Then, in either case, rename swebd.conf.new to swebd.conf.
Public HTML directory
Caucus requires that certain files be placed 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 by default, persuade it map the URL "~caucus" (for example) to /home/caucus/public_html.

IV. Configure your web server to run Caucus

Allow Access to Caucus directories
Most web servers require that you "open up" access to any specific directories that live outside the "root" directory of the web tree. In particular, assuming /home/caucus is the Caucus home directory, you may need to allow access to the directories
To do this for Apache, modify your httpd.conf or other configuration file to include:
```
<Directory /home/caucus/SWEB>
   Options All
   AllowOverride All
   allow from all
</Directory>
   
<Directory /home/caucus/REG>
   Options All
   AllowOverride All
   allow from all
</Directory>
```
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/
  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 below as CGI programs:
- /home/caucus/SWEB/swebsock
- /home/caucus/REG/swebsock
To do this for Apache, include the directives:
```
   ScriptAlias  /sweb/   /home/caucus/SWEB/
   ScriptAlias  /reg/    /home/caucus/REG/
```

Define special "/caucus" URL
Existing Caucus users 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/REG/start.cgi. If this is not possible for your web server, your users may still access Caucus through the regular login page.)

To do this for Apache, add the directives:

   ScriptAlias  /caucus/ /home/caucus/REG/start.cgi/
   ScriptAlias  /caucus  /home/caucus/REG/start.cgi

Allow access to ~caucus
Ensure that the URL http://yourhost.com/~caucus maps to /home/caucus/public_html.
To do this for Apache, you have three choices:
1. If it is acceptable to map all "~user" URLs to the equivalent public_html directories, just include the directive:
```
   UserDir public_html
```
2. If you have a separate section for a Caucus virtual host (recommended), include the same directive in that section.
3. Otherwise, you can add a specific directive to do the mapping:
```
   Alias /~caucus /home/caucus/public_html
```
Restrict "Directory Indexing"
This turns off the automatic indexing (directory listing) of the directories (folders) under Caucus. Otherwise outside users could, in principle, navigate through all the files uploaded to Caucus.
To do this for Apache, include the directive:
```
   <Directory /home/caucus/public_html>
      Options -Indexes
   </Directory>
```
Allow file upload
If (and only if) you encounter problems uploading files into Caucus, you may need to specifically allow file uploads.
To do this for Apache, add the directive:
```
   AddHandler cgi-script .cgi
```
Restart your web server
The usual method for Apache is
```
   service httpd restart
```

V. Start Caucus automatically on server reboot
Caucus runs as a single master "daemon" program called swebd, which accepts requests for new Caucus sessions. It spawns off a "sub-server child" called swebs, one for each user's session. (See the Caucus architecture description for more information.)

Swebd is normally started from root, so that it may start as many children as needed. Each swebs child runs as effective userid "caucus", and real userid "nobody". (If you are just testing Caucus, or if your system policies discourage running outside software as root, you may instead start Caucus logged in as the "caucus" userid. On most Unix systems, however, this will limit the number of simultaneous Caucus sessions.)

Note:

/home/caucus

To start the Caucus daemon, login as root, and type the commands below:

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

where /home/caucus is the home directory of the "caucus" userid.

You must also add these same commands to your system start-up file so that the Caucus daemon will automatically start when your system reboots:

For most Linux installations, you can simply add these commands to the file /etc/rc.d/rc.local.

For Solaris installations, the proper way to start Caucus is to create a run-level 3 startup file. As root, create the file /etc/rc3.d/S90caucus. It must be "hard-linked" (via 'ln', no -S option) to the file /etc/init.d/caucus, and contain the following script:

      #!/sbin/sh
      
      case "$1" in
      start)
              rm -f /home/caucus/SOCKET/sweb /home/caucus/SOCKET/sweb0*
              /home/caucus/SWEB/swebd  /home/caucus/SWEB/swebd.conf
              ;;
      restart)
              ;;
      stop)
              ;;
      *)
              ;;
      esac
      exit 0

For MacOS X, see www.macdevcenter.com/pub/a/mac/2002/10/22/macforunix.html.

VI. Test Caucus
Point your browser at http://yourhost.com/~caucus/caucus.html. Click on the "New User Registration" link, and follow the instructions.

If you encounter problems, check the trouble-shooting guide below:

The server encountered an internal error...: The swebd program was probably not started.
The requested URL was not found on this server: The 'sweb' or 'reg' parameter in the web server configuration may have been misspelled.
swebfail='/home/caucus/SOCKET/swebfail' errno=13 Hint: If file is correct, volume may not be mounted suid.: The files swebs or swebsock in /home/caucus/SWEB are not setuid, or the volume (disk) that contains them is specifically mounted as to not allow setuid programs to run.