INSTALLATION DIRECTIONS FOR ATHENARMS VERSION 5.0 PRE RELEASE 1

AthenaRMS is a Request Management System Covered under the GNU Public Licence,
Version 2.  See the file README for details.


REQUIREMENTS

Unix - Solaris 8, RedHat 7.3, FreeBSD 4.7
Apache - 1.3.26+                        http://httpd.apache.org/
PHP - 4.2.3+                            http://php.net/
PHP Must be built with: mcrypt, postgres, session, and mbstring support
The mailparse extension must also be installed.
PearDB, if not part of your PHP distrib, must also be installed.

Sendmail or qmail.  (See the section below
                       on configuring email)    http://qmail.org/
Postgres - version 7.3.2+                       http://postgresql.org/
adodb  - version 2.5.0+                         http://php.weblogs.com/ADODB/


AthenaRMS has been tested with the versions noted above, and may work 
with others. Please let us know what variations are working for you 
by sending a note to [[athenadevelopers@mnl.com]].

Note about back end databases:
AthenaRMS 5.0 was developed using Postgres . We have
almost completed modifications to allow it to work with MySQL 3.23 and 
above.

GETTING THE SOURCE

The latest version of AthenaRMS is available at
http://athenarms.com/download in tar.gz format
The source is provided under the GNU Public license. Please see
the LICENSE file for details.

GENERAL INSTALLATION

1)   Ensure that Postgres is set up correctly.
      For instructions, see:
      http://www.postgresql.org/docs/7.3/interactive/installation.html

      Then create a databas for use by AthenaRMS and a user account and 
      password for the  application. Make note of the parameters, as 
      they will be added to your athena.config file.

    * untar AthenaRMS into an installation directory.  This directory should
      NOT be under your web tree.  Suggested locations are:

      /usr/local/athena
      /opt/athena
      /home/athena

      Example:

      cd /tmp
      curl -O http://athenarms.com/download/athenarms-5.0[[alpha]].tar.gz
      cd /usr/local
      gunzip < /tmp/athenarms-5.0[[alpha]].tar.gz | tar xvf -
      ln -s athenarms-5.0[alpha]] athena

      (If you have GNU tar, you can untar in one command with the following:
       tar xvzf /path/to/athenarmsRELEASE.tar.gz)

    * Change your working directory to the root release directory

      cd /usr/local/athena

    * copy athena.conf.sample to athena.conf and edit it to reflect your
      installation.  Read the comments inside and make changes; the required
      fields to change are $athena_root and $db_config.

      cp athena.conf.sample athena.conf
      vi athena.conf

    * Change directory to bin and run install.php.  This assumes that php
      has been built to run as an executable on your system and is in your
      path.

      cd bin
      php install.php

    * If the installation went correctly, you will be see the following
      message:

      "Installation is finished, now you need to configure your web and
        email services.

      For web, make sure http://path.to.your/athena/
      points at /path/to/installdir/htdocs
      You can usually do this with a symlink or an entry in httpd.conf."

CONFIGURING YOUR WEB SERVER AND DNS

     There are two basic ways to install athena for the web: absorbing an
     entire hostname, or under a specific path.

     Option 1: Whole hostname

	 You run "example.com" and you want Athena to have a whole hostname all
	 to itself (good for you!).  Therefore you put into install.php the url
	 "http://athena.example.com"

	 You need to first make sure you actually create the DNS entry for 
	 "athena.example.com" and that it points at your webserver.

	 Next, configure your webserver so that / points at 
	 /path/to/your/athena/install/htdocs

	 For example, if you're running Apache and you installed Athena in
	 /usr/local/athena, your httpd.conf for Apache might look like:

	 <VirtualHost *>
	   ServerName athena.example.com
	   DocumentRoot /usr/local/athena/htdocs
	 </VirtualHost>

     Option 2: Specific path

	You run "www.example.com" and host all sorts of company 
        information on that site.  You decide you want Athena stuff to be
	at http://www.example.com/support/, so that's what you told install.php.
	You have Athena installed in /usr/local/athena, and your Apache config
	for www.example.com already has an entry like:

	DocumentRoot /usr/local/www/data

	So you do:

	cd /usr/local/www/data
	ln -s /usr/local/athena/htdocs support

	Now any access to http://www.example.com/support/ will be hitting
	Athena.  You could also do this in the Apache config itself with:

	Alias /support/ /usr/local/athena/htdocs/

     In either case, make sure for the Athena directory you have full override
     permissions and PHP turned on:

     AllowOverride any

CONFIGURING EMAIL

     Regardless of whether you're sharing a web hostname with other services
     or not, Athena requires a dedicated email domain name to receive mail
     on.  In the default installation, the email and web domains are the
     same, but if you cannot dedicate mail sent to any username 
     @your.web.domain to Athena, you will need to choose a separate email 
     domain; this can be done in the RMS Settings section of the admin 
     screen.

     Whatever email domain you choose must be set up in DNS.  Let's assume
     for the rest of this document that you're using "athena.example.com"

     How you set up your mail server depends on what mailserver you're using.
     We currently have instructions for qmail and sendmail, but there's no
     reason it shouldn't work with others (please send us how-tos!)

     CONFIGURING WITH QMAIL

        1. Edit /var/qmail/control/virtualdomains
           and add an entry of the form: domainname:athena
        2. Make sure you have a
           /var/qmail/alias/.qmail-athena-default file which
           contains: 
	   |preline /path/to/php/bin/php -q /path/to/athena/lib/handle_email.php
	   (for example:
	   |preline /usr/local/bin/php -q /usr/local/athena/lib/handle_email.php
	   )
        3. Restart qmail-send; if using the recommended
           installation directions you can do this with
                   svc -t /service/qmail-send

      CONFIGURING WITH SENDMAIL

	1. Make sure your sendmail is configured with virtusertable support.
	   In your sendmail.mc, this would be something like:
	   FEATURE(virtusertable, `hash -o /etc/mail/virtusertable')
	2. Edit the virtusertable (/etc/mail/virtusertable) and add a line like:
	   @your.email.domain	    athena
	   (e.g.:
	   @athena.example.com	    athena
	   )
	3. Edit the aliases file (usually /etc/mail/aliases) and add:
	 athena: "|/path/to/php/bin/php -q /path/to/athena/lib/handle_email.php"
	   (e.g.:
	 athena: "|/usr/local/bin/php -q /usr/local/athena/lib/handle_email.php"
	   )
	4. Rebuild the virtusertable db:
	   makemap hash virtusertable.db < virtusertable
	5. Rebuild the mail aliases db:
	   newaliases
	6. If you just added the virtusertable support, you'll also need to
	   restart sendmail.

LOGGING IN TO FINISH INSTALLATION

    1) Open a web browser and point to the location that you
       specified during installation to finish the installation.

       Note: the default user/password for a fresh install is as
             follows:

              user: 1
              password: password

       BE SURE TO CHANGE THE DEFAULT PASSWORD

       1) Once logged in, select "admin" from the top menu bar.
       2) Select "Edit Support People" from the Admin screen
       3) Edit the person "default,default"
       4) Enter a new  password at the bottom of the page,
          and optionally change the default user name, first and last name,
	  etc.

TESTING YOUR DEFAULT INSTALLATION

Once you have your default installation complete, you should perform the
following tests to ensure correct functionality.

  1) Adding tickets via the default web forms

   From the home page, select "add ticket". Fill in all necessary fields
   and submit the form.  From the home page, the count of "my open" and
   "all open" should increase by one.  click on the numeric link for either
   "my open" or "all open" to view and edit the ticket.

2) Adding Tickets via email

   Send an email to the default address noted during installation,
   or what ever you changed it to during the customization.  By
   default, the address would be "default@emaildomain", where email
   domain was set during installation.  Verify that the email
   was inserted into the default instance as in (1) above.  If
   the ticket was not inserted, you need to retest your email
   configuration.  Check the log file specified in your athena.conf for
   any email-related error messages.

3)  Editing tickets and adding comments to your athena instance

     To edit a ticket you can select the ticket by clicking on the
     "my open" or "all open" numeric link.  Try changing the status
     on the ticket, and saving the results by clicking on the "save"
     button at the bottom of the page.  Then reload the page.  Verify
     that the page still has the new value that you just set.

     To add comments, select the "esc. reply" link at the top of the
     page.  Enter a comment and press the "submit button.  Verify
     that the comment has been logged as a comment for the ticket.

4) Accessing tickets as an end user via one-time URLS

    When new tickets are submitted, the end user will receive an email
    with a link to a one time URL that provides access to the ticket.
    Test the link in the email response sent to one of the preceding tests
    (assuming you used a valid email address).  Verify that the URL
    works and provides access to the ticket.

CUSTOMIZING YOUR ATHENA INSTANCE

  You can customize your athena instance by adding support people and custom
  attributes, and by creating custom templates for all administration pages
  within the instance.  See the Administrator's guide for details.


ADDING ADDITIONAL ATHNEARMS INSTANCES

Once you have your finished your basic installation for your default 
instance, you can create additional instances through the admin 
interface.
Instances can be created as sub directories under a single web domain,
or as completely separate web domains.


WHERE TO FIND OUT MORE?

The best place to start is with the documentation. See the
administrator's guide and the user's guide, both part of this distribution.

AthenaRMS's homepage is at http://athenarms.com

The open source project for athena is hosted at sourceforge:
AthenaRMS is hosted at http://athenarms.sourceforge.net.

There are links to typical email discussion lists at both locations.
