~eventum-developers/eventum/trunk

Installation Process
====================

Installation is pretty simple and quick. Eventum already bundles the libraries
that it needs to work properly:

- JpGraph 1.5.3 (last GPL version)
- Smarty 2.6.18 (http://smarty.php.net)
- PEAR packages:
   Auth_SASL 1.0.2
   DB 1.7.13
   Date 1.4.7
   HTTP 1.4.0
   HTTP_Request 1.4.2
   Mail 1.1.14
   Mail_Mime 1.5.2
   Mail_mimeDecode 1.5.0
   Net_DIME 0.3
   Net_POP3 1.3.6
   Net_SMTP 1.2.10
   Net_Socket 1.0.8
   Net_URL 1.0.15
   PEAR 1.6.2
   Text_Diff 0.3.1
   XML_RPC 1.5.1
- dTree 2.0.5 (http://www.destroydrop.com/javascript/tree/)
- dynCalendar.js (http://www.phpguru.org/dyncalendar.html)
- overLIB 3.5.1 (http://www.bosrup.com/web/overlib/)
- A few other small javascript libraries

Anyway, all you should have to do is place the Eventum files in a directory that
is viewable from the web, and open it up with your browser. Eventum should
redirect you to the installation screen, and it will try to guess some of
required parameters, like path in the server and etc.

  http://yourserver.com/eventum/

If Eventum's installation script finds that it needs a few directories or
permissions changed, it will print the warnings before actually displaying
the installation screen. So just fix what it says it's wrong/missing and
everything should go well.

After the installation is done, you should go and take all of the available
privileges from the '/setup' directory, so other people are not allowed to
go in there and mess with your configuration.

IMPORTANT: If you already have an installation of Eventum, please read the
UPGRADE file.

IMPORTANT: If you are having trouble getting Eventum to work, please read
the trouble shooting section of the FAQ file and visit
http://eventum.mysql.org



Setting Up The Required Cron Scripts
====================================

1)- Mail Queue Process (process_mail_queue.php)

Beginning with the first release of Eventum, emails are not directly sent out
from the various scripts, but rather added to a mail queue table that is
processed by a cron job. If an email cannot be sent, it will be marked as such
in the mail queue log, and the cron job script will re-try to send it again the
next time it runs.

* * * * * <PATH-TO-EVENTUM>/process_mail_queue.php

The above line will run the mail queue script every minute. To setup the SMTP
server that Eventum should use to send these queued emails, go to:

 Administration >>> General Setup > SMTP (Outgoing Email) Settings


2)- Email Download (download_emails.php)

In order for Eventum's email integration feature to work, you need to setup a
cron job to run the script above every so often. The following is an example of
the required crontab line:

0 * * * * <PATH-TO-EVENTUM>/download_emails.php username_here mail.domain.com INBOX

The above will run the command every hour, and will download emails associated
with the given email account. If you have more than one email account, you may
add another crontab entry for the other accounts. To setup the email integration
feature with the appropriate email accounts, go to:

 Administration >>> Manage Email Accounts

You can also call the download_emails script via the web, using the following URL:
http://eventum_server/<PATH-TO-EVENTUM>/download_emails.php?username=username_here&hostname=mail.domain.com&mailbox=INBOX

You need to copy it first to htdocs directory.

3)- Reminder System (check_reminders.php)

The reminder system was designed with the objective as serving as a safe net
for issues that need attention. Depending on what configuration you create, you
may have several reminders (or alerts) be sent out whenever an issue needs
attention, for whatever parameter you may deem necessary.

*/10 * * * * <PATH-TO-EVENTUM>/check_reminders.php

It is recommended that you run the reminder cron job every 10 minutes, so it
won't flood you with alerts too often, but it would still be enough to handle
most cases.


4)- Heartbeat Monitor (monitor.php)

The heartbeat monitor is a feature designed for the administrator that wants to
be alerted whenever a common problem in Eventum is detected, like the database
server not being available anymore, or maybe when the recommended permissions
for certain configuration files are changed. Please note that before running
the heartbeat monitor, you may need to customize some of the checks to be
appropriate for your own system, particularly the permission and file checks on
Monitor::checkConfiguration().

*/10 * * * * <PATH-TO-EVENTUM>/monitor.php




Other Features Requiring System Setup
=====================================

Note: Starting with Eventum 1.5.2 there is a new way of routing emails,notes
and drafts. You will need to setup up a wild card address to route all
messages that should be in eventum (usually issue-<number>@<domain>,
note-<number>@<domain> and draft-<number>@<domain>) to an email account. Then
add that email account to eventum by going to the email account administration
page:

  Administration >>> Manage Email Accounts

When setting up the account, check 'Use account for email/note/draft routing'.
Once the account is added, set the account to be downloaded as describe above
(2)- Email Download).


1)- Email Routing Script (route_emails.php)

The email routing feature is used to automatically associate a thread of emails
into an Eventum issue. By setting up qmail (or even postfix) to deliver emails
sent to a specific address (usually issue-<number>@<domain>) to the above
script, users are able to use their email clients to reply to emails coming from
Eventum, and those replies will be automatically associated with the issue and
broadcasted to the entire notification list.

The entire email message should be passed as standard input to the script, and
the only parameter to it should be email account to which this email should be
associated with. The following is an example of a successful run of this script:

./route_emails.php 1 < example_note_email.txt

This script also saves any routed messages it receives in a separate directory,
so you would never lose emails. Create a 'routed_emails' sub-directory under
/<PATH-TO-EVENTUM>/misc/ and setup the proper permission bits on it.

IMPORTANT: Please be aware that depending on the MDA that you are using (qmail,
postfix or whatever), you may need to manually change the exit codes used in
this script to handle the proper signals to the MDA. For example, postfix uses
exit code 78 to signal a configuration problem, but other agents may need
different exit codes.


2)- Note Routing Script (route_notes.php)

The note routing feature is used to automatically associate a thread of notes
into an Eventum issue. By setting up qmail (or even postfix) to deliver emails
sent to a specific address (usually note-<number>@<domain>) to the above
script, users are able to use their email clients to reply to internal notes
coming from Eventum, and those replies will be automatically associated with
the issue and broadcasted to the notification list staff members.

The entire email message should be passed as standard input to the script. The
following is an example of a successful run of this script:

./route_notes.php < example_note_email.txt

This script also saves any routed messages it receives in a separate directory,
so you would never lose notes. Create a 'routed_notes' sub-directory under
/<PATH-TO-EVENTUM>/misc/ and setup the proper permission bits on it.

IMPORTANT: Please be aware that depending on the MDA that you are using (qmail,
postfix or whatever), you may need to manually change the exit codes used in
this script to handle the proper signals to the MDA. For example, postfix uses
exit code 78 to signal a configuration problem, but other agents may need
different exit codes.


3)- Draft Routing Script (route_drafts.php)

The draft routing feature is used to automatically associate a thread of drafts
into an Eventum issue. By setting up qmail (or even postfix) to deliver emails
sent to a specific address (usually draft-<number>@<domain>) to the above
script, users are able to send drafts written in their mail client to be stored
in Eventum. These drafts will NOT broadcasted to the notification list.

The entire email message should be passed as standard input to the script. The
following is an example of a successful run of this script:

<PATH-TO-EVENTUM>/route_drafts.php < example_note_email.txt

This script also saves any routed messages it receives in a separate directory,
so you would never lose drafts. Create a 'routed_drafts' sub-directory under
<PATH-TO-EVENTUM>/misc/ and setup the proper permission bits on it.

IMPORTANT: Please be aware that depending on the MDA that you are using (qmail,
postfix or whatever), you may need to manually change the exit codes used in
this script to handle the proper signals to the MDA. For example, postfix uses
exit code 78 to signal a configuration problem, but other agents may need
different exit codes.


4)- IRC Notification Bot (irc/eventum-irc-bot)

The IRC notification bot is a nice feature for remote teams that want to handle
issues and want to have a quick and easy way to get simple notifications. Right
now the bot notifies of the following actions:

 - New Issues
 - Blocked emails
 - Issues that got their assignment list changed

To invoke the notification bot and let it running on the server, this is the
proper command:

./irc/eventum-irc-bot &

NOTE: You will need to manually edit config/irc_config.php to set your appropriate
preferences, like IRC server and channel that the bot should join. An example
config file is located in setup/irc_config.php


5)- Command-line Interface (cli/eventum)

The Eventum command-line interface allows you to access most of the features
of the web interface straight from your command shell. In order to install it,
you will need PHP and if you use SSL, the curl and openssl PHP extensions.

Assuming you have the requirements properly setup::

 - Just copy the <PATH-TO-EVENTUM>/cli directory to another location (e.g.
   copy to ~/bin/)
 - Add that location to your PATH environment variable
 - Set the required permission in the script (chmod 700 ~/bin/eventum)
 - Copy the new .eventumrc example file to your home directory
   (cp ~/cli/eventumrc ~/.eventumrc)
   -> Edit ~/.eventumrc and set the appropriate values in there
 - Run it (eventum --help)
 - Test it with 'eventum 1' (display issue #1 details)