Monday, November 30, 2009

Setting Up Redmine in A Shared Hosting Environment

Let's face it: providing issue tracking and a nice looking web interface to your code is a must if you want to get your clients involved in your development process.
Redmine is an awesome issue tracker that's written in Ruby on Rails: it's extremely pretty (which everyone loves) and has some fantastic plugins to integrate with all sorts of things, including your source control system (more on that some other time!) While Ruby is not a language that I'm familiar with, I have never been one to turn my back on a solution solely for the language that it was written in. To be perfectly honest, if I did this I probably never would have gotten into PHP in the first place!

Redmine is very similar to Trac (if you have any experience with it), except for the fact that it supports multiple projects. When I first saw Redmine I was working with a shared hosting service and had never deployed a Ruby application in my life. What follows is essentially a step-by-step process for setting this up in your own shared hosting environment. It discusses version 0.8.5, but mainly because that was the version that was available when I created my notes: I doubt newer versions are massively different to set up.

Unfortunately there are a couple of prerequisites for you to get Redmine working with your hosting environment. Firstly, and probably most naturally, it needs to support Ruby on Rails applications. It also needs access to some sort of source control system: I have my installation linked to Subversion, but it does support a number of systems and so you should be able to get something working, at least. Finally, you need to have SSH access to your account. Luckily, my hosting company provided all three of these features with my account, so I was really lucky :)

Finally, there is the prerequisite that at the end of this process, you want to use a subdomain to host your Redmine installation. I have no doubt it's simple to set this up in a subdirectory instead, but the point is that this was my goal and this was what I did to get there.

Anyway, with that out of the way, let's get started...

Getting Started...
We start our process in the cPanel interface. Head into the database management area:
1) create a database for Redmine. As per the usual cPanel result, I called my database 'redmine' and ended up with a database named 'myusername_redmine'.
2) create a database user. Again, I named my 'redmine', which resulted in a user actually named 'myusername_redmine'.
3) give the new user full rights to the new database
4) in your domain management area, create a subdomain (I used, which resulted in a directory being created at ~/public_html/code)
5) in your Rails applications area, create a Rails application named 'redmine'
6) if the newly created application is already running, stop it
7) download the file redmine-0.8.5.tar.gz from
8) upload the redmine-0.8.5.tar.gz file to your home directory on the hosting server

Cracking the shell...
Open your SSH interface and keep going...
9) switch to the ~/etc/rails_apps/redmine directory
10) delete everything in the directory: rm -rf *
11) copy redmine-0.8.5.tar.gz from your home directory to ~/etc/rails_apps/redmine
12) extract the file: tar -zxvf redmine-0.8.5.tar.gz
13) switch into the redmine-0.8.5 directory and move everything to the parent directory: mv * ..
14) switch back to the parent directory and remove the now empty redmine-0.8.5 directory: rmdir redmine-0.8.5
15) copy the example database YML file: cp config/database.yml.example config/database.yml
16) open config/database.yml in your editor of choice
17) Find the section that looks like:
adapter: mysql
database: redmine
host: localhost
username: redmine
password: my_password
and set the correct value for the 'database' line, the 'username' line and the 'password' line.
18) save the file and exit back to the command line
19) create the database structure: rake db:migrate RAILS_ENV="production"
20) add the default configuration data: rake redmine:load_default_data RAILS_ENV="production"

Back to cPanel
Head back to the cPanel interface for a moment.
21) add a rewrite for the Redmine application: on the Rails application page, click 'Create a Rewrite' for the Redmine application. On the next page, change the dropdown so that it has the correct subdomain selected. Leave the text box empty and click 'Save'.
22) start the Redmine application

Back to SSH One Last Time...
Back in your SSH interface:
23) edit the .htaccess file in the directory that was originally created for your subdomain. In my case, this is the ~/public_html/code/.htaccess file
24) after the line:
RewriteRule ^/?$ "http\:\/\/127\.0\.0\.1\:12012%{REQUEST_URI}" [P,QSA,L]

add the line:
RewriteRule ^(.*)$ "http\:\/\/127\.0\.0\.1\:12012%{REQUEST_URI}" [P,QSA,L]
NOTE: in the URLs above there is a port number: that port points to the Rails app and it may be different for your particular Redmine installation. Maybe it would be better to say copy the first line, paste it and then change the '^/?$' to '^(.*)$' in that newly pasted line. (Thanks to memebenegas for pointing this out).
25) save the file and exit back to the command line
26) send your browser to the subdomain you created and see your Redmine application running. Default username is 'admin', default password is 'admin'.

And that's that: you now have your own installation of Redmine. Your co-developers will appreciate you and your clients will love you.

No comments:

Post a Comment