********************************************************************************
* Last-Modified: $Date: 2001/04/25 08:54:17 $ 
* Version: $Id: INSTALL,v 1.6 2001/04/25 08:54:17 burton Exp $
* Author: Kevin A. Burton ( burton@openprivacy.org )
********************************************************************************
    
====== SIERRA INSTALL NOTES ======

Sierra can be setup in numerous configurations.  What follws is a generic
setup to get you started.

=== REQUIREMENTS:

(necessary libraries may be found under SIERRA_HOME/lib)

- JDK 1.2.2 or later.  (GNU Java Compiler may also work)

- Apache Xerces 1.2.3 (http://xml.apache.org)

- Arrowhead snapshop (http://arrowhead.sourceforge.net)
  - This should be included in the distribution.

- MySQL 3.23.33 or greater (http://www.mysql.com)
  - Could run on earlier versions but this hasn't been tested.  

=== Test install:

The Test install builds Sierra and runs the necessary Unit Tests to make sure
your installation is correct.  Developers can also use this installation
mechanism to test Sierra's operation and how everything ties together.

STEPS:

- Install required libraries.  Make sure that the following are in
  your CLASSPATH:

    $SIERRA_HOME/lib/*.jar


- Build Sierra:

  - Change to $SIERRA_HOME/build and compile:

        shell% cd $SIERRA_HOME/build
        shell% java org.apache.tools.ant.Main

    - If you have all the necessary libraries on your system this
      should build Sierra and place a jar in $SIERRA_HOME/bin/sierra.jar


- Create your database:

  - Install MySQL (this is outside the scope of this document)

  - Make sure mysqld is running and listening to port 3306

  - Create the database by running all scripts in $SIERRA_HOME/src/sql 

        shell% cd $SIERRA_HOME/src/sql
        shell% mysql < *.sql


- Update the sierra.properties file

  - Place the sierra.properties file in your /etc or {java.home} directory.

  - Update the sierra.properties file so that the component
    'talon:///component-name/product/sierra/name/database_connection_pool'
    points to your new database.  This must have the correct
    host/user/password/port information in order to connect.

    shell% cp $SIERRA_HOME/src/config/sierra.properties $JAVA_HOME
    shell% emacs $JAVA_HOME/sierra.properties

    or
    
    shell% cp $SIERRA_HOME/src/config/sierra.properties /etc
    shell% emacs /etc/sierra.properties


- Run the tests.

  - Change to the $SIERRA_HOME/build directory.

  - Run Ant to drive your tests:

    shell% cd $SIERRA_HOME/build
    shell% java -Dtalon.project=sierra org.apache.tools.ant.Main test


- If you see:
  (java.sql.SQLException): Server configuration denies access to data source
  this is mysql exhibiting some permissions problems.  There are two easy
    ways to deal with these (other suggestions are welcome):

  - change root's user profile to allow connections from anywhere

      mysql> use mysql
      mysql> update user set host='%' where user='root';

  - create a new user that has access from anywhere

      mysql> use mysql
      mysql> insert into user values ('%','sierra','',
          -> 'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y');

    - be sure to update your sierra.properties file with the new user name.
    - (BUG: adding a password seems to break the test)


At this point Sierra should run fine on your system.  All tests should pass and
you should be ready to either write additional unit tests or deploy Sierra.
