Project Management, Collaboration and Time Tracking.
Ruby JavaScript PHP
Switch branches/tags
Nothing to show
Pull request Compare This branch is 4 commits ahead, 4879 commits behind ari:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


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://

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.

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 has been heavily tested, and some people are running postgresql.

Install the following packages:

  • ruby gems

  • ruby mysql driver (you could also choose postgresql)

  • rake

  • ImageMagick

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

FreeBSD with Ruby 1.9

Ruby 1.9 is much faster than 1.8.

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

FreeBSD with Ruby 1.8

Sometimes you just need to use 1.8 if you have other tools which rely on 1.8, such as portinstall.

portmaster converters/ruby-iconv devel/ruby18-gems databases/ruby-mysql devel/rubygem-rake graphics/ImageMagick


First install the Macports system from Then:

sudo port install rb-rubygems rb-mysql rb-rake ImageMagick libxml2 libxslt

Linux, etc

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

yum install libxml2 libxslt ImageMagick ruby

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

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>
  RailsEnv production
  PassengerHighPerformance on

  DocumentRoot /usr/local/www/jobsworth/public
  CustomLog /var/log/www/ combined
  ErrorLog /var/log/www/

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 Rails application.

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

Naturally adjust the paths to suit your own environment.

Step 4: Setup configuration and database

cd /usr/local/www/jobsworth
ruby setup.rb

Step 5: Ruby gems

There are a few Ruby gems which are needed for running CIT. Change directory into the top of your CIT installation, then type:

rake gems:install

That will install the gems you need.

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 mysql -- --with-mysql-include=/opt/local/include/mysql5 --with-mysql-lib=/opt/local/lib/mysql5 --with-mysql-config=/opt/local/lib/mysql5/bin/mysql_config

Upgrading to a newer revision

git checkout db/schema.rb
git pull

Check that there aren't any updated gems or new gems to install. If there are, just follow the instructions you will be given on screen.

rake gems

Next, make sure the database is updated:

rake db:migrate RAILS_ENV=production

Depending on which environment you are updating, you can change the RAIL_ENV value to “test” or “development” and the appropriate database will be updated.

Restart the web server just to ensure anything cached is cleared

apachectl graceful

Clear out cached asset files

rm public/javascripts/main.js
rm public/javascripts/popup.js
rm public/javascripts/prototype-all.js
rm public/stylesheets/all.css
rm public/stylesheets/popup.css

Setting up Email Integration

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

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 '' 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 * to a special script. That '*' means a wildcard: that is, any username at that hostname will be forwarded.


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

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

jobsworth: "|/path/to/cit/script/runner -e production 'Mailman.receive('"

Add an entry to /etc/mail/virtusertable to redirect all emails to your domain to the above alias        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.



# Make sure Ruby is on the path
export PATH=/usr/local/bin:/usr/local/sbin:$PATH

# Strip the first 6 lines which are specific to Communigate
/usr/bin/tail -n +7 $2 | ${RUBY} -W0 /usr/squish/script/runner -e production 'Mailman.receive(' > /dev/null

exit 0;