Sunday, March 22, 2015

Parallel Redmine Installations: Installation

Install Redmine with RVM, Git, Apache, Phusion Passenger and MySql under Ubuntu Server 14.04


As a system admin I've been responsable for managing our Redmine server in my company for nearly two years now. Over this time I've found some problems that made me search for a way to be able to install and test new Redmine versions without affecting my currently running Redmine environment.
Using RVM and dedicated gemsets requieres a little more overhead for the installation but on the long run it brings huge benefits, specially if you are a sysadmin.

The Concept

Following table shows how separated redmine installations can be organized using RVM.

In addition to the three elements in the table (redmine, ruby+gems,passenger) you can have separated databases for every Redmine version, or directly migrate the current database.
In my case, my goal is to be able to test new Redmine releases in a safe environment before I decide to upgrade to it. So for testing purposes, I dump the currently used Redmine database, create a new database and import the dump back into the new database.
Once I'm sure the new version works well, I drop the old database and the related Redmine and ruby stuff.
If for some reason the new version does not work, switching back to the older version is not a problem.

Following I will describe how to install Redmine from GitHub 2.6-stable branch with dedicated ruby, gems and passenger module. Follow the same steps to install other separated Redmine versions.

Install Dependencies

root@redmine:/home/adrian# apt-get install apache2 mysql-server git libmysqlclient-dev imagemagick libmagickwand-dev libcurl4-openssl-dev apache2-threaded-dev libapr1-dev libaprutil1-dev


Create Dedicated User

This user's home will live under /opt/redmine which will hold the redmine as well as ruby, ruby gems and the passenger modules.
root@redmine:/home/adrian# adduser --home /opt/redmine redmine
Add the redmine user to the sudo group
root@redmine:/home/adrian# gpasswd -a redmine sudo
This is needed since RVM will install system dependencies via apt-get when needed.


Install RVM

Switch to the newly created redmine user
root@redmine:/home/adrian# su - redmine
Get RVM gpg key
redmine@redmine:~$ gpg --keyserver hkp:// --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
Install RVM stable
redmine@redmine:~$ curl -sSL | bash -s stable
To start using RVM source the rvm script
redmine@redmine:~$ source /opt/redmine/.rvm/scripts/rvm
The RVM installer adds RVM to the user's PATH variable so there is no need to source RVM every time you switch to the redmine user.

Before we move on to install ruby and ruby gems, we will prepare the database and get Redmine from Git.

Prepare Redmine database

In this example I will create a new database named redmine_production, adjust the database name to your needs. If you are going to use the same database there is no need to create a new one but I would recommend to create a new separated database for testing since the rake:migrate commands later on will make changes to the database.

Connect to the mysql server with the root user
redmine@redmine:~$ mysql -uroot -p
Create the Redmine database and the redmine user to connect to that database.
mysql> create database redmine_production character set utf8;
mysql> create user 'redmine'@'localhost' identified by 'redmine_mysql_user_password';
mysql> grant all privileges on redmine_production.* to 'redmine'@'localhost';
mysql> flush privileges;
mysql> exit

Install Redmine from Git

Clone Redmine's repository on GitHub
redmine@redmine:~$ git clone redmine-2.6-stable
Symlink the Redmine directory
redmine@redmine:~$ ln -s redmine-2.6-stable active
This symlink is needed for an easier switch between Redmine versions. The apache virtual host file will reference the DocumentRoot, PassengerAppRoot, etc using this active symlink.
Of course you can have different virtual hosts for the different Redmine paths and enable/disable as needed. I prefer the symlink method.

Cehckout the 2.6 stable branch
redmine@redmine:~/redmine-2.6.2$ git checkout origin/2.6-stable -b 2.6-stable
Configure Redmine 

The  database.yml and configuration.yml is  where you configure redmine. I will not dive into the configuration.yml file, take a look to the redmine installation documentation for it.
redmine@redmine:~/redmine-2.6.2$ cp config/database.yml.example config/database.yml
redmine@redmine:~/redmine-2.6.2$ cp config/configuration.yml.example config/configuration.yml
Edit the database.yml (production section) file to fit the mysql redmine database created in the previous section.
  adapter: mysql2
  database: redmine_production
  host: localhost
  username: redmine
  password: "redmine_mysql_user_password"
  encoding: utf8
Adjust permissions
redmine@redmine:~/redmine-2.6.2$ sudo chown -R www-data files log tmp public/plugin_assets redmine@redmine:~/redmine-2.6.2$ sudo chmod -R 0775 files log tmp public/plugin_assets

Install Ruby and Gems

redmine@redmine:~$ rvm install 1.9.3
Create Gemset
redmine@redmine:~$ rvm gemset create redmine-2.6-stable
Use Gemset
This is a very important part. Every time you are going to manage gems you have to make sure the currently used gemset is the right one! Please read the RVM:Using Gemsets reference.
So after creating the redmine-2.6-stable gemset, listing the current available gemsets shows following. Note the arrow points to the currently used gemset:
redmine@redmine:~$ rvm list gemsets

rvm gemsets

=> ruby-1.9.3-p551 [ x86_64 ]
ruby-1.9.3-p551@global [ x86_64 ]
ruby-1.9.3-p551@redmine-2.6-stable [ x86_64 ]
We want to use our redmine-2.6-stable gemset:
redmine@redmine:~$ rvm use gemset ruby-1.9.3-p551@redmine-2.6-stable
Using /opt/redmine/.rvm/gems/ruby-1.9.3-p551 with gemset redmine-2.6-stable
List gemsets again to check that the redmine-2.6-stable gemset is selected:
redmine@redmine:~$ rvm list gemsets

rvm gemsets

ruby-1.9.3-p551 [ x86_64 ]
ruby-1.9.3-p551@global [ x86_64 ]
=> ruby-1.9.3-p551@redmine-2.6-stable [ x86_64 ]
Install Redmine Gems
redmine@redmine:~$ cd redmine-2.6-stable/
redmine@redmine:~/redmine-2.6-stable$ bundle install --without develop,test,postgresql,sqlite
redmine@redmine:~/redmine-2.6-stable$ gem install passenger
RMV and bundler integration
This step is needed since we will use bundler to install Redmine required gems. More detailed information about RVM and bundler integration in the RVM site.
redmine@redmine:~$ gem regenerate_binstubs

Install Phusion Passenger

redmine@redmine:~/redmine-2.6-stable$ passenger-install-apache2-module

Setup Apache

Create a configuration file under /etc/apache2/conf-available named passenger-ruby-1.9.3-p551@redmine-2.6-stable which links to the passenger module.
Why this name? Because later on, when we want to switch between redmine installations with their separated ruby + gems installations, we will have separated passenger modules for each of them.
LoadModule passenger_module /opt/redmine/.rvm/gems/ruby-1.9.3-p551@redmine-2.6-stable/gems/passenger-5.0.4/buildout/apache2/
<IfModule mod_passenger.c>
   PassengerRoot /opt/redmine/.rvm/gems/ruby-1.9.3-p551@redmine-2.6-stable/gems/passenger-5.0.4
   PassengerDefaultRuby /opt/redmine/.rvm/gems/ruby-1.9.3-p551@redmine-2.6-stable/wrappers/ruby
Virtual Host
Note that all references to the Redmine path use the active symlink instead of the actual Redmine directory, this way you only need to point the symlink to the right Redmine directoy to switch between Redmine versions and only one virtual host file is needed.
This is just a sample file. You will have to adjust it to your needs.
<VirtualHost *:80>
ServerAdmin admin@domain.sample
ServerName redmine.domain.sample

DocumentRoot /opt/redmine/active/public/
RailsBaseURI /
PassengerAppRoot /opt/redmine/active
PassengerUser www-data
PassengerGroup www-data

<Directory /opt/redmine/active/public/>
Options +Indexes +FollowSymLinks -MultiViews
AllowOverride All
Order allow,deny
Allow from all
LogLevel warn
ErrorLog ${APACHE_LOG_DIR}/redmine.error.log
CustomLog ${APACHE_LOG_DIR}/redmine.access.log combined
Final Steps
Note that the rake redmine:load_default_data step is only needed when making a fresh new installation. Omit this step if using an already exiting (or imported from dump) Redmine database. The rake redmine:plugins:migrate is needed only if you are using some extra plugins.
redmine@redmine:~/redmine-2.6-stable$ rake generate_secret_token
redmine@redmine:~/redmine-2.6-stable$ RAILS_ENV=production rake db:migrate
redmine@redmine:~/redmine-2.6-stable$ RAILS_ENV=production rake redmine:load_default_data
redmine@redmine:~/redmine-2.6-stable$ RAILS_ENV=production rake redmine:plugins:migrate