Galt Escrow Agency System Installation
---- ------ ------ ------ ------------


1. Create an e-gold account

    You will need to create an account on the e-gold system, to hold escrow
    funds.  Go to http://www.e-gold.com, and follow the instructions to
    create an account.

    During this process, you will need to choose a passphrase for logging in,
    as well as an alternate passphrase used by the Shopping Cart Interface.
    It's quite important to safeguard both of these carefully.  Anyone who
    discovers the passphrase can transfer all funds out of the account in a
    matter of seconds.  Anyone who discovers the alternate passphrase can
    fabricate deposits through the Shopping Cart Interface.

    The account will need to be enabled for automation.  It's recommended
    that you allow automation access only from your web server's IP address.
    You should also seriously consider the Account Sentinel (AccSent) options
    for detecting IP address changes on access through a browser.


2. Create or choose a MySQL database

    The Galt Escrow Agency system needs a MySQL database to store its data.
    The table names all start with "gea" (see includes/tables.php), so it's
    possible to share the database with other applications.  The MySQL
    software must be version 3.23 or higher.

    You will need to choose a MySQL username and password to be used for
    access to the database.  This user must have SELECT, INSERT, UPDATE and
    DELETE privileges for the tables listed in includes/tables.php.  For
    MySQL 4.0.2 or higher, LOCK TABLES privilege is also needed.

    During installation, CREATE and DROP privileges are required.  You may
    specify a separate MySQL username and password for the installation
    process if you like.


3. Configure the web server for PHP options

    The file visible/.htaccess contains some PHP options that should be in
    effect for proper system operation.  This file will be read and processed
    automatically if all of the following conditions hold:

      * Your web server is Apache.
      * PHP is installed as an Apache module.
      * Apache has either "AllowOverride Options" or "AllowOverride All"
        in its configuration.

    Otherwise, you should configure your web server to achieve the equivalent
    effect somehow.  In PHP 4.1 or 4.2, it's particularly important that
    register_globals and session.use_trans_sid be turned off.


4. Create directories on the web server

    Three directories are needed in the web server file system, as follows:

      visible:   This contains the PHP scripts that browsers may invoke, plus
                 a few other files.  Some URL must map to this directory.
                 Generally this means the visible directory must be somewhere
                 underneath DocumentRoot.  The process that runs the PHP
                 scripts will need read access to the files in this directory.

      includes:  This contains PHP include files that are used by several
                 scripts.  This directory doesn't have to be underneath
                 DocumentRoot, and in fact it typically should not be.  The
                 process that runs the PHP scripts will need read access to
                 the files in this directory.

      documents: This is used to hold documents such as versions, defect
                 reports, arguments and opinions.  This directory doesn't
                 have to be underneath DocumentRoot, and in fact it typically
                 should not be.  The process that runs the PHP scripts will
                 need read access to the existing files in this directory, as
                 well as the ability to create new files there.


5. Finish installation

    Upload the contents of the visible, includes and documents directories in
    the distribution to the corresponding directories on the web server.  Be
    sure to use binary mode for the PNG files (visible/figure?.png).

    The following files need to be configured:

      visible/includes.php
      includes/configure.php
      documents/configureInstall.php

    If you're familiar with PHP, you can edit these files directly before
    you upload them, and then point your browser to the URL that maps to
    visible/install.php, to perform the installation.

    Alternatively, you can run the setup script as follows:

      a. Set write access to the three files listed above (e.g., chmod 666).

      b. Point your browser to the URL that maps to visible/setup.php, and
         follow the instructions there.

      c. Remove write access from the first two files, visible/includes.php
         and includes/configure.php (e.g., chmod 644).  The third file,
         documents/configureInstall.php is deleted at the end of the
         installation process anyway.

      d. After installation is complete, you may want to delete the file
         visible/setup.php, so someone doesn't accidentally invoke it.


6. Create links to the initial entry point as needed

    The URL that maps to visible/index.php is the initial entry point to
    the Galt Escrow Agency system.  From here, new users can register, and
    existing users can log in.



Administration
--------------

    The administrator user (named "administrator" by default) is created
    during the installation process, and has special privileges.  Escrow fees
    and maintenance fees are paid to this user's general escrow account.
    Although this user can enter into contracts as buyer or seller, you
    will probably find it more convenient to register another user name
    representing yourself for this purpose.

    You should safeguard the administrator password carefully.  You may want
    to turn on the "challenge if new IP address" flag under "Edit Security
    Configuration".

    When you are logged in as administrator, you can list users from the
    public pane, like anyone else.  But when you select a user from the list,
    the view pane will show all information about that user, not just the
    fields that are visible to the public.  You can also update the following
    permission flags:

      * allowed as buyer
      * allowed as seller
      * allowed as arbitrator
      * allowed as default arbitrator

    If you want the user to be a default arbitrator, you will need to turn on
    both "allowed as arbitrator" and "allowed as default arbitrator".

    Also from the view pane for a user, you can act as proxy for that user.
    You can then do anything which that user would be able to do, such as
    propose or accept a schedule, or submit a claim.  Typically, you would
    use this privilege to reset someone's password.

    An additional pane labelled "Administration" is present when you are
    logged in as administrator.  There are links from here to edit the system
    configuration and to change the e-gold passphrase or the passphrase mode.

    You will be responsible for routine maintenance, which is done from the
    administration pane.  Below are the routine maintenance functions:

      * process transactions from e-gold
      * process withdrawal requests
      * perform internal balance audit
      * perform external balance audit

    Normally, you should do all four functions on some regular basis,
    typically once a day.

    Transactions to be processed from e-gold include the following:

      * a deposit made via a manual spend
      * a deposit made via the Shopping Cart Interface, which for some
        reason was not credited right away
      * the receive fee associated with a deposit
      * the monthly storage fee, which is posted to the administrator's
        general escrow account
      * a withdrawal request that was in limbo, where the e-gold server
        actually performed the spend

    For reference, here are the possible states of a withdrawal request:

      * pending
      * cancelled
      * rejected
      * in limbo
      * stalled
      * completed

    Most of these are self-explanatory.  The state "in limbo" means that
    the spend message was sent to the e-gold server, but no reply was
    received.  In this case, the e-gold server may or may not have actually
    performed the spend.  The state "stalled" means that the spend message
    was sent to the e-gold server, and an error reply was received.
