Installation tutorial¶

• Installation tutorial
  • Requirements
  • Notes
  • Installation
  • Using
  • Troubleshooting

Requirements¶

• Redmine with MySQL.
  Orangutan was tested on Redmine 1.0.x and 1.1.x.
• Jabber/XMPP server (can be used with Google Talk).
• Perl
  Any version should work.
• Perl Net::XMPP library
  Orangutan was tested with Net::XMPP 1.02.
  For Debian-like distros: apt-get install libnet-xmpp-perl
• Perl XML::Writer and XML::Parser libraries
  For Debian-like distros: apt-get install libxml-writer-perl libxml-parser-perl
• Perl DBI library with MySQL driver
  For Debian-like distros: apt-get install libdbi-perl libdbd-mysql-perl
• 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¶

• 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.
• 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 (please share the tutorial if you succeeded to do this). If it is equal to 0 the special field “Jabber ID” will be used to “link” logins.
• 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 better use 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.
    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).
    See: http://www.redmine.org/projects/redmine/wiki/plugins
    • 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).
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.