Installing Redmine on RHEL5

Oct

2010

In the last post, I discussed why you need to bother with a project management tool like RedMine. And I'm quite certain I mentioned that it's kind of a pain to install in RedHat... so here's a step by step howto for future reference.

The following instruction are now outdated since Redmine has moved on, and has changed dependencies. Most of the information present here should still apply though, but be sure to check the specific versions of gems required in your version.

I assume that you have a normal LAMP stack that's working properly. As mentioned in the previous post, Redmine is written in Ruby on Rails (RoR), which is usually not preinstalled. So, fire up your trusty SSH client, switch to a root account, and let's get this party started:

First you need the Ruby language, then the apache module that makes it available to the web ( rails ). Normally, you'd have to go through a rather tedious process, bu thankfully the guys over at http://www.rubyenterpriseedition.com/ have made an (extremely!) nice installer that does all the heavy lifting for you. So, grap a copy! When this article was written, latest version was 1.8.7-2010.02,so
```
# cd ~
# wget http://rubyforge.org/frs/download.php/71096/ruby-enterprise-1.8.7-2010.02.tar.gz
# tar zxvf ruby-enterprise-1.8.7-2010.02.tar.gz
```
You should check with the above site to make sure you are getting the latest version. Ruby is prone to security issues as much as any other platform!
That will fetch the installer, and unzip/untar it in a subdirectory of your home folder. Now, since the installer will actually compile Ruby, you need some libraries. Don't worry if you think you have the following, if you do your package manager is clever enough to skip them
```
# yum install gcc-c++ zlib-devel openssl-devel readline-devel mysql-devel httpd-devel
```
This will most likely require to install more packages, since some of the above have dependencies. In my case, all of them were just development versions of libraries, so I went ahead with it.
After some downloading and installing you get to enjoy, you're ready for the big step: actually compiling Ruby! For that, you need to specify we're interested in a mysql backend:
```
# ./ruby-enterprise-1.8.7-2010.02/installer
```
At this point, the installer should start compiling things. If your configuration is different than mine (pretty natural since each webhost will customize their configuration ever so slightly), the installer will prompt specific instructions (even with the yum install to run!). The default values are pretty sane, so unless you have reasons to change them, leave them as is.
You should now have a working Ruby installation in /opt/ruby-enterprise-1.8.7-2010.02 , which however is not linked to anything, and has not touched your enviromental variables.

We now need to enable Ruby to talk to mysql. Ruby modules are called gems, so to install the MySQL gem just ask for it :

# /opt/ruby-enterprise-1.8.7-2010.02/bin/ruby /opt/ruby-enterprise-1.8.7-2010.02/bin/gem install mysql -- --with-mysql-config='/usr/bin/mysql_config'

The needed libraries for this were installed in our first pass, so you shouldn't have any trouble. We now need the passenger module, for Ruby to be able to handle Apache requests:
```
# /opt/ruby-enterprise-1.8.7-2010.02/bin/passenger-install-apache2-module
```
Again, libraries were installed in the first pass. We now however need to inform Apache of this module, so we need to create a new configuration file for it:
```
# nano /etc/httpd/conf.d/passenger.conf
```

Just paste the following inside the file:

LoadModule passenger_module /opt/ruby-enterprise-1.8.7-2010.02/lib/ruby/gems/1.8/gems/passenger-2.2.15/ext/apache2/mod_passenger.so
PassengerRoot /opt/ruby-enterprise-1.8.7-2010.02/lib/ruby/gems/1.8/gems/passenger-2.2.15
PassengerRuby /opt/ruby-enterprise-1.8.7-2010.02/bin/ruby

We should be all set now. Only one last tidbit left: if you're using Plesk to manage your vhosts, you need just one more step, since Redmine is based on a "pure" MVC architecture. You must define that the document root is not httpdocs but httpdocs/public instead. To do that for a domain named mydomain.com, on a subdomain called redmine, you need to create a file in the conf folder:
```
# nano /var/www/vhosts/mydomain.com/subdomains/redmine/conf/vhost.conf
```
If you don't want to setup in a subdomain, just omit the subdomains/redmine part of the file, so that the final path is /var/www/vhosts/mydomain.com/conf/vhost.conf
You should obviously substitute for your domain name and subdomain. Now paste the following line to alter the document root folder to httpdocs/public
```
DocumentRoot /var/www/vhosts/mydomain.com/subdomains/redmine/httpdocs/public
```
Right. So that takes care of that as well, let's now reload Apache in a way that doesn't break connections, or annoy customers
```
# /etc/init.d/httpd graceful
```
You also need to let Plesk know that something has changed in its vhost configuration
```
# /usr/local/psa/admin/sbin/websrvmng -a
```
Your server is all setup! Now let's install and configure Redmine. First order of business is to downgrade a tool called rake, since Redmine doesn't like the latest version
```
# cd /opt/ruby-enterprise-1.8.7-2010.02/bin
# ./gem install rack -v=1.0.1
```
Create a database in MySQL using any tools you normally do ( like phpMyAdmin )

To create the database configuration, do the following

# cd /var/www/vhosts/mydomain.gr/subdomains/redmine/httpdocs/config
# cp database.yml.example database.yml
# nano database.yml

Find the section production: and enter your database details below it. A sample might be

production:
  adapter: mysql
  database: mydomain_redmine_dbname
  host: localhost
  username: redmine_user
  password: redmine_password
  encoding: utf8

Now initialize the database schema

# RAILS_ENV=production /opt/ruby-enterprise-1.8.7-2010.02/bin/rake db:migrate

And import the initial dataset

# RAILS_ENV=production /opt/ruby-enterprise-1.8.7-2010.02/bin/rake redmine:load_default_data

Assuming your domain username (as chosen in Plesk domain setup) is the domain name, grant permissions to apache from httpdocs:

# cd /var/www/vhosts/mydomain.com/httpdocs
# chown -R mydomain.com:psacln files log tmp public/plugin_assets
# chmod -R 755 files log tmp public/plugin_assets

And finally -- go to redmine.mydomain.com and enjoy the result of ... well, all this!
The default credentials for Redmine are:
username: admin
password: admin