Installing Achievo
==================

Read this first
---------------
Despite our efforts to keep this INSTALL file as accurate as possible, there
might be situations in which the described procedure does not work.
In this case send an email to sandy@achievo.org or visit our forums at
http://www.achievo.org/forum and we will try to help you out.

Upgrading from an earlier version
---------------------------------
This INSTALL file assumes that you install Achievo for the first time.
If you are upgrading from an earlier version, check the UPGRADE file for
upgrade instructions.

Requirements
------------

- A webserver capable of running php5 scripts
  (Apache is a good choice, http://www.apache.org)
- PHP5 (http://www.php.net, version 5.2.0 or newer)
- MySQL5+ (http://www.mysql.org)

The following are requirements for optional features of Achievo:

- There are several graphical charts in Achievo. For these to work, PHP should
  be installed/compiled with GD support (http://www.php.net/gd).

- To make use of the OpenOffice document generator, both the 'zip' and 'unzip'
  binaries should be in the path.

- To make use of the cronned reminder scripts, you must be able to setup cron
  on the machine where you install Achievo.

Installation Procedure
----------------------

Note that this guide does not describe how to install a webserver or PHP
or a database server. See the documentation for these programs on how to
install those. This installation guide assumes that you already
have a working webserver with PHP support and a MySQL database installed.

1) Untar the entire achievo archive to a place where you can access it with
   your webserver.

   example:

   $ cd /usr/local/apache/htdocs              # change to a web accessible
                                              # directory
   $ tar xzvf ~user/achievo_x.x.tar.gz        # unpack the tar.gz file

   optional:

   $ ln -s achievo_x.x achievo                # make a symbolic link

2) Make the 'achievotmp' directory (and its subdirectories) writable for the
   webserver. On Linux/Unix you can run the following command:

   $ chown -R username achievotmp documents doctemplates modules/docmanager/doctypetemplates

   Replace 'username' with the username that you use to run the webserver,
   for example 'nobody', 'apache' or 'www'.

3) Create an empty database in mysql and a user that has create, alter,
   select, insert, update and delete-access on the database.

   example (assuming your mysql root password is 'secret'):

   $ mysql --user=root --password=secret mysql

   mysql> create database achievo_1_4;
   mysql> grant create,alter,select,insert,update,delete,lock tables,
          create view, drop, index 
          on achievo_1_4.* to achievo@localhost identified by 'secret';
   mysql> quit;

   This creates a database named 'achievo_1_4', and a user with username
   'achievo' and password 'secret'.

   Note: the create and alter privileges are only needed during installation
   and upgrades. You can revoke these privileges once the installation is
   complete.

4) Edit the file config.inc.php in the achievo directory, and set the
   $config_db variable to match your setup.

   example:

   $config_db["default"]["host"] = "localhost";
   $config_db["default"]["db"] = "achievo_1_4";
   $config_db["default"]["user"] = "achievo";
   $config_db["default"]["password"] = "secret";

5) In the same configuration file there is a variable
   $config_administratorpassword. This is the password you need on your
   first login. You might want to change this password.

   There are some other things in the config-file that you can change, but
   for your first configuration, you can leave those settings to the default.

6) After editing the configuration file, point your browser to the setup.php
   script in the Achievo directory. For example:

   http://yourserver/achievo/setup.php

   You'll be prompted to login. Enter 'administrator' as username and the
   password you've set in step 4.

7) Follow the instructions. Achievo will first perform some system checks, to
   see if your PHP configuration is up to date. If it discovers any problems,
   it will tell you how to solve them. If everything is ok, it will install
   the database for you.

8) Once the setup.php script is completed, you'll be ready to run Achievo.
   You can point your browser to the Achievo directory, like this:

   http://yourserver/achievo/

   If this is the first time you're using Achievo, you might want to take the
   Guided Tour on http://www.achievo.org/wiki/Guided_Tour, which will show
   you everything you should do to make Achievo useable for your users.

9) Achievo contains some useful cron scripts that can be run periodically from
   a cron job. See the CRON file for available cron features and instructions.

