Caucus 5.1 Build & Installation Instructions Last revision: 9 May 2007 I. INTRODUCTION Caucus is a sophisticated web-based group discussion and e-learning tool, with a history that stretches back to 1986. It provides multi-tiered asynchronous discussion groups, classes, assignments, quizzes, file storage areas, user tracking, and grading, all with a high degree of security, flexibility, and customizability. Caucus runs as a CGI application on top of most web servers (such as Apache), and uses MySQL as its data store. Caucus can run on just about every flavor of Unix. There was also (briefly) a Windows NT version, although it is no longer supported or recommended. Most of the NT code remains in the code base, and in theory could be resurrected. Caucus version 5 was released as "open source" in October 2005, and may be used by anyone for any purpose. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. For more information, see www.caucus.com. If you are actively using or testing Caucus, there is a conference (discussion forum) called "Caucus5 Open Source", specifically for questions and comments about this build and install procedure. Caucus is Copyright (C) 2007 CaucusCare.com, a registered DBA in the state of Michigan of the United States of America. Version 5 was released under the GPL and the CDDL; see the license.txt files in the source directories, or the web site, for details. II. REQUIREMENTS Caucus requires the following packages: 1. MySQL 4.1 or higher. See www.mysql.com. 2. MySQL development package (libraries and include files) 3. A web server (Apache is recommended) Caucus also requires the OpenLDAP libraries, but they are included (and built from source) by this package. We currently use OpenLDAP version 2.3.11. III. OVERVIEW There are two phases: 1. Build kit 2. Install kit Caucus is frequently installed multiple times on a single box (each install in its own unix userid as a "virtual host"). Thus a "kit" (caucus5.tar) is built once from source, and then potentially installed multiple times. IV. BUILD PHASE 0. Unpack source and cd to build directory. (Solaris 9 may require gzcat instead of zcat.) zcat caucus5.102.102.tar.gz | tar xvf - cd caucus5.102.102 1. Configure for this operating system. (Run "./configure --help" for a list of options.) ./configure Currently Linux (Redhat and Debian), Solaris 9, and MacOS X are supported. Other flavors of unix will require only minor changes to the configure script. 2. Build the install kit, in the file caucus5.tar. make V. BUILD PHASE NOTES 0. Run "./configure --help" to see a list of all configuration options. In particular, if your MySQL is installed in an unusual location, you may need to set the --mysqllib or --mysqlinc options. 1. Linux Distributions: a. Most RedHat distributions (RHEL, Fedora Core) work fine with just "./configure". b. Debian seems to need: ./configure --nosasl2 --nomd5 2. For Solaris and MacOSX, we recommend ./configure 3. If you have problems linking Caucus, see the file CV2/sweb/makefile (produced by configure), and edit the list of libraries to match the locations on your system. Please let us know what you did, and we will incorporate the necessary changes in the next release. VI. INSTALL PHASE 1. Create two unix userids, e.g. "caucus" and "caucus_mail" at /home/caucus and /home/caucus_mail. Caucus_mail and caucus must share the same, unique, group. For example: useradd -u 555 -d /home/caucus caucus useradd -u 556 -d /home/caucus_mail -g caucus caucus_mail 2. Select a virtual hostname (if possible), e.g. caucus.yourserver.com. 3. Login to "caucus". 4. tar xvf /wherever-you-put/caucus5.tar 5. ./install (Follow the instructions. You will need the root MySQL password. For the first install of Caucus on a server, accept the defaults when offered. Use the virtual hostname from step 2.) 6. /home/caucus/SWEB/swebd /home/caucus/SWEB/swebd.conf (Starts the Caucus "daemon" process.) For a permanent installation, you should set Caucus up to be started at boot time. Add something like the following to /etc/rc.d/rc.local (or equivalent start-up script): rm -f /home/caucus/SOCKET/sweb rm -f /home/caucus/SOCKET/sweb0* /home/caucus/SWEB/swebd /home/caucus/SWEB/swebd.conf 7. Configure your web server. For Apache, the best approach is to define a virtual host as below: ServerName caucus.yourserver.com DocumentRoot /home/caucus/public_html Options All AllowOverride All allow from all Options All AllowOverride All allow from all Options -Indexes ScriptAlias /sweb/ /home/caucus/SWEB/ ScriptAlias /reg/ /home/caucus/REG/ 8. Restart (or reload) your web server. 9. Test Caucus. Point your browser at http://caucus.yourserver.com, and click on "New User Registration". Register yourself as the "primary manager" userid that you supplied (in response to the install script prompt) in step 5. 10. If Caucus does not run, create an empty file called "debug" in the SOCKET directory. Then try stopping, restarting, and entering Caucus. You should see several .log files in the SOCKET directory that will contain more information.