Install the Backlogs plugin for Redmine on Hostgator

Backlogs is one of the best plugins for Redmine. It allows you to work in an agile way by creating stories, tasks and displaying beautiful charts showing the project's progress.

Installing Backlogs is quite easy. It gets a little bit complicated when you try to install it in the restrictive environment of a shared hosting provider like Hostgator. But it can be done.

Enable SSH access, install Redmine

Before we start, you need to enable SSH access for your Hostgator account. If you don't know how to do it, follow the instructions from my previous post:
Enable SSH access on a Hostgator shared hosting account

Of course you need an installation of Redmine. If you need help installing Redmine on Hostgator, check out this post:
Install Redmine on Hostgator shared hosting

Configure a local gem repository

Backlogs requires a few gems to run properly. But on a shared hosting account you can't install gems in the standard gem repository location. The solution is to specify a non-standard gem repository location via the GEM_HOME environment variable.

You can do that by editing the .bash_profile

vim  ~/.bash_profile

And adding the following line:

export GEM_HOME=$HOME/ruby/gems

Right now Redmine knows only about the global gem repository. To inform it about your local repository, edit the configuration file ~/apps/redmine/config/environment.rb and add the following lines:

$:.push("/home/your-account/ruby/gems")
ENV['GEM_PATH'] = '/home/your_account/ruby/gems:/usr/lib/ruby/gems/1.8'

Install Backlogs gem dependencies

Some of the gems are already available in the global repository on the Hostgator servers and you don't need to install them:

• rubygems
• rails
• rack

The rest of the gems can be installed in the local repository by running the following command:

gem install i18n icalendar prawn open-uri-cached system_timer

Another gem you need is holidays. But installer of the latest version (1.0.4) has a known problem. The workaround is to first install an older version and then update to the latest one:

gem install holidays --version 1.0.3
gem install holidays

You also need to install the nokogiri gem. But it needs to compile some native extensions and this can't be achieved on the Hostgator server.

Compile nokogiri gem

The solution is to compile the gem and its native extensions on a different machine where you have access to a compiler. Then pack the gem together with the native extensions and install it in the local gem repository on the Hostgator server.

Before getting to the compilation part, make sure you have installed both libxml2 and libxslt libraries in the /opt/ folder of your build machine, just like on the Hostgator server.

In order to generate gems with pre-packed native extensions we need to install the gem-compiler gem that helps us compile other gems:

gem install gem-compiler

Next, download the nokogiri gem without installing it:

gem fetch nokogiri

This will download the gem file nokogiri-1.5.0.gem in the current folder.

Now you can simply compile the nokogiri package, specifying the custom locations for the libxml2 and libxslt libraries:

gem compile nokogiri-1.5.0.gem -- \
  --with-xml2-lib=/opt/xml2/lib/ \
  --with-xml2-include=/opt/xml2/include/libxml2/ \
  --with-xslt-lib=/opt/xslt/lib/ \
  --with-xslt-include=/opt/xslt/include/

This will create the gem file nokogiri-1.5.0-x86-linux.gem with precompiled native extensions. Upload the gem file to the Hotgator server and install it:

gem install nokogiri-1.5.0-x86-linux.gem

If you don't want to get through all the trouble of compiling the nokogiri gem yourself, just download the package I've attached to this post.

Install Backlogs plugin

You have to download the Backlogs source code in the vendor/plugins of your Redmine installation on the Hostgator server. I prefer to use git for this.

cd ~/apps/redmine/vendor/plugins/
git clone git://github.com/relaxdiego/redmine_backlogs.git

If you want to install git on a Hostgator shared hosting account check my previous post:
Install Git on Hostgator shared hosting

This will create a directory named redmine_backlogs. Next we have to take a look at the available versions and choose the latest one available.

cd redmine_backlogs
git tag
git checkout v0.8.1

Now ensure your Redmine instance is set-up correctly by running the following rake commands in the Redmine installation directory.

cd ~/apps/redmine/
rake generate_session_store
rake config/initializers/session_store.rb
rake db:migrate
rake db:migrate:upgrade_plugin_migrations

Next step is to configure Backlogs:

cd ~/apps/redmine/
rake redmine:backlogs:install

That's all, have fun!