Software Development

Redmine Installation & Getting Started Guide

Redmine is a free and open source, flexible web-based project management and bug-tracking tool, written using the Ruby on Rails framework.

Redmine supports multiple projects, with its own wiki, forum, time tracker and issues management.

Moreover Redmine implements a plugin platform so can be customized depending on your requirements. Exists plugins to work with Kanban, Scrum, notification plugins or reports.

What I really like about Redmine is that although does not fix the way you must work, it contains enough options to work in any kind of project management approach.

Redmine can be installed in different ways:

  • Using webrick (not recommended in production environments).
  • Run with mongrel and fastcgi.
  • Using Passenger.
  • Or package Redmine into war and deploy into Java container like Tomcat or Glassfish.

In this post I am going to show you how to package Redmine 1.3 into a war file so could be executed into Tomcat7 and Linux. In theory should be work with Glassfish, JBoss, or any other OS.

First of all download JRuby 1.6.6, so open a terminal

wget http://jruby.org.s3.amazonaws.com/downloads/1.6.6/jruby-bin-1.6.6.tar.gz

And decompress downloaded file and move to /usr/share directory.

tar xvzf jruby-bin-1.6.6.tar.gz
sudo mv jruby-1.6.6/ /usr/share/jruby-1.6.6

Then update environment variables with JRuby installation directory.

sudo gedit /etc/environment

PATH= … :/usr/share/jruby-1.6.6/bin
JRUBY_HOME="/usr/share/jruby-1.6.6"

Finally try to execute jruby to see that has been installed correctly:

jruby -v

And JRuby version information should be printed on console.

Next step is to install required gems:

gem install rack -v=1.1.1
gem install rails -v=2.3.14
gem install rdoc -v=2.4.2
gem install activerecord-jdbcmysql-adapter -v=1.2.2
gem install warbler -v=1.3.2
gem install jruby-openssl -v=0.7.5
gem install rubytree -v=0.8.2
gem install i18n -v=0.4.2
gem install tree -v=0.2.1

Redmine installation

Download Redmine 1.3 and install them on /usr/share directory:

wget http://rubyforge.org/frs/download.php/75597/redmine-1.3.0.tar.gz

tar xvzf redmine-1.3.0.tar.gz
sudo mv redmine-1.3.0 /usr/share/redmine-1.3.0

Redmine requires a database to work. In this case I had already installed mySQL5, but postgeSQL is supported too. So let’s configure mySQL into Redmine.

cd /usr/share/redmine-1.3.0/config/

Installation comes with a database template configuration file, we are going to rename it and modify to suit our environment. Moreover Redmine contains different start up modes (production, development, test). In our case because we are configuring a production environment, only production section will be touched.

cp database.yml.example database.yml
sudo gedit database.yml
production:
  adapter: jdbcmysql
  database: redmine
  host: localhost
  username: redmine
  password: redmine
  encoding: utf8

After this modification, it is time to create Redmine user and database into mySQL.

mysql -u root -p

create database redmine character set utf8;
create user ‘redmine’@’localhost’ IDENTIFIED BY ‘redmine’;
grant all privileges on redmine.* to ‘redmine’@’localhost’;

Now it is time to initialize Redmine

cd /usr/share/redmine-1.3.0
rake generate_session_store

Next step is required because we are installing Redmine 1.3, in next versions of Redmine 1.4 and beyond will not be necessary. Open config/environment.rb and comment next like:

config.gem ‘rubytree’, :lib => ‘tree’

And then create database schema and fill them with default data with next scripts.

RAILS_ENV=production rake db:migrate
RAILS_ENV=production rake redmine:load_default_data

Now we are going to test that Redmine is correctly configured. For this purpose we are going to use webrick.

cd /usr/share/redmine-1.3.0
jruby script/server webrick -e production

and open a browser at http://localhost:3000 to start checking installation.

Redmine web page will be shown, you can login with username and password admin/admin

At this point we have Redmine correctly installed.

Configuring Email

An issue tracker should be able to send mail to affected users when a new issue is created or modified by change.

If your mail server requires tls security protocol you should install action_mailer_optional_tls plugin.

This plugin requires git, if you don’t have installed yet, type:

sudo apt-get install git

and then run next command on Redmine directory:

jruby script/plugin install git://github.com/collectiveidea/action_mailer_optional_tls.git

Let’s configure email delivery:

cd /usr/share/redmine-1.3.0/config/
cp configuration.yml.example configuration.yml
sudo gedit configuration.yml

Inside configuration file you will find common email settings. Depending on your email server these attributes can vary widely, so at this point I am going to show you a simple smtp server configuration using plain authentication at production environment. Go to last line of configuration.yml file and append next lines into production section.

production: # this line is already present in configuration.yml.
   email_delivery:
  delivery_method: :smtp
  smtp_settings:
    address: "example.com"
    port: 25
    authentication: :plain
    domain: 'example.com'
    user_name: 'myaccount'
    password: 'password'

All attributes are self-explanatory.

And before creating war file, let’s check that email is correctly configured. Again we use webrick.

cd /usr/share/redmine-1.3.0
jruby script/server webrick -e production

Then open browser at http://localhost:3000 and log in with admin account.

Adjust admin email by clicking on My Account link, and at Email section, set administrator email.

After that we are going to test email configuration, from main menu, go to Administration -> Settings -> Email Notifications, add emission email and click on test email. After a few time, a test message will be sent to administrator email account.

We have succeeded in Redmine installation, now it is time to package it to be deployed into Tomcat.

Packaging Redmine

Before starting, because of incompatibility with installed jruby-rack gem, we should run next commands to install 1.0.10 version of jruby-rack.

gem uninstall jruby-rack
gem install jruby-rack -v=1.0.10

Warble command requires a configuration file. This file is created using next command:

cd /usr/share/redmine-1.3.0
warble config

cd config/
sudo gedit warble.rb

Edit Warble::Config section and configure config.dirs, config.gems and config.webxml.rails.env sections as:

Warbler::Config.new do |config|
  config.dirs = %w(app config lib log vendor tmp extra files lang)
  config.gems += ["activerecord-jdbcmysql-adapter", "jruby-openssl", "i18n", "rack", "tree"]
  config.webxml.rails.env = ENV['RAILS_ENV'] || 'production'
end

And finally run:

warble

And Redmine war has been created and is ready to be deployed into Tomcat.

Although we have got a war file, I recommend not deleting Redmine installation directory because could be used in future to install new plugins, or modify any configuration. After a modification, calling warble command, a new war with that change would be created.

I wish you have found this useful.

Reference: Redmine Installation & Getting Started Guide from our JCG partner Alex Soto at the One Jar To Rule Them All blog.

Subscribe
Notify of
guest

This site uses Akismet to reduce spam. Learn how your comment data is processed.

0 Comments
Inline Feedbacks
View all comments
Back to top button