== Installing jobsworth on your server === Step 1: Getting the source.

The easiest way to get the source and easily update it from time to time is with git. You'll need to install that on your machine and then run:

git clone git://github.com/ari/clockingit.git

You will want to put the source somewhere sensible depending on your operating system. On OSX that might be ~/Sites/jobsworth and on FreeBSD /usr/local/www/jobsworth. We'll use the FreeBSD path in these instructions.

Now pick a branch. You can follow "dev" if you are working on the development of jobsworth. This branch will be frequently unstable and you should know quite a bit about Rails and jobsworth before you follow this one.

git checkout dev

Or follow "master" if you want the stable branch.

git checkout master

Or you may wish to just stick with a particular release which will remain static, such as

git checkout v1.2

=== Step 2: Prerequsites

You need to be running some type of Unix: OSX, Linux, Solaris, BSD. Windows will probably not work. You will also need a database. MySQL is recommended. Postgresql may work.

Install the following packages:

• ruby 1.9.2 or ruby 1.8.x
• zip
• ImageMagick

How to install these will differ on each platform. Some possibilities:

==== FreeBSD with Ruby 1.9

echo "RUBY_DEFAULT_VER=1.9" >> /etc/make.conf portmaster converters/ruby-iconv archivers/zip graphics/ImageMagick

==== OSX

First install the Macports system from http://www.macports.org. Then:

sudo port install ruby19 ImageMagick

==== Linux, etc

Under other operating systems use your favourite package manager to ensure you have Ruby, rubygems, Rake and the Ruby mysql driver installed. Something like:

yum install ruby19 ImageMagick zip

=== Step 3: Phusion Passenger

Install Phusion Passenger. You can instead use Mongrel, but it tends to be a little easier to set up with Phusion.

gem install passenger passenger-install-apache2-module

And follow the instructions you'll be given about how to install the relevant config for Apache httpd.

Your Apache httpd virtual host DocumentRoot should point to the public directory in the installation directory.

<VirtualHost *:80> ServerName jobsworth.example.com.au RailsEnv production PassengerHighPerformance on

DocumentRoot /usr/local/www/jobsworth/public
CustomLog /var/log/www/myserver.example.com.au-access_log combined
ErrorLog /var/log/www/myserver.example.com.au-access_log

You'll need to allow access to the folder you specify if isn't already inside your global httpd DocumentRoot. And MultiViews is bad for a Rails application.

<Directory /usr/local/www/jobsworth/public> AllowOverride All Options -MultiViews Order allow,deny Allow from all </Directory>

Naturally adjust the paths to suit your own environment.

=== Step 5: Ruby gems

First we need the Rails gem installation tool.

gem install bundler

Then in order to install all the gems we need.

cd /usr/local/www/jobsworth bundle install

If you have trouble on OSX with the mysql gem (this seems to be an issue on 10.5), then try this sudo env ARCHFLAGS="-arch i386" gem install mysql2 -- --with-mysql-include=/opt/local/include/mysql5 --with-mysql-lib=/opt/local/lib/mysql5 --with-mysql-config=/opt/local/lib/mysql5/bin/mysql_config

=== Step 4: Setup configuration and database

ruby setup.rb

=== Step 5: Set up email sending

Jobsworth sends email in a background process. In order to get that process running a script needs to run. Now just in case the script dies for some reason, it makes sense to add it to cron to ensure it is always running. Add a line like this to /etc/crontab

15 * * * * root cd /usr/local/www/jobsworth; /usr/local/bin/ruby19 script/delayed_job start

=== Step 6: Set up email receiving

When jobsworth sends outgoing emails for task updates, they will have a reply address which looks like this:

[email protected]

If a user hits reply to that email, you want it to go back and be appended to the task comments. It isn't hard, but you'll need a mail server you have some control over in order to get the magic to work. Firstly, let's look at that email address. To the left of the @ we have a designator showing which task this email is relevant to. On the right 'acme' represents the name of the company you set up when you ran the setup.rb script and first installed jobsworth. And the final 'domain.com.au' part is defined in the environment.local.rb file in your config folder.

You need to set up your email software to pass all incoming emails for @acme.domain.com.au to a special script. That '' means a wildcard: that is, any username at that hostname will be forwarded.

=== Sendmail

For example to configure sendmail, add an entry to /etc/mail/local-host-names for your hostname:

acme.domain.com.au

Add an entry to /etc/mail/aliases to create an alias that will hand off emails to the mailman script

jobsworth: "|/usr/local/www/jobsworth/script/rails runner -e production 'Mailman.receive(STDIN.read)'"

Add an entry to /etc/mail/virtusertable to redirect all emails to your domain to the above alias

@domain.com jobsworth

run "make; make restart" in /etc/mail

=== Communigate Pro

Communigate Pro puts it own headers on the top of each email which need to be stripped. A little script like this is dropped into /var/Communigate/Scripts and then added to the 'helpers' configuration with in the GUI. You'll need a rule inside Communigate to pass all email to the appropriate hostname to this script.

#!/bin/sh

RUBY=/usr/local/bin/ruby MAILSCRIPT="/usr/local/www/jobsworth/script/rails runner"

Strip the first 6 lines which are specific to Communigate

/usr/bin/tail -n +7 $2 | ${RUBY} -W0 ${MAILSCRIPT} -e production 'Mailman.receive(STDIN.read)' > /dev/null

exit 0;

== Upgrading to a newer revision

rake update:git