
                             Ethereal Realms 3.5.0
                                       
Installation Instructions

  Released: 28-Jan-2004
  
File Listing

   ./[1]erealms
     * [2]bio.pl
     * [3]board.pl
       - board*
       - sysbload*
     * [4]contrib.pl
     * [5]gallery.pl
       - gallery*
     * [6]gwho.pl
     * [7]mail.pl
     * [8]poll.pl
     * [9]portal.pl
       - go*
     * [10]realm.pl
       - stream.pl*
     * [11]registration.pl
       - confirmation.pl*
     * [12]reset.pl
     * [13]weblog.pl
     * [14]webring.pl
       - ring*
     * [15]./post
       
     * [16]colours.pl
     * [17]dice.pl
     * [18]private.pl
     * [19]who.pl
     * [20]zoom.pl
       
     [21]./ssi**
     * banner_rotate.pl -> ./ssi/rotate.pl
     * extlog.pl -> ./weblog.pl
     * gallery_rotate.pl -> ./ssi/rotate.pl
     * imagegal.pl -> ./ssi/gallery.pl
     * quicklog.pl -> ./weblog.pl
     * ssi_rotate.pl -> ./ssi/rotate.pl
     * static.pl -> ./portal.pl
     * textgal.pl -> ./ssi/gallery.pl
       
   [22]./erealms-admin
     * [23]./admin
       
     * [24]system.pl***
       - access.pl*
       - attrib.pl*
       - audit.pl*
       - contact.pl*
       - font.pl*
       - genre.pl*
       - gummy.pl*
       - poll.pl*
       - realm.pl*
       - rotate.pl*
       - template.pl*
       - weblog.pl*
     * [25]swho.pl
       
     .[26]/config
     * [27]cookie.pl
     * [28]home.pl
     * [29]ignore.pl
     * [30]gallery.pl
     * [31]gummies.pl
     * [32]puppet.pl
     * [33]puppeteer.pl
     * [34]realm.pl
       
     [35]./commandline
     * [36]convert.pl
     * [37]erealms.pl
     * [38]publish.pl
     * [39]release.pl
     * [40]rewrite.pl
     * [41]spel.pl
       
     [42]./eRealms
     * [43]Audit.pm
     * [44]Comm.pm
     * [45]Crypto.pm
     * [46]Database.pm
     * [47]Filter.pm
     * [48]Home.pm
     * [49]Image.pm
     * [50]Login.pm
     * [51]Mail.pm
     * [52]Option.pm
     * [53]Param.pm
     * [54]Post.pm
     * [55]Pull.pm
     * [56]Rotate.pm
     * [57]Spel.pm
     * [58]Stamp.pm
     * [59]Table.pm
     * [60]Template.pm
     * [61]Weather.pm
     * [62]Who.pm
       
   [63]./gz
     * [64]css.tar.gz
     * [65]gummies.tar.gz
     * [66]help.tar.gz
     * [67]images.tar.gz
     * [68]js.tar.gz
       
   changelog.txt
   installation.html
   installation.txt
   license.txt
   
   * Filenames are symbolic links relating to file above.
   ** Directory has special purpose, consult installation file for more
   details.
   *** File will change behavior based on filename.
   
                                 File Overview
                                       
./erealms

   This directory the bulk of the client scripts.   At least those that
   will be accessed frequently at varying stages of their use of the
   system.   As a result of this, it is recommended that these be placed
   into some sort of accelerated mode.
     * bio.pl
       Bio is a script that is designed to display contact information or
       redirect to a puppets home page if the users have so decided to
       allow it.   In realms, this functionality is enhanced as to allow
       for quick access to private messaging and ignoring.
     * board.pl
       - board
       - sysboard.pl
       Message board functionality for Ethereal Realms, using a
       simplified threaded model expanded for ease of use.
     * contrib.pl (Experimental)
       A new portal designed exclusively for contributors which allows
       access to all components without using native interfaces.
     * gallery.pl
       The client side portion of galleries, currently featuring text and
       image works.   Script includes searching capabilities,
       work/gallery overviews, detailed work navigable interfaces and
       user based comments and rating system.
     * gwho.pl
       A front-end interface available to end-users allowing them to see
       globally the activity in public realms.
     * mail.pl
       Internal mail system for Ethereal Realms, that allows for users to
       send messages directly to other users without having to making
       their identity known.
     * poll.pl
       Front-end interface for the polling system used by the site.
       Allows a user to place votes and see the results of the poll at
       any time.
     * portal.pl
       - go
       - static.pl
         The primary function of the portal is to authenticate users and
       direct them to a screen that will show them access to available
       features, functionality and allow them to access individual
       realms.
     * realm.pl
       - stream.pl
       Handles the primary interaction with the realms themselves.   In
       order to post, chat or view traffic on a realm one must make use
       of this script to proceed.
     * registration.pl
       - confirmation.pl
       System requires that users are registered in order to recall
       settings, handles and customizations.   This script handles the
       tasks of collecting initial information and making sure that the
       details provided such as the Email address are valid through the
       confirmation aspect of the script.
     * reset.pl
       This script allows one to reset passwords for users excluding
       anyone with a degree of privilege as to avoid abuse.
     * weblog.pl
       Allows for the passing of quick information to all users on the
       site.   This is done through a new style system which works like a
       weblog.
     * webring.pl
       - ring
       Integrated webring system for use by public and hybrid realms
       located on the system.
       
  ./erealms/post
  
   These scripts are used while interacting through a realm.  As a result
   of this, the bulk of these scripts will have the same access control
   measures put into place as to prevent unauthorized access.
     * colours.pl
       Colours display a guide listing all allowed colours in a realm
       against the customized background as to allow for a quicker
       selection.
     * dice.pl
       An advanced die roller that while supporting a multitude of
       systems can be templated to support simply one for realms catering
       to a certain role-play system.  Rolls can be made in public or
       sent privately based on the users preference.
     * private.pl
       Primary private message sub-system that will allow to send
       messages in private to people of the same realm or public realms
       if configured to do as such.  Administrators can also use this
       interface as to send messages globally to all realms at once.
     * who.pl
       Realm specific who is on that will originally display everyone in
       a specific realm then move to all public realms if requested.
     * zoom.pl
       Allows for the expansion of posts into an external window in order
       to allow for easier modification and spell checking.
       
  ./erealms/ssi
  
   Ethereal Realms has created scripts that are made to function in
   conjunction with Server Side Includes.   This allows dynamic content
   to be mixed in with seemingly static pages, without requiring people
   to use scripts directly.
   The above directory does not contain a series of scripts.  Instead it
   acts as a container for allowed SSI scripts that can be called by the
   web server itself.    Since the ./erealms-admin/ssi directory would
   normally not be directly exported, this effectively allows
   administrators to determine what is available to be passed.
   For ease of installation, all SSI are installed with the proper name
   in this directory.  To disable certain features, simply remove the
   symbolic links.
   
./erealms-admin

   A separate container for scripts that sites may not to have loaded
   under mod_perl or equivalent web acceleration processes.    This also
   allows one to selectively export directories granting a more granular
   control over the scripts themselves.
   
  ./erealms-admin/admin
  
   This contains all of the administrative scripts which require
   administrative level users to make changes to the system.   These
   scripts allow to change anything from a users properties to the look
   and feel of the site.
     * swho.pl
       Similar in principle to global who, this script has the additional
       features of seeing all associated usernames, warning levels and
       any active realm currently active.
     * system.pl
       - access.pl
       - attrib.pl
       - audit.pl
       - contact.pl
       - font.pl
       - genre.pl
       - gummy.pl
       - poll.pl
       - realm.pl
       - rotate.pl
       - template.pl
       - weblog.pl
       This administrative script creates a tabbed user interface that
       allows to control all administrative aspects of the site.  From
       realm creation to changes in specific wording of a button, this
       script will allow the changes to be made.
       Recent changes have also allowed the administrator to view
       administrative/supervisory actions taken on the side.   This audit
       entry viewer can become a very useful ally to determine where
       things have gone wrong.
       
  ./erealms-adming/config
  
   These configuration scripts do not require administrative access in
   order to be used.   However, their access levels vary from requiring
   supervisory/moderative access for their use to simply being available
   to all.
     * cookie.pl
       Script that allows for users to embed a browser cookie.  When used
       users will be able to bypass the normal authentication process.
     * home.pl
       The homepage component of Ethereal Realms which allows
       contributors to access files and images stored on the local
       server.    In addition to straight file access, the script allows
       for mass uploads, removals and image resizing.
     * ignore.pl
       Script that allows to ignore users on multiple levels, including
       simply replacing their title information.
     * gallery.pl
       Interface used to manage galleries, works and gallery news entries
       for any contributor of the site.
     * gummies.pl
       A view-only script that is generally used in conjunction with the
       puppet configuration panel and allows users to see gummies allowed
       on the site.
     * puppet.pl
       Puppet configuration script that handles the creation, cloning,
       modification and removal of puppets to be used in realm.
     * puppeteer.pl
       Puppeteer configuration panel allows a user to change user
       specific information from one interface.   This includes password
       and Email address changes, contact information updates etc.
     * realm.pl
       This supervisory/moderative level script deals with realm specific
       management as required for public and/or hybrid realms.  As with
       ./admin/system.pl, this script uses a tabbed interface to
       consolidate interfaces into one.
       
  ./erealms-admin/commandline
  
   Scripts in this directory are to be used at the commandline level only
   and do not carry with them the ability to interact as a CGI script and
   are used exclusively for maintenance/update tasks.
   NOTE: These scripts should NOT be exported through the webserver.
     * convert.pl
       This is a primitive tool that can be used in the migration of SQL
       dumps from MySQL databases to PostgreSQL.  It is used as a pipe
       from a process to generally a file.
     * erealms.pl
       Primary command-line utility used by Ethereal Realms for all of
       required maintenance.   This script can also be used to terminate
       streams, rotate banners in realms and synchronize Email addresses
       with eGroups.
     * publish.pl
       Used on the site in order to publish all text works in
       galleries.    This also allows for a global update of all works to
       new matching templates saving time and resources.
     * release.pl
       Creates an SQL dump of necessary code to release Ethereal Realms
       into the wild.   Generally administrators will find minimal use
       for this script since this is NOT a replacement for native
       database tools.
     * rewrite.pl
       This is especially useful for those that cannot move the libraries
       into a system search position.   Once the CHANGE values within the
       file are adapted to match the needs of the administrator, the
       script will adapt the files to use the proper instance of perl and
       find the appropriate modules.
     * spel.pl
       Daemon which will interact with iSpell and allow the system to run
       the actual through accelerated means such as Apache mod_perl.
       
./erealms-admin/eRealms

   This chat server aims to be somewhat object oriented. The following
   folder contains classes and their methods used throughout the chat
   system.
     * Audit.pm
       Auditing modules used to store administrative and supervisory
       tasks done within the system.
     * Comm.pm
       Handles all of the post gathering and inserting into the database
       system.
     * Crypto.pm
       Handles encoding features within Ethereal's parameters.
     * Database.pm
       Designed primarily to hide most of the work used to access and
       work with the database. Will handle things from making a database
       handle to retrieving documents.
     * Filter.pm
       A safer, centralized method of filtering HTML based on a few
       factors.  This includes a somewhat primitive version of HTML tag
       closing for those that tend to forget.
     * Home.pm
       Home page module, currently only used for the removal of home
       folders on the system.
     * Image.pm
       Basically a wrapper Image::Magick that simplifies common tasks
       employed on the system.
     * Login.pm
       Simple authentication module, as to make the scripts easier to
       deal with.
     * Mail.pm
       Mail handling module, which allows for the standardization and
       separation of the mailing process from the scripts.
     * Option.pm Option handling module.  Meaning options that are
       specific on a straight line.
     * Param.pm
       Handles all aspects of the parameters sent back and forth between
       browser and server.  Instance of the class also acts as an
       associative hash for easier retrieval of values.
     * Post.pm
       Handles the display of posts to the various viewing method
     * Pull.pm
       Module used to retrieve posts for users.
     * Rotate.pm
       Deals with the rotation of objects in the ethereal.Rotate table in
       order to be displayed in various areas of the site.
     * Spel.pm
       Spell checking module, which will work in conjunction with the
       spell checking daemon.    The typo in the name is done on purpose.
     * Stamp.pm
       Time stamp handling module used exclusively with posting.
     * Table.pm
       Default table creation, used extensively in the scripts along with
       Template.pm as to simplify design implementations.
     * Template.pm
       Makes use of templates to generate interfaces and widgets on the
       site, removing a great deal of repetition from the attribute code.
     * Weather.pm
       Handles the parsing of the METAR weather reports.  Also will
       retrieve them as needed for use in weather forecasts on the system
       and individual realms.
     * Who.pm
       Primary component of who.pls, handles the retrieval and display;
       of who is currently on.
       
./gz

   This contains a series of files which can be used to populate the
   system with a certain set of defaults.   These are generally not kept
   up to date, but will serve as a staging area.
     * css.tar.gz
       Example css code which will allow you to format the basics for the
       site.
     * gummies.tar.gz
       All images needed to host a base set of gummies are in this
       archive.
     * images.tar.gz
       Images used in the display of various pages for Ethereal Realms,
       allowing for simpler integration if need be.
     * help.tar.gz
       Documentation related for use of Ethereal Realms from the users
       perspective.
     * js.tar.gz
       Base javascript used on the system.
       
                                 Installation
                                       
   Before you even begin you will need to retrieve a series of perl
   modules that were not included with Ethereal realms.    This is
   primarily for the fact that they were not created by the author of the
   scripts and thus where not included. All of these modules can be
   retrieved by using CPAN.
     * Digest::MD5
       MD5 cryptographic hashing
     * Image::Magick
       Imagine manipulation library, replacement for Image::Size other
       then legacy use.
     * Image:Size
       Used to determine the size of retrieved image, legacy library used
       when Image::Magick fails.
     * LWP::UserAgent
       Used in the retrieval of images for the module above.
     * MIME::Entity
       Tools for handling MIME encoded Emails, used for sending posts to
       users.
       
   The CPAN module itself can greatly simplify the installation of the
   above modules.  As it also makes sure that dependencies are installed
   in order to properly install the main modules.   In order to use CPAN
   simply type in the following at the command prompt:
 > perl -MCPAN -e shell;

   Then type in the following:
 cpan> install DBI
 cpan> install DBD-Pg
 cpan> install Digest::MD5
 cpan> install Image::Magick
 cpan> install Image::Size
 cpan> install LWP::UserAgent
 cpan> install MIME::Entity

   A new requirement for Ethereal Realms needed to handle the publishing
   of documents over to PDF is the addition of the HTMLDOC
   distribution.   In order to install and make use of HTMLDOC one simply
   needs to visit [69]http://www.easysw.com/htmldoc/ and follow their
   instructions.    The source code and binary versions are available
   without their associated fee.
   After these modules have been downloaded and installed, you should
   download the tar.gz file containing this distribution.  This is done
   by decompressing the file, make sure all of the listed files above are
   in fact there and do the following steps.
   NOTE: The installation of the modules above will most probably need
   other modules. Read the installation instructions of each module
   specifically to determine what is required before installation.
   Copy the contents of ./erealms-admin/eRealms so to that it can be
   found by perl when it searches for modules.
   In the authors case the location was:
   /usr/lib/perl5/site_perl/5.005/eRealms/ (Linux RedHat 6.0) or
   /usr/local/libdata/perl5/site_perl/eRealms/ (OpenBSD 2.7-3.4)
   NOTE:  If the scripts use the wrong instance of Perl or if you cannot
   move the modules into a searched path.   Look at the
   ./erealms-admin/commandline/rewrite.pl file for a possible solution.
   The next step involves exporting the scripts so that they can be made
   accessible through a web server.  In most cases you can create
   symbolic links to ./erealms, ./erealms-admin/admin and
   ./erealms-config to a directory that allows execution of scripts.
   This can either be a dedicated directory such as
   http://www.somesite.org/cgi-bin or simply enabled to execute when
   scripts are present.
   NOTE: Apache will not be default execute a script mixed in with normal
   HTML documentation.  Look into using the ExecCGI option for an
   exported directory in order to gain that functionality if need be,
   NOTE: All scripts must be executable in order for them to be run by
   the webserver.   In order to confirm that all scripts are, you can
   complete the following command under both ./erealms and
   ./erealms-admin.
> chmod +x `find ./ -type f`

   Next, configure the database according to the specific instructions
   listed within the ./erealms-admin/commandline/dumps directory.   The
   current database installation and configuration system uses database
   dumps to makes things easily and less complicated then changes done in
   Database.pm.
   As of version 1.3.0 and above there are no longer DBMs for use with
   Ethereal Realms.  They have been removed due to problems with Perl on
   certain distributions or Unix variants.  As a result the next step
   requires you to change one file other then the database dumps
   themselves:  Database.pm
   Lines 85 to 88 of eRealms::Database should be adapted to meet your
   needs.  While this may seem less gallant in a way, it does allow for
   the tags to be placed in the database and allows for the subsequent
   use
   of multiple web servers with one singular or clustered database as a
   back end.
   Finally, all of the scripts including administrative scripts should be
   operational.  Please make use of system.pl in order to change from the
   defaults used by Ethereal itself, even though we do not mind added
   visitors.
   NOTE:  Ethereal Realms 3.0.0 was final release of the functions under
   function under MySQL.  Future versions have been optimized for
   operation under PostgreSQL and can be found at the following link:
   [70]http://www.postgresql.org 
