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.
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.
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
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
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)
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
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.
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:
Then, take a look at the available versions that have been tagged in the repo:
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.
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`.
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
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 ...
|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.
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.
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.
Back to top
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.