OpenImpetus Release Notes

V0.9.2 Installation Guide

Introduction

Thank you for using OpenImpetus! Your comments on any aspect of this software: installation, configuration, usage, etc, are welcome: please send mail to dcctdw@mit.edu. You can find the latest version of this file at the OpenImpetus homepage.

Random notes:

In this document, the acronym OI stands for OpenImpetus.
All pathnames shall be set in the teletype font, e.g., /usr/local/openimpetus.
This document is very long, because it assumes very little knowledge on the part of the installer. But if you're still lost, please give me feedback, so I can be more complete.

Requirements

Installing OpenImpetus requires that you have maintainer access to a web server which has perl (version 5) installed. For an excellent web server, get the Apache webserver. Perl can be downloaded from the GNU archives. Note that you will want to download (at least) perl version 5; perl 4 is insufficient.

Installing either of these is very easy; just uncompress them and look at the README or INSTALL files and follow the directions. If you need to install perl, I suggest you let it automatically install itself with the defaults it comes up with, rather than reviewing each option individually. Furthermore, if you are installing both a webserver and the perl package, I suggest that you install them in separate directories (and not in the same directory); e.g., /usr/local/apache and /usr/local/perl, or c:\ProgramFiles\apache and c:\ProgramFiles\perl, etc.

Installation

For UNIX installations, you will probably want to install OI into /usr/local. To do this,

cd /usr/local mkdir openimpetus cd openimpetus gunzip openimpetus-v0.9.2.tar.gz tar -xf openimpetusv-0.9.2.tar
./Configure.pl

Note that you may need to have root access to mkdir in /usr/local.

Running Configure will (minimally) setup the directory structure and prompt you for customizations. This customization is discussed in detail later.

Webserver Modifications

If you know your way around configuring a webserver, here's the very short form. Add the following aliases:

Alias /openimpetus/ pathname
ScriptAlias /oi/ pathname

where pathname points to the parent directory for openimpetus (such that /oi/openimpetus.pl resolves correctly). Using the above exmaple in the Installation section, pathname would be /usr/local/openimpetus.

Here's the long form of the above.

Webservers can be configured to resolve certain URLs in a directed manner. This configuration information is done via files for UNIX servers; for NT servers, it is usually done through the administrator's screen. For UNIX (which I am the most familiar with), I will provide examples using the apache server (the server that I'm the most familiar with). Information is provided to the best of my knowledge about NT installations; feedback here is especially welcome.

UNIX Installations
For UNIX-based Apache servers, this configuration is in the file srm.conf, often located in /usr/local/apache/etc or /usr/local/etc/httpd/conf. Note that srm.conf-dist is probably not the file that needs to be changed. In srm.conf, you should see something like the following:

# Aliases: Add here as many aliases as you need. The format is # Alias fakename realname
Continuing the example started from the Installation section, add the line

Alias /openimpetus/ /usr/local/openimpetus/
A few lines later, you should see a similar section for ScriptAlias; add the line

ScriptAlias /oi/ /usr/local/openimpetus/
In order for these customizations to take effect, you will need to kill and restart your webserver. To do this on apache, look for the file httpd.pid, located in the logs/ directory (logs is a peer directory with conf). Then issue the command:
% cd /usr/local/apache/logs % kill -HUP `cat httpd.pid`
Newer versions of apache have the command apachectl in the sbin directory: use the following instead:
% cd /usr/local/apache/sbin % apachectl restart
Non-UNIX Installations
For NT and Mac servers, there should be a webpage you can bring up for the server administrator. Somewhere in there should be a mechanism to add aliases. You will need to add two aliases.
The first alias is a non-executable alias from openimpetus to wherever you installed openimpetus on your machine: probably something like c:\openimpetus. The second is an executable alias from oi to the same directory (c:\openimpetus).
If this doesn't work, try setting the aliases to be /openimpetus/ -> c:\openimpetus\.

OpenImpetus Customization

All the customization that needs to be done to OpenImpetus is in a single file, which is initially written by Configure.pl. Moreover, all the files that pertain to a single competition reside in a single directory. If you installed OI into (say) /usr/local/openimpetus, then all of the comp's files will be in /usr/local/openimpetus/Comps/compname. Compname can be anything, although a short succint name (``MIT'', ``Harvard'', ``BU_Beginner'') is probably best. I will use the example of the MIT Comp.

The file that holds all these constants is called (drum roll, please), Constants; the path is therefore /usr/local/openimpetus/Comps/MIT/Constants. The file largely consists of key-value pairs, with the more relevant ones near the very top or very bottom of the file.

A brief overview of the most-likely-to-be-changed constants near the top of the file:

Key Sample Value Description

SENDMAIL 1 0 if mail should not be sent to competitors each time OI processes an update involving them.

STARTING_NUMBER 100 The first leader's number that should be assigned.

LAST_NUMBER 399 The largest leader's number that should be assigned.

REGISTRATION_OPEN 0 0 if Registration updates should not be accepeted.

SERVER "bingo.mit.edu" The full name of the web server.

STATS_DIR "/usr/local/openimpetus/Comps/MIT/" The full path into the Competition's directory.

STATS_DIR_HREF "/openimpetus/Comps/MIT/" The URL, using the installed Alias, into the Competition directory.

BODY_TAG "<BODY bgcolor=black text=white link=yellow vlink=orange background=\"/openimpetus/Images/background.gif\">" The BODY tag that should be used in all HTML pages that OI produces.

Key	Sample Value	Description
SENDMAIL	1	0 if mail should not be sent to competitors each time OI processes an update involving them.
STARTING_NUMBER	100	The first leader's number that should be assigned.
LAST_NUMBER	399	The largest leader's number that should be assigned.
REGISTRATION_OPEN	0	0 if Registration updates should not be accepeted.
SERVER	"bingo.mit.edu"	The full name of the web server.
STATS_DIR	"/usr/local/openimpetus/Comps/MIT/"	The full path into the Competition's directory.
STATS_DIR_HREF	"/openimpetus/Comps/MIT/"	The URL, using the installed Alias, into the Competition directory.
BODY_TAG	"<BODY bgcolor=black text=white link=yellow vlink=orange background=\"/openimpetus/Images/background.gif\">"	The BODY tag that should be used in all HTML pages that OI produces.

At the bottom of the file are the MASTER and SCHOOLS array. The MASTER array is a listing of all the events that are being offered. SCHOOLS is a simple listing of all the school names that will be present. Each school is listed in quotes, separated by commas.

The MASTER listing is a linear listing of SingleDance() or MultiDance() directives. The first two arguments of SingleDance() and MultiDance() are:

Level. Level is oneof NEWCOMER, BEGINNER, INTERMEDIATE, ADVANCED, OPEN, PRE_BRONZE, BRONZE, SILVER, GOLD, NOVICE, PRE_CHAMP, CHAMP, or TEAMMATCH.
Style. Style is oneof AMERICAN, INTERNATIONAL, or FUN_DANCE.

The third argument of SingleDance() and MultiDance(), the fourth argument of MultiDance(), and optionally up to three more arguments in MultiDance(), are the dance(s), which is oneof RHUMBA, CHACHA, BOLERO, SWING, MAMBO, SAMBA, RUMBA, PASO, JIVE, WALTZ, TANGO, FOXTROT, VIENNESE, or QUICKSTEP.

Note that, for aesthetics, it is recommended to group dances together first by level, and then by style. Here's an example:

MASTER={ SingleDance(BEGINNER, INTERNATIONAL, CHACHA), SingleDance(BEGINNER, INTERNATIONAL, RUMBA), SingleDance(BEGINNER, INTERNATIONAL, JIVE), SingleDance(BEGINNER, INTERNATIONAL, WALTZ), SingleDance(BEGINNER, INTERNATIONAL, TANGO), SingleDance(BEGINNER, INTERNATIONAL, FOXTROT), SingleDance(BEGINNER, INTERNATIONAL, QUICKSTEP), SingleDance(BEGINNER, AMERICAN, RHUMBA), SingleDance(BEGINNER, AMERICAN, CHACHA), SingleDance(BEGINNER, AMERICAN, SWING), SingleDance(BEGINNER, AMERICAN, WALTZ), SingleDance(BEGINNER, AMERICAN, TANGO), SingleDance(BEGINNER, AMERICAN, FOXTROT), MultiDance(ADVANCED, INTERNATIONAL, RUMBA, CHACHA), MultiDance(ADVANCED, INTERNATIONAL, SAMBA, JIVE), SingleDance(ADVANCED, INTERNATIONAL, PASO), MultiDance(ADVANCED, INTERNATIONAL, WALTZ, QUICKSTEP), MultiDance(ADVANCED, INTERNATIONAL, TANGO, FOXTROT), SingleDance(ADVANCED, INTERNATIONAL, VIENNESE), MultiDance(ADVANCED, AMERICAN, CHACHA, RHUMBA, SWING), SingleDance(ADVANCED, AMERICAN, BOLERO), SingleDance(ADVANCED, AMERICAN, MAMBO), MultiDance(ADVANCED, AMERICAN, WALTZ, TANGO, FOXTROT), SingleDance(ADVANCED, AMERICAN, VIENNESE), MultiDance(OPEN, INTERNATIONAL, CHACHA, SAMBA, RUMBA, PASO, JIVE), MultiDance(OPEN, INTERNATIONAL, WALTZ, TANGO, VIENNESE, FOXTROT, QUICKSTEP), MultiDance(OPEN, AMERICAN, RHUMBA, CHACHA, BOLERO, SWING, MAMBO), MultiDance(OPEN, AMERICAN, WALTZ, TANGO, FOXTROT, VIENNESE), SingleDance(OPEN, FUN_DANCE, Hustle) }; # Master definition

Note that the capitalization is important for the 'typical' dances (RUMBA, SAMBA, WALTZ, etc), but not for the 'fun dances'.

Administrator Page

OK, I somewhat lied. The administrator page, /usr/local/openimpetus/admin.html also requires customizing to use. The default looks something like:

<a href="http://hno2/oi/openimpetus.pl?openimpetus_major_dispatch=admin&openimpetus_minor_dispatch=redo_stats&compname=MIT">Redo Stats</a>

To use, replace your web server name for hno2, and the your competition's directory name for MIT. Do this for all the lines. I'll try to get Configure to do this for you instead.

From the Administrator Page, you can:

Force a remake of all the stats pages.
Send mail to all competitors; OI will read certain files (that you have prepared in advance) and use them to send mail to all competitors. (Note: This is currently unimplemented.)
Automatically assign numbers to leaders.
Generate Postscript files for the MC, Scrutineer, and Registrar.
Open registration (allow web requests to go through).
Close registration.
Scrub the database -- this will optimize the database, making for faster process times.

The Postscript files are placed in /usr/local/openimpetus/Comps/comp_directory/PS, and are called list1.PS, list2.PS, ... list7.PS. (These names can be changed in the Constants files, if you really wish to do so.)

Using OpenImpetus

If you look at demo.html, you'll see how to invoke OI. In general, either of the following should work:

<form action=http://bingo.mit.edu/oi/openimpetus.pl method=POST>
<input type="hidden" name="openimpetus_major_dispatch" value="starting_page">
<input type="hidden" name="compname" value="MIT">
<input type="submit" value="Click Here To Begin">
</form>
<a href="http://bingo.mit.edu/oi/openimpetus.pl?openimpetus_major_dispatch=starting_page&compname=MIT">This link should work as well.</a>

You will need to replace bingo.mit.edu with your server name, and modify compname=MIT with comp_directory used above.

Troubleshooting

One day I'll flesh this out better. Invariably, most errors stem from the fact that files aren't world-writeable, or that directories aren't world-writeable. For instance:

If you can't scrub the DB, make sure the db file is world-writeable.

dave leung (dcltdw@mit.edu)