How To Install Redmine 2.1.2 on FreeBSD Apache (with Passenger and RVM)

A few days ago I needed to setup a FreeBSD server from scratch, in order to have a dedicated ticketing and project management system at work. We decided to use the popular Open Source Project Management Software, Redmine, since some of us had some previous (positive) experiences with it.

Looking through the Redmine community wiki, I noticed that the guides on how to install Redmine on a FreeBSD system were either outdated, or in a language I couldn’t understand. In contrast, one can find so many (and up to date!) guides for Debian and Ubuntu. Well, I could not let this injustice stand, so I set out to document the whole process.

Installing Redmine on FreeBSD isn’t hard, but it requires many steps (especially if the machine you are working on is bare and has just the minimum software ports installed.

This guide has the prerequisites of a working FreeBSD server with Apache and MySQL configured and ready to work on (there’s plenty of guides out there to set those up). Preferably, you should also have super user rights on the machine, otherwise this whole venture might prove more difficult than it should be.

If your server is already setup with Ruby, GIT, Passenger and ImageMagick, you can skip past most of the introductory stuff and go straight to the Redmine Installation part.

Compile all the things

We’ll be needing a few packages before we can actually install Redmine on our server. I’ll be documenting the steps I went through on the basis that none of this is already installed (as it wasn’t on my machine either). First thing to do would be to update our ports:

[color-box]$ portsnap fetch
 $ portsnap extract[/color-box]

We’ll need curl to install Ruby Version Manager, so let’s get that out of the way too:

[color-box]$ cd /usr/ports/ftp/curl
$ make install clean[/color-box]

Wget is optional, but it’ll come in handy later when we download the Redmine source:

[color-box]$ cd /usr/ports/ftp/wget/
$ make install clean[/color-box]

Next up is ImageMagick. This will take a while, but it’s worth it if you want to have properly working Gantt exports and other image manipulation features (ie. with some of Redmine’s plugins).

NOTICE: Make sure to install ImageMagick WITHOUT HDRI support, since the rmagick gem which we’ll be installing later on doesn’t play along with it.

[color-box]$ cd /usr/ports/graphics/ImageMagick
$ make install clean[/color-box]

If you haven’t installed bash yet on the server, you’ll be needing it later on:

[color-box]$ cd /usr/ports/shells/bash
$ make install clean[/color-box]

Install git

[color-box]$ cd /usr/ports/devel/git
$ make install clean[/color-box]

Setting up RVM

Using RVM (Ruby Version Manager) will allow you to more easily handle multiple ruby versions, gemsets and rails applications on your server. I think it’s a must have on environments where mor ethan one applications might be deployed in the future. If you don’t like RVM, there’s also Sam Stepehenson’s rbenv available, which has a more to-the-point approach to the same issue.

First of all, let’s add a new user for RVM:

[color-box]$ adduser

Username: rvm
Full name: Ruby Version Manager
Uid (Leave empty for default): 
Login group [rvm]: 
Login group is rvm. Invite rvm into other groups? []: 
Login class [default]: 
Shell (sh csh tcsh bash rbash nologin) [sh]: bash
Home directory [/home/rvm]: 
Home directory permissions (Leave empty for default): 
Use password-based authentication? [yes]: no
Lock out the account after creation? [no]: no
Username   : rvm
Password   : 
Full Name  : Ruby Version Manager
Uid        : 1001
Class      : 
Groups     : rvm 
Home       : /home/rvm
Home Mode  : 
Shell      : /usr/local/bin/bash
Locked     : no
OK? (yes/no): yes
adduser: INFO: Successfully added (rvm) to the user database.[/color-box]

[color-box]$ su rvm[/color-box]

Install RVM using curl. This line will also install the latest stable Ruby version.

[color-box]$ $ \curl -L https://get.rvm.io | bash -s stable --ruby[/color-box]

Make sure to follow the instructions at the end of RVM’s installation process and reload your Bash profile.

[color-box]$ source ~/.bash_profile[/color-box]

Check that everything runs smoothly.

[color-box]$ type rvm | head -1[/color-box]

The above should return rvm is a function

[If you have used the curl command above without the –ruby flag] Install your ruby version

[color-box]$ rvm install 1.9.3-head[/color-box]

Set the ruby version as the system default

[color-box]$ rvm use 1.9.3-head --default[/color-box]

Let’s also create a default gemset which will be used by our Redmine installation:

[color-box]$ rvm gemset create redmine
$ rvm use 1.9.3-head@redmine --default[/color-box]

Finally, check that your ruby version is the one we just installed

[color-box]$ ruby -v[/color-box]

Setting up Redmine

With all the introductory stuff out of the way, we can move on to installing Redmine on our server. First, let’s install the bundler gem:

[color-box]$ gem install bundler[/color-box]

Get the latest version of Redmine from this link (if you don’t have wget installed, just visit the link download the tar.gz file and upload it to your server) and untar it:

[color-box]$ cd /usr/local/www/
$ wget http://rubyforge.org/frs/?group_id=1850
$ tar xvfz redmine-2.1.2.tar.gz[/color-box]

Cd into the new directory and run bundler to install all the required gems (skipping unnecessary gems)

[color-box]$ cd redmine-2.1.2/
$ bundle install --without development test postgresql sqlite[/color-box]

We’ll also install the MySQL C bindings for Ruby, they provide a significant performance increase and there’s really no reason to have a rails app running without them.

[color-box]$ gem install mysql2[/color-box]

Next up, create a database and a user specific to Redmine.

[color-box]$ create database redmine character set utf8;
$ create user 'redmine'@'localhost' identified by 'my_password';
$ grant all privileges on redmine.* to 'redmine'@'localhost';[/color-box]

We need to create a database.yml file for the Redmine installation to use.

[color-box]$ cd /redmine/installation/dir
$ cp config/database.example.yml database.yml
$ vi config/database.yml[/color-box]

Change the adapter to mysql2 (if you’ve installed the mysql2 gem above), then change the database name, username and password to the ones you’ve set when creating your redmine database for the production namespac ie:

[color-box]$ production:
   adapter: mysql2
   database: redmine
   host: localhost
   username: redmine 
   password: redmineuserpass
   encoding: utf8[/color-box]

Now we’re ready to run database migrations and secret key generators for the production environment. This will also load a default data set for Redmine with sample categories, task sets etc.

[color-box]$ rake generate_secret_token
$ RAILS_ENV=production rake db:migrate
$ RAILS_ENV=production rake redmine:load_default_data[/color-box]

Installing Passenger

In order for the Redmine application to spawn on Apache, we’ll need some kind of interface to run it from. Here, it’s up to you to decide what kind of modules or servers you want to be running, I went with Passenger. We’ll need to install the Passenger gem & the corresponding module for Apache.

[color-box]$ gem install passenger
$ passenger-install-apache2-module[/color-box]

Now that passenger’s installed, we’ll need to add a few lines to cnfigure it properly in order to run with Apache. Inside your httpd.conf (in /usr/local/etc/apache22/httpd.conf) add the lines:

[color-box]$ LoadModule passenger_module /home/rvm/.rvm/gems/ruby-1.9.3-p194@redmine/gems/passenger-3.0.17/ext/apache2/mod_passenger.so
$ PassengerRoot /home/rvm/.rvm/gems/ruby-1.9.3-p194@redmine/gems/passenger-3.0.17
$ PassengerRuby /home/rvm/.rvm/wrappers/ruby-1.9.3-p194@redmine/ruby
$ PassengerDefaultUser www[/color-box]

Notice here that I use /home/rvm/ which means that I installed RVM for the user ‘rvm’. Next, we’ll also need to modify our vhosts file as well. Open /usr/local/etc/apache22/Includes/your.domain.com.conf with an editor (or create it first if it doesn’t exist) and add the following:

[color-box]<VirtualHost SERVER.IP.ADDRESS.HERE>
    ServerName server.domain.com
    ServerAdmin [email protected]
    DocumentRoot /usr/local/www/redmine/public
</VirtualHost>

<Directory "/usr/local/www/redmine/public">
    AllowOverride All
    Options -MultiViews
    Allow from all
</Directory>[/color-box]

Finally, restart Apache:

[color-box]$ apachectl restart[/color-box]

Try visiting your site via a browser, and you should now see a working Redmine installation. The default login credentials are

username: admin
password: admin

Epilogue

There’s quite a few steps to take if you’re starting out with a basic server setup, but all in all it is a straight forward process. If you’ll excuse me now, I’ll get back to creating some tasks…