Alumni Internet Directory README file $Id: README,v 5.12 2003/11/06 01:41:33 mradwin Exp $ ======================================================================== This software is available under the BSD License. Please see COPYING for details. ======================================================================== DISCLAIMER: This is not very well packaged code. It's not packaged at all. Don't come here expecting something you plop in a directory, twiddle a few things, and you're off and using it. To set up the Alumni Internet Directory, do the following: 1. Customize these files for your School/Unix/Apache setup ------------------------------------------------------------------------ bin/generic_config.pl: Copy this file to customize for your high school. Change all GHS and Generic High School references to your own school name, all e-mail addresses, and pathnames for various web/source directory scripts, etc. Make sure the pathnames match with the ones used in the Makefile. bin/aid_util.pl: Change the "require 'generic_config.pl'" line near the top of the file to your particular school_config.pl file. Makefile: Edit the SCHOOL, WWWROOT, WWWDIR, CGIDIR, and possibly other variables, making sure that they're consistent with the school_config.pl file. data/*.include: Customize the HTML code for your school. These files get a header and a footer attached to them, and then get copied verbatim out to the web directory. 2. Create a data/working.db file and put at least one entry in it ------------------------------------------------------------------------ Run these commands: $ ./bin/aid_dbm_create data/working.db /dev/null $ ./bin/aid_edit_entry data/working.db -1 The first should create a valid, empty DBM file for your particular OS. The second will drop you into your favorite editor (vi by default) and let you create the first entry (probably your name!) by hand. Be sure to put non-blank values in the 4 required keys: * sn [surname] * gn [given name] * e [email address] * yr [graduation year] You also might put an URL the 'w' key (complete with leading "http://"). 3. Install CGI scripts, .htaccess files, and default.css (style sheet) ------------------------------------------------------------------------ A simple 'make install' should do the trick, but check to make sure that the permissions are set correctly. You may need to chmod the files to make them world-readable and possibly world-executable. 'make install' creates a .htaccess file in your cgi-bin directory to tell apache that all of the scripts (form, go, vcard, etc.) are CGI scripts and not content via the directive "SetHandler cgi-script". This is ususally only relevant if you're using a "bin" subdirectory of the public_html/school directory instead of a standard "cgi-bin" script. If your Apache won't accept that configuration directive, or you're using another web server, you'll probably need to rename all of the cgi binaries with the extension .cgi, and be sure to update your school_config.pl file appropriately. 4. Generate static HTML pages ------------------------------------------------------------------------ If all has gone well up to this point, 'make all' should copy your data/working.db into the web directory's master.db location. Then it will use the various scripts in the bin dir to generate all of the Graduating Class/Alphabetical listings and the index.html, FAQ, reunions page, download page, etc. 5. Process new submissions as they come in ------------------------------------------------------------------------ New submissions get added to a staging database, and then the site gets rebuilt in batch. You'll want to create a cron job that checks every 5 minutes or so and rebuids the HTML pages: # build alumni directories 0-55/5 * * * * nice $HOME/mvhs/bin/aid_addname -q # ocassionally clean staging.db 10 4 * * * nice $HOME/mvhs/bin/aid_staging_clean -q aid_addname reads the staging.db and modifies data/working.db, invokes 'make all' to push out the new static HTML pages, and then invokes aid_welcome to e-mail the new members to tell them that their submission has been received. aid_staging_clean removes old entries that have been in staging.db for 28 days or more and have not been verified. 6. Send out quarterly digests and bi-yearly confirmation messages ------------------------------------------------------------------------ In addition to notifying new/updated alumni that their submissions have been processed, aid_welcome can also be used for sending out the quarterly digests or bi-yearly verification messages. For quarterly digests and bi-yearly confirmation messages, run: ./bin/aid_quarterly Be careful only to run this script once every 3 months! 7. Manage invalid email addresses ------------------------------------------------------------------------ aid_bounce will help you manage people who's email has been bouncing (I usually let e-mail bounce for 6 months before I make their record invalid). To extract a list of userids who bounced from your last mailing (determined by scanning messages in your mail spool), run: ./bin/aid_grep_bounce $MAIL If the list looks okay, set their bounce flag in the database: ./bin/aid_bounce data/working.db `./bin/aid_grep_bounce $MAIL` To see a list of userids to invalidate, run: ./bin/aid_dbm_read -g data/working.db If the list looks okay, move their entry to the invalid page: ./bin/aid_bounce -v data/working.db `./bin/aid_dbm_read -gi data/working.db` ======================================================================== Michael John Radwin michael@radwin.org http://www.radwin.org/michael/