Redmine is a great project management web application which is pretty easy to set up if you have experiences with Ruby on Rails applications.

As this was my first or maybe second encounter with a RoR application, I ran on a couple of difficulties while trying to install Redmine on our company’s web server (which is a Media Temple dedicated virtual server running CentOS 5). This is a guide on installing it on an (mt) server and running it under Apache2 with Phusion Passenger. I’m not going to repeat each step from the official installation guide, just the differences for this setup.

Before setting this up on a live server, I have tried setting it up on my local machine running Mac OS 10.5.8. With the built in WEBrick I got it running within minutes. I thought I would finish with the installation on the live server in no time, but as it turned out  - I was wrong.

Here are the steps that I had to take to get this setup working:

STEP 1 - Install Ruby and RubyGems

Media Temple has a great guide on this one. Use that to set up Ruby and all the required gems. If you are following this guide there's no need to install the mongrel/mongrel_cluster as we will use Phusion Passenger to run Redmine.

Using this guide I have set up Ruby 1.8.6 and RubyGems 1.3.5.

NOTE: the rubygems setup takes more time to finish than usual. Be patient! This was the first mistake that I have committed...

STEP 2 - Install the Passenger Gem

Installing Phusion's Passenger is very straight-forward. Here's how I have done it:

gem install passenger

After that run the wizard:

passenger-install-apache2-module

and follow the on-screen instructions. At the end you will get a couple of configuration lines that you need to insert into your main Apache configuration. The best way to do that is to create a passenger.conf file in /etc/httpd/conf.d/, and paste the configuration there.

STEP 3 - Install Redmine

Follow the official wiki and install Redmine.

You will need to rename all dispatch.*.example files in the public folder of your Redmine installation. You just need to remove the .example part from the filename. Also, make sure their executable flag is set.

STEP 4 - Set up Apache

As the target server is a (dv) server, I have used Plesk to set up a subdomain for Redmine (let’s say redmine.my-domain.com). Be sure to check the CGI and/or FastCGI option under Services when you create the subdomain!

The Apache configuration should look like this:

DocumentRoot /var/www/redmine/public
<Directory "/var/www/redmine/public">
Options FollowSymLinks
Order allow,deny
Allow from all
</Directory>
RailsBaseURI /

where /var/www/redmine is the path of your Redmine installation. Save this configuration as vhost.conf in your subdomain’s conf folder.

So, if your main domain is my-domain.com, and your subdomain that you have created is redmine, the configuration file should go here:

/var/www/vhosts/my-domain.com/subdomains/redmine/conf/vhost.conf

Now restart Apache.

Catch number one

According to the number of guides you should now have a working project management app. Unfortunately that was not the case with my setup. I kept getting errors like this:

[Thu Aug 13 16:30:36 2009] [notice] Apache configured -- resuming normal operations
/usr/local/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:31:in `gem_original_require': no such file to load -- fastthread (LoadError)
	from /usr/local/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:31:in `require'
	from /usr/local/rubygems/gems/gems/passenger-2.2.4/lib/phusion_passenger/utils.rb:27
	from /usr/local/rubygems/gems/gems/passenger-2.2.4/bin/passenger-spawn-server:53:in `require'
	from /usr/local/rubygems/gems/gems/passenger-2.2.4/bin/passenger-spawn-server:53

As it turned out, some gems needs to be in the site_ruby subfolder, otherwise the app/server will not find it, and your app will not run. Googling around didn’t help, so I have desperately tried to solve this. The solution is so simple that I had to share it with you.

All you have to do is to run fastthread’s setup file. To do that, type the following (assuming your rubygems path is /usr/local/rubygems/)

ruby /usr/local/rubygems/gems/gems/fastthread-1.0.7/setup.rb

Restart Apache. Now you should see something different, hopefully a working Redmine. If that's not the case, keep readig on.

Catch number two

If you are still getting a RoR error when you try to access Redmine, it’s time to check the Redmine log. To list the last error messages, type this:

tail /var/www/redmine/log/production.log

On our server I had to tell Redmine where’s my MySQL’s socket located. So if you are getting a similar line in your production.log, you will know what to do:

Errno::ENOENT (No such file or directory - /tmp/mysql.sock):
    /vendor/rails/activerecord/lib/active_record/vendor/mysql.rb:107:in `initialize'
    /vendor/rails/activerecord/lib/active_record/vendor/mysql.rb:107:in `new'
    /vendor/rails/activerecord/lib/active_record/vendor/mysql.rb:107:in `real_connect'
    .
    .

To tell Redmine where is your socket located, find the database.yml file from the redmine/config folder and insert a line as follows:

production:
  adapter: mysql
  database: redmine
  host: localhost
  username: redmine
  password: **********
  encoding: utf8
  socket: /var/lib/mysql/mysql.sock

Catch number three

Be careful with the permissions! Your apache and passenger should be able to read and write to your redmine installation. By default, Phusion Passenger runs Rails applications as the owner of environment.rb. On my setup I have set apache as the owner of my Redmine installation and I have set up passenger as follows:

PassengerUserSwitching off
PassengerDefaultUser apache

These lines should go in your passenger.conf that you have created in step 2. After these changes you need to restart the webserver.

That’s it! Now you have made Redmine work on (mt)!

This is a non-standard Redmine installation. Passenger might not be the best way to run an application, but considering the number of our users, it is sufficient for us. I thought I would share this as I wasn’t able to find a comprehensive and complete guide on this subject. Hope some of you find this useful!