Thanks for downloading Orangutan.

REQUIREMENTS
============

 o Redmine with MySQL
   http://www.redmine.org/
   Orangutan was tested on Redmine 1.0.x.

 o Jabber
   Any Jabber server.

 o Perl
   Any version should work.

 o Perl Net::XMPP library
   Orangutan was tested with Net::XMPP 1.02.

    * For Debian-like distros: apt-get install libnet-xmpp-perl

 o Perl XML::Writer and XML::Parser libraries

    * For Debian-like distros: apt-get install libxml-writer-perl libxml-parser-perl

 o Perl DBI library with MySQL driver

    * For Debian-like distros: apt-get install libdbi-perl libdbd-mysql-perl

 o Ruby XMPP4R library

    * For Debian-like distros: apt-get install libxmpp4r-ruby

    * For all (or if libxmpp4r-ruby is not available): gem install xmpp4r

NOTES
=====

 o Orangutan accesses Redmine's MySQL database directly. So Orangutan should
   either be installed on the same machine as Redmine or MySQL should listen
   to the network.

 o Orangutan supports two modes - same logins (e.g. LDAP) and different logins.
   These modes are controlled by 'redmine.same_login' configuration option. If
   it is equal to 1 you should use LDAP or configure Jabber server to use the
   'user' table of the Redmine installation (mail me if you succeeded to do
   this). If it is equal to 0 the special field 'Jabber ID' will be used to
   "link" logins.

 o To access Google Talk account you need to specify jabber.component
   configuration option. It needs to be set to the domain part of your username
   (e.g. 'gmail.com').

INSTALLATION
============

  1. Create a Jabber account for Orangutan.

  2. Create new system user for Orangutan (or use e.g. 'nobody').

  3. Copy 'sample.conf' to /etc and rename it to 'orangutan.conf'. Ensure that
     it is readable by 'nobody' user.

  4. Modify /etc/orangutan.conf.

      * Put your Jabber ID into 'admin' section (as 'creator' and as 'manager').
        The 'creator' is admin and the 'manager' can be JID of your manager.

      * Put Orangutan's Jabber account data into 'jabber' section.

      * Configure 'db' section - use the same credentials as you do for your
        Redmine installation.

      * Change 'redmine.base_url' to the base URL of your Redmine installation.

  5. Copy 'orangutan' file to /usr/bin directory.

  6. Create directory /usr/share/orangutan and two subdirectories - 'contexts'
     and 'monkeys'. Ensure that both are readable by user 'nobody'.

  7. Copy the content of 'Contexts' directory to /usr/share/orangutan/contexts.
     All these files should be readable by user 'nobody'.

      * Change 'contexts.directory' in /etc/orangutan.conf to
        /usr/share/orangutan/contexts.

  8. Copy the content of 'Monkeys' directory to /usr/share/orangutan/monkeys.
     All these files should be readable by user 'nobody'.

      * Change 'monkeys.directory' in /etc/orangutan.conf to
        /usr/share/orangutan/monkeys.

  9. Create directory /var/lib/orangutan and three subdirectories - 'data',
     'logs' and 'users'. All these directories must be writable by user
     'nobody'.

      * Change 'users.data' to /var/lib/orangutan/data.

      * Change 'users.directory' to /var/lib/orangutan/users.

      * Change 'logs.directory' to /var/lib/orangutan/logs.

     NOTE: you can create 'logs' directory somewhere in /var/log but remember
           that these logs will contain users' personal data).

 10. Create 'Orangutan' directory in /usr/lib/perl5.

 11. Copy the content of 'Orangutan' directory to /usr/lib/perl5/Orangutan. User
     'nobody' should be able to access these files.

 12. Copy 'Changelog' file to /usr/share/doc/orangutan and ensure that it is
     readable by user 'nobody'.

      * Put full path to 'Changelog' file into your orangutan.conf in
       'orangutan.changelog'.

 13. Install Redmine plugin ('Redmine' directory).

      * Copy 'Redmine' directory to #{RAILS_ROOT}/vendor/plugins and rename it
        to 'orangutan'.

      * Run: rake db:migrate:plugins RAILS_ENV=production

      * Create a Jabber account for Redmine.

      * Copy redmonkey.yml into #{RAILS_ROOT}/config directory and change it
        (put new Jabber account credentials there and set 'orangutan' to JID of
        Orangutan (which was specified in /etc/orangutan.conf)).

      * Restart Redmine (usually it means restarting Apache).

     See: http://www.redmine.org/projects/redmine/wiki/plugins

 14. Copy Tools/orangutan file to /etc/init.d directory.

     NOTE: You need to modify this file if you are using different locations for
           /usr/bin/orangutan, /etc/orangutan.conf and/or using different user
           id, group id.

 15. Create 'orangutan' directory in /var/run. Ensure that this directory is
     writable by user 'nobody'.

 16. Add Orangutan to be started on boot up (under root):

     # update-rc.d orangutan defaults 95

 17. Start orangutan:

     # /etc/init.d/orangutan start

NOTE: You can use different locations for files but these ones are recommended.

USING
=====

To start using Orangutan just add him to your contact list (roster).

TROUBLESHOOTING
===============

 1. How to get logs on STDOUT?

    Run: orangutan -D

 2. Running in debugging mode

    To solve issues with accessing Jabber server it can be useful to set
    jabber.debug to 1.

 3. Orangutan reports: authorization failed: error ...

    REASON:
    There is a bug in Debian's Authen::SASL::Cyrus (see #427162).

    SOLUTION:
    Remove (if possible) libauthen-sasl-cyrus-perl and install (if not installed)
    libdigest-hmac-perl.

BUG REPORTING
=============

Currently the only way to report a bug for Orangutan is to mail me:
Andriy Lesyuk <s-andy@andriylesyuk.com>