27 Jun

Redmine is a free and open source, web-based project management and bug-tracking tool. It includes a calendar and Gantt charts to aid visual representation of projects and their deadlines. It handles multiple projects. Redmine provides integrated project management features, issue tracking, and for multiple version control options.
The design of Redmine is significantly influenced by Trac, a software package with some similar features.
Redmine is written using the Ruby on Rails framework. It is cross-platform and cross-database. [...]

Source: http://en.wikipedia.org/wiki/Redmine

This post is not intended to replace the detailed installation instructions available at redmine.org; it’s just a simple, easy-accessible step-by-step guide for installing Redmine on a specific platform.

Our setup

  • Machine: 64 bit Ubuntu 11.04 with 1GB of memory
  • Redmine stable version 2.0.3
  • MySQL version 5.1

Redmine download

We need wget to download our files:
sudo apt-get install wget

We will download Redmine from RubyForge. Run the following command in your favorite directory:
wget http://rubyforge.org/frs/download.php/76259/redmine-2.0.3.tar.gz
Then extract the downloaded archive using:
tar xzf redmine-2.0.3.tar.gz
This will create a local directory called redmine-2.0.3 with the following structure:
.gitignore
.hgignore
Gemfile
README.rdoc
Rakefile
app/
config/
config.ru
db/
doc/
extra/
files/
lib/
log/
plugins/
public/
script/
test/
tmp/
vendor/

Dependencies installation

Now that we have the Redmine source code, we can start installing the required dependencies.

First off are Ruby libraries, rake and gem plugins:
sudo apt-get install ruby ruby1.9.1-dev ruby1.8-dev libgemplugin-ruby libgemplugin-ruby1.8 libruby-extras libruby1.8-extras rake
To optionally support Gantt charts inside Redmine we need to install librmagick-ruby1.8:
sudo apt-get install librmagick-ruby1.8
We need version 1.8.5 of Ruby Gems. To verify the installed version run:
gem -v
If Gems is not installed or if the version is less that 1.8.5 run the following commands, again in your favorite directory:
wget http://production.cf.rubygems.org/rubygems/rubygems-1.8.5.tgz
tar xzf rubygems-1.8.5.tgz

This will create a local directory called rubygems-1.8.5. Backup the currently installed version of Gems then install version 1.8.5 by running:
sudo mv /usr/bin/gem /usr/bin/gem-old
cd rubygems-1.8.5
sudo ruby setup.rb

This will install gem1.8 in /usr/bin. Create a symbolic link named gem:
sudo ln -s /usr/bin/gem1.8 /usr/bin/gem
Then make sure that the version of Gems is now 1.8.5 by running
gem -v
Now we need to install Ruby On Rails (RoR) and the required gems for Redmine to connect to our MySQL database:
sudo gem install rails -v=2.3.14
sudo gem install mysql
sudo gem install rubytree -v=0.5.2

We will need to install Bundler to manage Gems dependencies:
gem install bundler

We will use Apache 2 as a web server. To install it with additional required libraries run:
sudo apt-get install apache2 apache2-mpm-prefork apache2-prefork-dev libapache-dbi-perl libapache2-mod-perl2

We will need the Curl development headers with SSL support. We can get them by running:
sudo apt-get install libcurl4-openssl-dev

Database configuration

As mentioned we will use MySQL for our database.
To install mysql run the command:
sudo apt-get install mysql-server mysql-client
During installation you will be prompted to enter a password for the root user.
We need to create a database and a corresponding user for Redmine.
mysql -u root -p
CREATE DATABASE redmine CHARACTER SET utf8;
CREATE USER 'redmine' IDENTIFIED BY 'password';
GRANT ALL privileges ON redmine.* TO 'redmine';

To configure the Redmine database settings, we need to modify the configuration file database.yml located in the config directory.
Redmine provides a template configuration file named database.yml.example. You can create a copy of it to start with:
cp database.yml.example database.yml
Redmine can run in different profiles, we will be using the production profile, so we will modify this section of database.yml:
production:
adapter: mysql
database: redmine
host: localhost
username: redmine
password: my_very_secure_password
encoding: utf8

Redmine web folder configuration

We need to set appropriate permissions on on the different Redmine folders so that access through Apache works correctly.
We also need to create a folder in public where Redmine plugins will save their assets.
mkdir public/plugin_assets
sudo chown -R www-data:www-data files/ log/ tmp/ public/plugin_assets
sudo chmod -R 755 files/ log/ tmp/
sudo chmod -R 777 public/plugin_assets

Using Bundler, we need to install all the gems required by Redmine. In the root Redmine directory, run the following:
bundle install --without development test postgresql sqlite rmagick

Now we can initialize Redmine and generate the database. Run the following command at the root directory of the Redmine source code:
sudo rake generate_secret_token
sudo RAILS_ENV=production rake db:migrate
sudo RAILS_ENV=production rake redmine:load_default_data

The last command will prompt you to choose the language for the default data to load.

At this point, we can test the Redmine installation by running it over a WEBrick server:
ruby script/rails server webrick -e production
Once the WEBrick server starts, you can access your Redmine instance by going to the URL:
http://YOUR_SERVER_IP_ADDRESS:3000

WEBrick is not suitable for normal use, it is only intended to test the installation and make sure everything is functioning correctly.

Apache configuration

We will make the Redmine ruby application accessible through Apache bu using the Apache module Passenger.

We need first to install passenger:
sudo gem install passenger
Then we need to install the Apache2 module by running:
sudo passenger-install-apache2-module
This step will guide through the installation and will advise on how to install missing dependencies, if any.

We need to create the files passenger.load and passenger.conf in /etc/apache2/mods-available/ with the following content:
passenger.load
LoadModule passenger_module /usr/lib/ruby/gems/1.8/gems/passenger-3.0.11/ext/apache2/mod_passenger.so
passenger.conf
PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-3.0.11
PassengerRuby /usr/bin/ruby1.8

Then we need to activate the installed Apache2 module and restart Apache2:
sudo a2enmod passenger
sudo /etc/init.d/apache2 restart

At this point we need to configure an Apache2 virtual host for our Redmine instance.
Since we didn’t originally put the Redmine source code in Apache’s /var/www web directory, we can create an alias in that directory to point to Redmine’s public directory and change the owner to www-data:
sudo ln -s /root/redmine-2.0.3/public /var/www/redmine
sudo chown www-data:www-data /var/www/redmine

To configure the virtual host, create the file /etc/apache2/sites-available/help-counter.com. A good file naming convention would contain the Redmine’s instance FQDN.
<VirtualHost help-counter.com:80>
ServerName help-counter.com
ServerAdmin username@yoursite.tld
DocumentRoot /var/www/redmine/public
PassengerDefaultUser www-data
RailsEnv production
RailsBaseURI /redmine
SetEnv X_DEBIAN_SITEID "default"
<Directory /var/www/redmine/public/>
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Then we need to enable to site and restart apache:
sudo a2ensite help-counter.com
sudo service apache2 restart

Please note that you will need to add execute permissions to the directory where redmine-2.0.3 is located in order for the configuration to work. Otherwise, you will get in your Apache2 error.log the following message: Symbolic link not allowed or link target not accessible.
An alternative would be to move the whole redmine-2.0.3 directory to /var/www

And voilà!! You got a Redmine instance running in under 30 mins.

Additional Redmine configutions

Email / SMTP server configuration

Redmine uses a configuration file named configuration.yml inside the config directory.
A template file is already provided, so we can copy it and customize it:
cp configuration.yml.example configuration.yml
The following configuration uses a local Postfix server with no authentication.
default:
# Outgoing emails configuration (see examples above)
email_delivery:
delivery_method: :smtp
smtp_settings:
enable_starttls_auto: false
address: 'localhost'
port: '25'
domain: 'help-counter.com'
authentication: :none

NB: this article was originally posted on http://techwatch.keeward.com/.