TangoRangers.com's Blog

Recently my work switched to Redmine to keep track of our projects and such, I loved it so much, I wanted to use it at home for my personal projects. Seriously, if you have never used it, give it a try, you won’t be disappointed. However, there is a problem that I ran into when setting it up at home, my Ruby was too new! At the time of this writing Redmine version 1.2.2 was the current stable, and required Ruby 1.8.6 or 1.8.7. My server came with 1.9.1! I could either downgrade and risk possible incompatibility problems, or I could take another approach. After days of Goggling, I found a solution.

Check out https://rvm.beginrescueend.com/rvm/install/

I recommend the single user install. I did it with no problems. Things get a bit tricky when using RVM, so I decided to create this Quick and Dirty Guide.

How to Install and Setup Redmine with RVM

Be sure to pay attention to directories, I will make notes to help make things easy. Also, I recommend trying this out in a VM or a dev box. Please read the HowTos on redmine.org and do some research and testing before following this guide.

Note: This was done running Slackware 13.1. I do NOT use sudo on my machines. If you get a permissions error you can use sudo if your Linux distro is setup for it. The first part of this I did as the root user. If you use sudo, type ‘sudo su -‘ to become full root. If you see Redmine (with the capital R), I’m referring to the Redmine program or website. Lowercase, is the user redmine.

After downloading the source from redmine.org extract it and rename the folder to redmine, you don’t have to do this, it’s just how I did it.

Setup a Redmine user

This user doesn’t need remote access, or the ability to login directly. We are going to create a new user and group for Redmine to run under.

groupadd redmine
useradd redmine -g redmine -m

Now set permission to where you extracted Redmine to. We are going to give everything to the redmine user and group.

chown redmine:redmine redmine/ -R

Now you need to su – redmine. Make sure you are in the redmine user’s home directory. Usually /home/redmine/

Setup RVM

Now that you are the redmine user and in their home directory, it’s time to install RVM. Be sure to check out their website for full and up to date information. The information listed here maybe out of date!

Lets install RVM for single user use. You are welcome to use the multi-user version, but this way worked just fine for me. Once again, make sure you are in the redmine user’s home directory.

bash < <(curl -s https://raw.github.com/wayneeseguin/rvm/master/binscripts/rvm-installer )

This will get the installer going. Once it finishes, run this:

echo '[[ -s "$HOME/.rvm/scripts/rvm" ]] && . "$HOME/.rvm/scripts/rvm" # Load RVM function' >> ~/.bash_profile

Now logout. Log back in as the redmine user. and type:

type rvm | head -1

You should get back rvm in a function. If not, something went wrong. Try the commands listed above again. If you get an error about a broken pipe, don’t worry about it. I got it once, but never again. I have no idea why.

If you do get back the good news type:

rvm install 1.8.7

This will install ruby 1.8.7! Once it is complete type:

rvm use 1.8.7

If you don’t get back any errors, type:

rvm use 1.8.7 --default

This will set that ruby version as your default (only for the redmine user!) RVM is now setup. Good job!

Install Some Ruby Gems

Now that RVM is setup and Ruby 1.8.7 is installed, we need to setup some gems for ruby. First step is getting the correct version of RubyGems installed. As per the Redmine documentation, we want version 1.3.7. I find the easiest way of doing this is to grab their .tgz file. Once you get it (you can also find a list of versions available for download here. Extract it, and run setup.rb.

wget http://rubyforge.org/frs/download.php/70696/rubygems-1.3.7.tgz
tar zxf rubygems-1.3.7.tgz
ruby rubygems-1.3.7/setup.rb

It should only take a second or two to install. Once it’s complete there are two more gems that need to be installed before continuing. It is easy and straight forward. Note: If your system appears to freeze when running the commands below, do not worry. It’s working in the background a may take a minute or two.

gem install rails -v=2.3.11
gem install -v=0.4.2 i18n

Setup MySQL

Assuming you are still the redmine user and MySQL is setup and ready to go, these next steps are very easy and were taken right from Redmine’s website. Follow the steps below.

mysql -u root -p
create database redmine character set utf8;
create user 'redmine'@'localhost' identified by 'redpass';
grant all privileges on redmine.* to 'redmine'@'localhost';
flush privileges;

Take note of redpass. Change it to the password you want to use!

Log out of MySQL and stay logged in as the redmine user. Change directory to where the redmine program is stored. For this example, and the rest of the article, I’m going to assume it’s in /srv/redmine

Copy config/database.yml.example to config/database.yml then edit config/database.yml to include your db setup (under production. You can remove the others)

Copy public/dispatch.cgi.example to public/dispatch.cgi then changes first line to the path of the redmine user’s ruby location (/home/redmine/.rvm/bin/ruby in my case)

public/dispatch.cgi needs to have execute permissions. If it does not, type: chmod 755 public/dispatch.cgi

Uncomment NV[‘RAILS_ENV’] ||= ‘production’ in config/environment.rb

Now we need to setup MySQL access. Below are four (4) commands that will do all this including building the MySQL gem. Please note the path to mysql_config. Make sure this matches your setup!

rake generate_session_store
gem install mysql -- --with-mysql-config=/usr/bin/mysql_config
RAILS_ENV=production rake db:migrate
RAILS_ENV=production rake redmine:load_default_data

If any of these fail, something may have gone wrong with RVM or MySQL. Check you meet the minimum qualifications listed on Redmine’s website and your paths are correct.

Setup Passenger

Passenger is designed to run as an apache module to keep Ruby of Rails running. If Redmine isn’t used for a while, Ruby of Rails may stop running, it’s not a big deal, it just means it will take a second longer to access your first request. It’s easy to setup, and can be done as the redmine user. So make sure you are still logged in as your redmine user.

I’m running version 3.0.11 or Passenger, you are welcome to do the same. There are only three (3) simple steps involved. So I put them below. Just give it some time to build, it can take a few minutes.

wget http://rubyforge.org/frs/download.php/75548/passenger-3.0.11.tar.gz
tar zxf passenger-3.0.11.tar.gz
./passenger-3.0.11/bin/passenger-install-apache2-module

Once the build finishes there are some lines you need to add to your apache.conf file. They are listed above, they are easy to see. Now, depending on your Linux distro, there are several names and locations for this file. You will need root access to edit the Apache config.

At this point you can stop being logged in as the redmine user. Go back to being root (or your regular user with sudo access)

Setup Apache

This setup worked well for me, I would recommend reading up on Apache config options at http://www.redmine.org/projects/redmine/wiki/HowTo_configure_Apache_to_run_Redmine

The page is a little hard to understand when talking about mod_fcgi and mod_fastcgi. You do NOT need them. They maybe faster, but I find that mod_cgi works just fine.

I’m getting a bit lazy here, and I don’t feel much like going into a lot of explanation on all the options you can use in Apache. Below is a sample of what I used.

<VirtualHost *:80>
   ServerName redmine.<YOUR-DOMAIN>.com
   ServerAdmin webmaster@<YOUR-DOMAIN>.com
   DocumentRoot /srv/redmine/redmine/public/
   ErrorLog /srv/redmine/redmine/log/redmine_error_log
   <Directory "/srv/redmine/redmine/public/">
      Options Indexes ExecCGI FollowSymLinks
      Order allow,deny
      Allow from all
      AllowOverride all
   </Directory>
</VirtualHost>

Obviously there are changes you need to make, like ServerName and ServerAdmin. Note how all the directories start with /srv/redmine/, Update it to where you extracted the Redmine program.

All done!

At this point you should just have to restart apache and you are good to go! Assuming you actually read the Redmine documentation, you can now login as admin (password admin) and give it a go. The first thing I recommend doing is creating a new Admin Level User and removing the default admin. If you get an Internal Error 500 when trying to add a new user, then something is definitely wrong. Check the redmine_error_log and production.log file (both should be in the same directory). If you see something about an error with US_ASCII, then Ruby is not running out of the redmine user’s home directory. Go back through and double check your settings.

I have been told that creating the redmine user in the fashion shown above can create a security risk. As root open /etc/shadow in your favorite editor. At the bottom of the list will be the redmine user. You may see something like:

redmine:!:12585:0:99999:7:::

If you change the exclamation point to an asterisk, it disables the account. That way you can not log into it remotely. Also, if you really want to play it safe, you can edit /etc/passwd also. Just change the last part of the file from /bin/bash to /bin/false. However, by doing this you will not be able to login, or su to that user.

Well?

Did this guide work for you? Do you have any suggestions that may work better? I would love to hear! Feel free to post a comment and let me know how it worked for you, and let me know what Linux distro and version you are running. Thank you.