Redmine logoRedmine logo

Preface

What is Redmine? Redmine is a flexible project management web application. Written using the Ruby on Rails framework, it is cross-platform and cross-database. What does that really mean though? What it means is that it gives you a great tool to manage your coding projects, either if you’re working solo or working in groups of people doing work on the same project. What’s great about Redmine is all the nice little features it offers you, that make managing your projects so much easier, some of them being

  • Multiple projects support
  • Flexible role-based access control
  • Flexible issue tracking system
  • Feeds & email notifications
  • Per project wiki
  • Per project forums
  • SCM integration (SVN, CVS, Git, Mercurial, Bazaar and Darcs)
  • Issue creation via email

Having a tool that gives you all this makes it easy to follow what you’ve done on a project so far, what issues have been uncovered with the code so far, and what has been done to fix these problems. But not only that, but it also gives you a great tool to write online documentation for your projects and has user-driven forums for them at the same making the integration between you as a coder and the end users even tighter.

As an added bonus, as with any community as it grows the community starts helping itself, making you able to focus on what’s important and that’s improving your code. Its ties to most modern VCS systems, such as Git, Subversion and Bazaar also make you able to track code changes in real-time through the web, much like you do on GitHub and similar services.

Getting ready

As always when doing work like this on any server, you should make sure you have good backup sets of your production server in case anything goes wrong. I would also recommend to packages that I just can’t live without, and that’s etckeeper and debian-goodies. etckeeper is a nice tool that saves your /etc hierarchy in a coding repository (supports git, mercurial, darcs and bzr) so that you can track your configuration changes with ease, and debian-goodies is a toolset that amongst others checks your system and its running processes to see if any program/service is running with old libraries after a system upgrade using the command checkrestart. After you’ve made sure of the above, perform the following:

sudo aptitude update
sudo aptitude safe-upgrade
sudo checkrestart (if debian-goodies is installed)

If everything looks good and checkrestart reports back “Found 0 processes using old versions of upgraded files”, you can proceed. If checkrestart reports that some processes are running using old libraries, either restart the respective processes using their associated init script under /etc/init.d or send the -HUP signal using kill, or simply restart the box to start with a clean slate.

INSTALL GIT

First, we install the files needed for git itself.

sudo aptitude install git-core

INSTALL RUBY

Then we install the files needed to get Ruby up and running

sudo aptitude install ruby ruby1.9.1-dev ruby1.8-dev libgemplugin-ruby libgemplugin-ruby1.8 mysql-server apache2-mpm-prefork wget libruby-extras libruby1.8-extras rake apache2-prefork-dev libapache-dbi-perl libapache2-mod-perl2 libdigest-sha1-perl libmysqlclient15-dev build-essential libcurl4-openssl-dev cron

SUPPORT FOR GANT CHARTS (OPTIONAL)

If you want Gant charts available in Redmine, you need this install this optional Ruby module.

sudo aptitude install librmagick-ruby1.8

SET UP MYSQL

Now we need to connect to the MySQL server and set up the database needed by Redmine. If you feel uncomfortable using the mysql console client, you can use tools like phpmyadmin, but this process should be fairly straightforward.

mysql -u root -p

CREATE DATABASE redmine CHARACTER SET utf8;
CREATE USER 'redmine'@'localhost' IDENTIFIED BY 'my_password';
GRANT ALL privileges ON redmine.* TO 'redmine'@'localhost';

INSTALL REDMINE

Now it’s time to install the files needed by Redmine itself. We clone the unofficial Git repository from Github, which will be cloned into the folder /var/www/redmine. At the time of writing this how-to, the latest stable release of Redmine was the 1.3.0 branch, which we check out after we cloned the repository.

cd /var/www
sudo git clone git://github.com/edavis10/redmine.git
sudo git checkout -b 1.3.0 1.3.0

CONFIGURE THE DATABASE SETTINGS

Now we need to edit the database configuration file for Redmine so that Redmine knows how to connect to mysql to create its initial database structure with default values.

sudo cp config/database.yml.example config/database.yml
sudo vim config/database.yml

Then in the database.yml file, make the “production:” stanza of the file look like this

production:
  adapter: mysql
  database: redmine
  host: localhost
  username: redmine
  password: my_password
  encoding: utf8

INSTALL RUBY GEMS

The version of Ruby Gems that comes with Ubuntu 10.04 isn’t sufficiently new enough for us to complete the installation, and as such we’re forced to install a none packaged version.

cd
wget http://production.cf.rubygems.org/rubygems/rubygems-1.8.5.tgz
tar xvfz rubygems-1.8.5.tgz
sudo mv /usr/bin/gem /usr/bin/gem-ubuntu
cd rubygems-1.8.5
sudo ruby setup.rb
sudo ln -s /usr/bin/gem1.8 /usr/bin/gem
gem -v

gem -v should return 1.8.5

INSTALL RAILS AND OTHER NEEDED GEMS

Now we install Ruby On Rails (or RoR for short) and the required gems for Redmine to communicate with MySQL.

sudo gem install rails -v=2.3.14
sudo gem install mysql
sudo gem install rubytree -v=0.5.2

CONFIGURE THE REDMINE WEB FOLDER

We need to create a folder where Redmine stores assets used by the plugins we install later on, as well as set the needed permissions on folders used by Redmine so that the www-data user/group has read/write access.

cd /var/www/redmine
sudo 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

Now that the files and folders have been created and have their right permissions, we can now initialize Redmine and the database it will use.

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

TIME TO TEST REDMINE FOR THE FIRST TIME

sudo ruby script/server webrick -e production

Point your web browser to http://<yourip>:3000, replacing <yourip> with the IP of the host running Redmine. You could also try to log in as the admin user with the username “admin” and password “admin”. Please change this password as soon as possible! If all goes well, you can just terminate the ruby process by pressing CTRL + C.

APACHE SETUP

Running Redmine just as a ruby application as we did above is far from ideal, so let’s move on to making Redmine accessible through Apache. The way we achieve this is by installing and setting up the Apache module passenger which basically acts like an interface between Apache and Ruby applications. Let’s get it set up!

PASSENGER INSTALLATION

First, we install the passenger gem, which gives us the tools to build and install the Apache passenger module.

sudo gem install passenger
sudo passenger-install-apache2-module

Add this to /etc/apache2/mods-available/passenger.load

LoadModule passenger_module /usr/lib/ruby/gems/1.8/gems/passenger-3.0.11/ext/apache2/mod_passenger.so

Then add this to /etc/apache2/mods-available/passenger.conf

PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-3.0.11
PassengerRuby /usr/bin/ruby1.8

Then active the Apache module

sudo a2enmod passenger

APACHE VIRTUAL HOST SETUP

Add this to /etc/apache2/sites-available/redmine.yoursite.tld

<VirtualHost xxx.xxx.xxx.xxx:80>
  ServerName redmine.yoursite.tld
  ServerAdmin [email protected]

  DocumentRoot /var/www/redmine/public

  PassengerDefaultUser www-data
  RailsEnv production
  RailsBaseURI /redmine
  SetEnv X_DEBIAN_SITEID "default"

  <Directory /var/www/redmine>
    Order allow,deny
    Allow from all
  </Directory>
</VirtualHost>

Then let’s enable to virtual host and restart Apache

sudo a2ensite redmine.yoursite.tld
sudo service apache2 restart

You should now be able to get the Redmine site up by pointing your browser at http://redmine.yoursite.tld – if not, please check your configuration and your Apache access/error logs.

GIT INTEGRATION

What good is a good project management tool without actual code to manage? My favourite VCS is beyond a shadow of a doubt Git. Git is a lightweight, easy to understand and flexible system to maintain your code. In our setup, we will be using a Git daemon called gitosis to host and sort out our Git repository needs.

INSTALL GITOSIS

First, we install the needed Ruby gems to access our gitosis files, and the required libraries for gitosis as well as binaries.

sudo gem install inifile lockfile net-ssh
sudo aptitude install libnet-ssh-ruby1.8 python-setuptools gitosis git-daemon-run acl

We need to edit the file /etc/fstab to activate ACL support on the partition we store our Git repositories. Gitosis resides in /srv/gitosis, which is mounted on / on most systems, meaning we need to activate the ACL module to the / partition. This is done by adding the parameter ‘acl’ before ‘errors=remount-ro’, like this.

UUID=xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx    /    ext4    acl,errors=remount-ro    0 1

To activate the ACL module, we need to restart the machine

sudo shutdown -r now

FINAL SETUP OF GITOSIS

Now that we’ve installed gitosis and activated the ACL module for the file system gitosis resides on, we are ready to initialize the gitosis main repository. First, we need to make an SSH key for the main repository.

sudo -H -u gitosis ssh-keygen -t dsa

IMPORTANT: Please do not enter a password for this SSH key!

Let’s initialize the main repository.

sudo -u gitosis cat /srv/gitosis/.ssh/id_dsa.pub | sudo -H -u gitosis gitosis-init
sudo sed -i.orig 's:/var/cache:/srv/gitosis:g' /etc/sv/git-daemon/run
sudo sv restart git-daemon

Now we need to apply the ACL settings for the files found under the gitosis home folder.

sudo setfacl -m user:www-data:r-x,mask:r-x /srv/gitosis/.ssh
sudo setfacl -m user:www-data:r--,mask:r-- /srv/gitosis/.ssh/id_dsa

Gitosis should now be ready and installed.  But it’s still not integrated with Redmine, which will be used to view our code as well as manage the repository users. For this, we need the Redmine gitosis plugin. Let’s proceed with that.

INSTALL THE REDMINE GITOSIS PLUGIN

cd /var/www/redmine
sudo script/plugin install git://github.com/xdissent/redmine_gitosis.git
sudo -u www-data X_DEBIAN_SITEID=default RAILS_ENV=production rake db:migrate:plugins

To make sure Redmine is aware of the newly installed plugin, we need to restart Apache

sudo service apache2 restart

To enable the plugin, go to your Redmine site and log in as an admin user, then proceed to Administration -> Plugins -> Configure Redmine Gitosis Plugin.

FINAL WORDS

I hope you found this howto helpful in your quest to get Redmine set up for your project management needs. I’m sure that you, just as I did will fall head over heels for this great gem of a tool. If you spot any errors or have any comments on this little howto, please leave a comment in the comment field below. Happy mining and managing!

By Jostein Elvaker Haande

"A free society is a society where it is safe to be unpopular" - Adlai Stevenson

Leave a Reply

Your email address will not be published. Required fields are marked *