Installation

Alrighty! Let’s install Backlogs into your system. Now, remember, if you come across any hitches or just don’t know how to proceed,
don’t hesitate to ask for help.

NOTE: These instructions always apply to current master on github until we have a decent baseline. Current backlogs requires ruby 1.9.3.

Select your target platform: generic, RHEL 5.x, Dreamhost, Bitnami Redmine stack

Install Redmine

RHEL 5.x (for x >= 3) is not a particularly friendly environment for
rails, but it can be done. Here’s what worked for me.

Ruby

RHEL comes with a pretty ancient version of Ruby, so you’ll need to
upgrade. Feel free to compile Ruby by hand, but a kind soul has
provided RPMS. Create a file named `/etc/yum.repos.d/ruby.repo` with
the following content:

[ruby]
name=ruby
baseurl=http://repo.premiumhelp.eu/ruby/
gpgcheck=0
enabled=0

and execute the following commands:

yum -y --enablerepo=ruby install ruby rubygems ruby-mysql ruby-devel
yum -y install git patch curl
yum -y install httpd

Redmine and Backlogs

I couldn’t get Rails to work without hard-coding the environment, so
after the installation, do.

sed -i 's/^# ENV/ENV/g' /var/www/redmine/config/environment.rb

Apache

For production you will not want to use Webrick. Here’s how to get
Redmine running on Apache using mod_rails.

Create a file named `/etc/httpd/conf.d/mod_rails.conf` and add the
following to it

LoadModule passenger_module
/usr/lib/ruby/gems/1.8/gems/passenger-2.2.11/ext/apache2/mod_passenger.so
PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-2.2.11
PassengerRuby /usr/bin/ruby

Create a virtualhost for your redmine instance by creating
`/etc/httpd/conf.d/redmine.conf`

NameVirtualHost *
<VirtualHost>
ServerAdmin You@example.com
DocumentRoot /var/www/redmine/public/
<Directory "/var/www/redmine/public/">
AllowOverride all
Options -MultiViews
</Directory>
</VirtualHost>

You may need to fiddle with file permissions to allow `apache` to read
all the required files. What worked in the end was

chown -R apache:apache /var/www

but I’m fairly sure this could be done more fine-grained.

I have not been able to locate a packaged version of mod_rails, so
we’ll have to build it

yum -y install make gcc-c++ httpd-devel
gem install passenger
passenger-install-apache2-module
chmod -R a+rwX /usr/lib/ruby/gems/1.8/

The `passenger-install-apache2-module` command will ask you a number of questions about your
environment and will compile and install mod_rails for you. The chmod
was necesary because the mod_rails installation reverted some file
permissions which prevented apache from reading the ruby files.

Don’t forget to restart apache.

The Backlogs plugin is supported on Redmine 2.2.4 and 2.3.2
. Other versions are known to work but are not supported. For more information on Redmine and how to install it, please visit the official Redmine website or the official ChiliProject website .

Check Those Gems!

You need bundler and an up-to-date version of rubygems for rails 2.3.14, so:

gem install rubygems-update -d --no-rdoc --no-ri
update_rubygems
gem update --system
gem install bundler

Before installing the required gems, make sure they’re getting installed in the Bitnami environment, not your system ruby environment:

export GEM_HOME=<path to bitnami stack>/redmine-<version>/ruby/lib/ruby/gems/1.8/gems 
export PATH=<path to bitnami stack>/redmine-<version>/ruby/bin:$PATH

In your home directory

Create directory `.gem/` (if not present)

mkdir ~/.gem

Add the following to `~/.bash_profile`

export GEM_HOME="$RUN/.gem"
export GEM_PATH="$GEM_HOME:/usr/lib/ruby/gems/1.8"
export PATH="$RUN/.gem/bin:$PATH"
export RUBYLIB="$RUN/lib:$RUBYLIB"

Create file `~/.gemrc` with this content (there must be an empty line at the end):

gemhome: /home/YOURUSERNAME/.gem
gempath:
* /home/YOURUSERNAME/.gem
* /usr/lib/ruby/gems/1.8

REMEMBER: Make sure the file above has an empty line at the end

In the Redmine directory

Add to `config/environment.rb`

ENV['GEM_PATH'] = '/home/YOURUSERNAME/.gem:/usr/lib/ruby/gems/1.8'

Backlogs requires a few gems to run properly. The included Gemfile lists all requirements, so bundler ought to install them all including their dependencies. Just re-run the bundler call you executed during redmine install, something to the effect of

bundle install --without development test

Some of these gems are not pure-ruby gems, so if no pre-compiled gems are available for your platforms, you will have to have a compiler available to the gems can be built during install. Some guides to accomplish this are available for windows and Ubuntu/Mac OS X, but (I’m sorry) you’re on your own to get this resolved. It’s not my expertise. I run Ubuntu using RVM, that’s what I know.

There is currently a known problem with the installer for the holidays gem (1.0.4). You can work around the problem by first installing an older version and then upgrading:

gem install holidays --version 1.0.3
gem install holidays

Install Backlogs

Now let’s download the Backlogs source code from the official repo into the `plugins` directory of your Redmine installation. The code is hosted in Github and you have two ways get it. The first method is what we recommend since it allows you to update to the latest version easily and even try out experimental features. Unfortunately, it requires that you have git installed. If you don’t feel like messing around with git right now, go ahead and skip to the second method.

Method #1

NOTE: This first method requires some knowledge of git. For more information on how to use it, please visit the git homepage.

First, make sure that you’re inside the `plugins` directory of your Redmine instance. Now, clone the source from Github by executing the following command:

git clone git://github.com/backlogs/redmine_backlogs.git

This will create a directory named `redmine_backlogs` which is exactly what we need.

IMPORTANT: Don’t rename the `redmine_backlogs` directory!

Now you need to select the version you want to use. First, go inside the `redmine_backlogs` directory by executing the following:

cd redmine_backlogs

Then, take a look at the available versions that have been tagged in the repo:

git tag

This will display the versions in alphabetical order. Choose the latest version (recommended), or whichever you prefer by running the following command:

git checkout vX.Y.Z

NOTE: Replace ‘X.Y.Z’ with the version of your choice.

That’s it for Method #1. If you want to try out some of the experimental features, feel free to poke around by checking out the master branch or any other available branches. See the section titled Optional: Getting the latest code below for information on how to do that.

Method #2

This second method involves going to the project’s page in Github and downloading the source archive. To download the archive, click the Download button found near the top right corner:

This will display a page where you can download the available versions tagged in the repo. Download the version of your choice by clicking either the tgz or zip link. For Windows users, it’s usually zip. After this, go ahead and extract the contents of the downloaded archive into the `plugins` directory of your Redmine instance. Also, make sure that the extracted directory is named exactly as `redmine_backlogs`.

Pre-install Tasks

IMPORTANT: Before you continue, keep in mind that most rake tasks run on the development environment when you don’t specify a value for RAILS_ENV. If you want to ensure that the rake tasks run on the production environment, run the following in the terminal:

RAILS_ENV=production
export RAILS_ENV

Up next, we need to ensure that your Redmine instance is set-up correctly. So make sure to execute the following rake commands from the command line while in your Redmine installation’s top directory:

bundle exec rake db:migrate

For more information on the above rake tasks, execute `rake -T` from within your Redmine installation. You may also want to run the following rake tasks.

WARNING: Be careful when running the following rake tasks in a production environment as it might produce unwanted results.

bundle exec rake tmp:cache:clear
bundle exec rake tmp:sessions:clear

Configure Backlogs

Now that Backlogs has been downloaded, let’s go ahead and tell it how to behave. To do that, go to your terminal again and do the following:

cd path/to/redmine
bundle exec rake redmine:backlogs:install

This will download some needed files, help you set up your story and
task trackers, run the plugin’s database migrations, and, if you’re
nice enough, maybe even make breakfast for you!

If you don’t want the installer to bother you with questions, you can
pass it parameters to automate (parts of) the install process by
calling it with

bundle exec rake redmine:backlogs:install parameter=value parameter=value ...

Parameter	Value	Effect
story_trackers	comma-separated list of trackers names	Overwrites the current setting for story trackers
task_tracker	tracker name	Overwrites the current setting for task tracker
corruptiontest	‘true’ or ‘false’	May be used to disable the (time-consuming) Redmine database corruption test. It’s not required, but if you disable this you cannot complain that the migration fails
labels	‘true’ or ‘false’	May be used to disable the label download

About story and task trackers: These settings tell Backlogs what type of issues it should consider as stories and tasks respectively. You may select more than one story tracker but only one task tracker. Some of us like to use Bug, Feature, and Support as story trackers and Task as the task tracker. Others prefer to make it simple by creating a Story tracker and a Task tracker. It’s really up to you.

Give it a spin!

At this point you can go to the Redmine/Chiliproject installation directory and run ‘thin start’. Redmine/Chiliproject ought to start, and backlogs ought to be functional. You might want to set up Redmine/ChiliProject to run behind Apache or nginx; the configuration of these is beyond the scope of setting up backlogs itself.

Additional Configuration

This step is not required at this point, but it helps to know there is this page for redoing the configuration. Access your Redmine instance using your preferred browser, log in as an administrator and head on to Administration > Plugins. Then click the Configure link to the right of the Redmine Backlogs Plugin record. You should then see a screen similar to the one below:

NOTE: Redmine ships with just the Feature, Bug, and Support tracker. To add custom trackers such as Task and Impediment in the above screen, go to Administration > Trackers in Redmine.

NOTE: Currently child-issues of stories are forced to become tasks. It is planned to lift this limitation.

A quick description of the fields:

Story Trackers and Task Tracker – These fields tell Backlogs what type of issues it should consider as stories and tasks respectively. You may select more than one story tracker but only one task tracker. Make sure that you don’t use the same tracker in both fields! If you do this, the Apply button will automatically be disabled.
Points burn up/down – Tells Backlogs how to display the sprint progress chart. Some of us like it to go up, others like it to go down. Choose which one you prefer.
Label types for card printing – If you like physical task boards (and you do, right?), you can select one of 250 preconfigured label types that are commercially available. Your product/sprint backlog will print neatly onto these.
Template for sprint wiki page – Backlogs helps you keep your sprint retrospectives or review notes on a wiki. If you want to have some template text on this page you can fill in the page that will be used as a template, which will be copied onto the sprint wiki page if that page does not already exist. The template page will be searched up the project chain, so you can define the template page on the project itself or any of its parents. You can also prefix the template name with a project ID followed by a ‘:’; if no template is found in the project chain, the template will be picked up from that project (if it exists, or course).

Once you’re done, go ahead and click Apply. If that button is disabled, it means you’re using a task tracker that’s also a story tracker. Fix the error so you can proceed.

Set Permissions

Now let’s tell Redmine which project roles have permission to use the plugin. To do that, go to Administration > Roles and permissions > Permissions report. This should lead you to a page that looks like something below:

Check or uncheck any of the permissions under the Backlogs section for any of the roles in your system.

Enable Backlogs in Your Projects

Now that Redmine and Backlogs are properly configured, all that’s left is to enable the plugin in each of the projects you want to use it in. To do that, login to your Redmine instance, choose a project then click on its Settings tab. Once in the settings page, click the Modules tab and then check Backlogs.

Afterwards, click Save and you should see the Backlogs tab appear in your project’s menu. Do the same thing for each project in which you want to use Backlogs.

Creating non-accepted closed states for stories/tasks

By default, Backlogs will treat any story or task that is in a “closed” state as completed succesfully. You may want the option to close stories or tasks so they don’t clutter your administration but without marking them as succesful. To do this, go to “Administration” → “Settings” → “Issue Tracking” and set “Calculate the issue done ratio with:” to “Use the issue status”.

Now go to “Administration” → “Issue statuses”, and edit the states you want to mark as non-succesful by setting them to closed and their done-ratio to any number except 100. Statuses that are closed and have no percentage or 100 count as sucessful.

Now you can go back and change the “Calculate the issue done ratio with:” back to “Use the issue field” if you wish.

Optional: Getting the latest code

If you want to grab the latest & greatest from the repo, here’s what you do:

cd path/to/backlogs
git checkout master
git pull origin
bundle exec rake redmine:backlogs:install

NOTE: Obviously, you can only do this if you used Method #1 in the installation process above.

WARNING: The master is constantly in flux and might be broken at times. Make sure to do the above in your test or staging environment first before pulling the code into production! We try to make sure new versions don’t break existing data, but we don’t have enough resources to test all possible scenarios.

ANOTHER WARNING: If you decide to checkout any of the topic branches (topic branches are prefixed by the dev’s name. example: backlogs-super-crazy-idea), keep in mind that these are very early stage work and may break the build at times. Topic branches are unsupported and we don’t recommend you pull from them unless you know what you’re doing.

Optional: Upgrading with git

We release new versions of the product often. To grab the latest version in the repo, here’s what you do:

cd path/to/backlogs
git fetch --tags origin
git tag

The last line above will show you a list of available versions. To upgrade to one of the versions, do the following:

git checkout vX.Y.Z
bundle exec rake redmine:backlogs:install

NOTE: Replace vX.Y.Z with the correct tag.

WARNING: Make sure to do the above in your test or staging environment first before pulling the code into production! We try to make sure new versions don’t break existing data, but we don’t have enough resources to test all possible scenarios.