Redmine 0.9.4 Setup Guide

1 Introduction

Redmine is an open-source collaborate project management solution. Redmine operates as a web service that allows for multiple projects to be hosted in a single location. The goal of this guide is to quickly and efficiently set up Redmine on a server that can be used immediately.

2 System Setup

Due to the popularity of Ubuntu, and personal usage of Arch Linux both commands will be outlined when needed. The commands will begin with either ubuntu# or arch# for the specific distribution, otherwise just a # will be used when both are applicable (also mysql# will appear briefly when dealing with MySQL). In addition, most Linux distributions are fairly similar which means that the installations of packages will be the same for the majority. The release for Arch Linux is 2009.08, and the release for Ubuntu is 10.04, both on 32-bit architectures.

2.1 Install Ruby

Redmine requires Ruby to execute the code, as well as to run.
ubuntu# sudo apt-get install ruby rubygems libopenssl-ruby1.8 rake
--or--
arch# sudo pacman -S ruby rubygems

2.2 Install Subversion

To acquire the Redmine source code Subversion will be used. (Could very well use another source control management tool like Git)
ubuntu# sudo apt-get install subversion
--or--
arch# sudo pacman -S subversion

2.3 Install MySQL

Redmine makes use of a database to retain all its information, and thus requires one. MySQL will be chosen though you could use another database if you desire. Proceed with any prompts to initialize MySQL.
ubuntu# sudo apt-get install mysql-server libmysql-ruby
--or--
arch# sudo pacman -S mysql

2.4 Install Ruby Gems

Ruby has the concepts of gems which is very similar to packages to Linux. Gems contain additional functionality for the Ruby language. Ruby on Rails is used to allow Redmine to act as a web server. First the 2.3.5 version of the rails gem needs to be installed for Redmine to work, then the other specific gems.
# sudo gem install -v=2.3.5 rails
--then--
ubuntu# sudo gem install rake rack
--or--
arch# sudo gem install rake rack mysql

2.5 Install Thin

Ruby on Rails is a decent web server for Ruby web applications. Thin is an alternative to the original server(WEBrick), and offers more performance due to its lightweight nature.
ubuntu# sudo apt-get install thin
--or--
arch# sudo gem install thin

3 Redmine Setup

Now that all the packages have been acquired, the actual process of setting up Redmine can start.

3.1 Acquire Redmine Source Code

The Redmine source code is required to progress any further. Redmine's version 0.9.4 will be used as it is the latest stable release. Use the following command preferably in the /srv/ directory (best practices on where to place server material).
# sudo svn checkout http://redmine.rubyforge.org/svn/tags/0.9.4 redmine

3.2 Create Redmine Database

First ensure that MySQL is set up securely by using the following command.
# sudo mysql_secure_installation

Now to enter MySQL.
# sudo mysql -u root -p

Now create the redmine database.
mysql# create database redmine character set utf8;

Now create a redmine user for this database, with a of your choice.
mysql# create user 'redmine'@'localhost' identified by '';

Now to give this new redmine user all privileges on the database.
mysql# grant all privileges on redmine.* to 'redmine'@'localhost';

Now flush the privileges to update the database.
mysql# flush privileges;

Finally exit MySQL.
mysql# exit

3.3 Configure Redmine

The database is set up, the next part is now to configure Redmine to make use of it. Navigate to where you have Redmine and enter the directory, which should be /srv/redmine/ if the guide has been followed to the note.
# sudo cp ./config/database.yml.example ./config/database.yml

Now enter in the copied file database.yml and make the following changes to the production section located near the beginning.
# sudo nano ./config/database.yml

Configure the production:
    adapter: mysql
    database: redmine
    host: localhost
    username: redmine
    password: redmine-password

3.4 Generating Redmine Web Server

The Redmine database should be completed, so the next part is to actually make use of it. First the ruby on rails session must be create.
# sudo RAILS_ENV=production rake config/initializers/session_store.rb

Next part is to create the actual database tables.
# sudo RAILS_ENV=production rake db:migrate

Finally to populate the database with the default data.
# sudo RAILS_ENV=production rake redmine:load_default_data

3.5 Redmine Directory Permissions

Redmine should work right now, but first some loose ends need to be tied up. A new user called redmine will be created to handle the Redmine web server exclusively. Using the current user redmine, you want permission of some directories in the root of the Redmine directory.

Make the redmine user with the group access of www-data (for future uses with other server tools).
# sudo useradd -U -G users,www-data redmine

Add a password for the new redmine user.
# sudo passwd redmine

Change the owner of the directories to the redmine user and the www-data group (for future uses with other server tools).
# sudo chown -R redmine:www-data ../redmine/

Change the permissions of the directories.
# sudo chown -R 755 ../redmine/

3.6 Redmine Automation

Finally the next part is to ensure that redmine will start up when you boot up your system. This will be accomplished through the use of the crontab.

Log in as the redmine users first.
# sudo login redmine

Allow the editor to be nano (for simplicity).
# export EDITOR=nano

Now enter the crontab.
# crontab -e

We want Redmine to start when the system reboots so enter this on one-line.
@reboot cd /srv/redmine/; ruby script/server thin -e production

4 Conclusion

Redmine should start up when you restart the system. To visit Redmine you can use your browser and navigate too http://localhost:3000. It is key to note that Redmine will default to port 3000, if you want to change that you can edit the database.yml and add a port field.

The default administrator account for your Redmine web server is admin:admin (account:password).