A guide to migrate old Ruby on Rails applications on the Windows platform. The guide requires no special skills in either Ruby on Rails or advanced Windows\Linux administration.

1. A manual for Microsoft-product-based developers:
How to successfully migrate old Ruby on Rails
solutions to Microsoft platforms
(Ruby 1.87+ and 2+ Series Rails with MySQL on Windows 8.1 & WinServer 2012R2)
22 March 2014
DIMITRIS VAYENAS, POSTGRADUATE STUDENT
DEPARTMENT OF COMPUTER SCIENCE @ THE UNIVERSITY OF OXFORD &
SOFTWARE INCUBATOR @ ISIS INNOVATION LTD.

2. Contents
 Motivation (in lieu of an introduction)
 The Scenario
 Installing Ruby 1.87 on Rails & DevKit
 Installing MySQL 5.6
 Installing Image Processors
 Building the Manifest
 Development Tools(Sapphire & Ruby Mine)
 Side-by-Side Ruby Installations
 Conclusions
 Acknowledgements

3. Motivation (in lieu of an introduction)
Having spent the past few days in migrating an old -but extremely complex- Ruby on Rails
solution from Linux to a Microsoft environment, I was confronted with a number of challenges:
The project relied upon an outdated version of Ruby on Rails, while the information available on
the web on various vistas (forums, stackoverflow etc.) was either fragmented or misleading or
both.
After having read over a hundred how-to articles and posts dealing with the various issues -from
various gems not installing, gcc and bash concerns down to MySQL and the image processor
concerns- I found useful to concentrate all this knowledge in a document in order to ensure a
trouble free installation by junior IT personel.
This manual was originally intended for distribution to all my colleagues (existing and unknown)
here who will have to perform this installation to their systems; yet following a discussion with the
person who “pays for my time” (as the word boss or supervisor are inappropriate in this context)
we decided to make this information available to all.

4. The Scenario
We had to migrate to Windows 8.1 and Windows Server 2012 R2 an application dating from
2006 that was (well… is) running on Ruby 1.87 and Rails 2.3.18.
The application requires also the following:
MySQL server 5+
accessed via mysql and mysql2 gems
Jaggernaut 0.5.7
(inclusive of EventMachine 1.0.3)
for Asynchronous Transaction Handling
Rmagick 2.12.0
for the Image Processing chores

5. Installing Ruby 1.87 on Rails & DevKit
A. In the event that you have Cygwin, it is EXTREMELY IMPORTANT to uninstall it prior to attempting to install your application. Failure to do so,
dramatically increases the risk of a variety of failures during the compilation of the native gems.
B. Until we complete all steps in this presentation, FORGET that you are running in a 64bit kit. EVERYTHING that you are going to install (inclusive
of MySQL) needs to be in 32bit mode.
C. Download from http://rubyinstaller.org/ the Ruby 1.8.7-p374 and DevKit-tdm-32-4.5.2-20111229-1559-sfx.exe
D. Do not install in the root of your C disk (which is the default installation path of the 1.87 Installer). You better create a directory such as
C:UsersYour_User_AccountRuby and install it there. Depending on the security configuration of your kit, this is likely to spare you from a series of
permission-related bugs while installing a number of gems. Thus, effectively you will have two directories:
C:UsersYour_User_AccountRubyRuby187
& C:UsersYour_User_AccountRubyDevkit
For added peace of mind do a restart (unless you know how to update on the fly the Environment Variables of your kit; or you are too bored to
follow the steps here: http://www.websol.nl/en/tutorials/windows_tutorial/how_to_add_an_environment_variable_without_rebooting_windows.html).
E. Upon reboot start with command prompt and navigate to your DevKit Directory and type:
C:UsersYour_User_AccountRubyDevkitruby dk.rb init <press enter>
C:UsersYour_User_AccountRubyDevkitruby dk.rb install
F. Downgrade your version of gem engine! EXTREMELY IMPORTANT by issuing the command:
C:UsersYour_User_AccountRubyRuby187gem upgrade --system 1.8.7
G. Install the Rails of your choice using the command: C:UsersYour_User_AccountRubyRuby187gem install rails –v 2.3.18
(IMPORTANT!!! The gem engine version is different from the Ruby version… even if you decide to install Ruby 1.9.3 you will still need to downgrade
your gem engine! To install very old gems you may need to downgrade your gem engine to version 1.8.4 whereas for newer gems upgrade to the
most current version of the gem engine).

6. Installing MySQL 5.6
Before we start: Do bear in mind that Ruby 1.87 is incompatible with MySQL versions higher than 5.0; but here is how we are going to “hack” our way:
A. Get the community version of MySQL by downloading only the installer here: http://dev.mysql.com/downloads/installer/5.6.html (1.5MB).
B. Run the installer, making sure that you skip the default and select the 32-bit architecture while making sure that you install the C Connector,
see the pic below (it is the only picture in this presentation and this, by itself, speaks volumes) :
C: Visit the archive and download the 32-bit 5.0.96 version (in zip format) from here: http://downloads.mysql.com/archives/community/
D. Extract its contents and locate the file libmysql.dll (sized 2.08 MB) and copy it to the
C:UsersYour_User_AccountRubyRuby187bin folder
E. Proceed now with installing the mysql and mysql2 gems using the instructions that include these options:
gem install mysql -v 2.8.1 -- '--with-mysql-lib=“C:Program Files (x86)MySQLMySQL Server 5.6lib“ --with-mysql-
include=“C:Program Files (x86)MySQLMySQL Server 5.6include" --with-mysql-dir=“C:Program Files (x86)MySQLMySQL
Server 5.6"„
and
gem install mysql2 -v 0.3.6 -- '--with-mysql-lib=“C:Program Files (x86)MySQLMySQL Server 5.6lib“ --with-mysql-
include=“C:Program Files (x86)MySQLMySQL Server 5.6include" --with-mysql-dir=“C:Program Files (x86)MySQLMySQL
Server 5.6"„
In the –highly unlikely- event that this fails in your kit, retry by adding the option --platform=ruby
(this option allows for the recompilation using the headers in your local system and it is known to solve a number or issues)

7. Installing Image Processors
If you are to install a ruby-enabled image processor rmagick is a likely choice.
The gem requires the following:
A. Installation of ImageMagick: Get ImageMagick-6.5.6-Q8 from here:
http://www.imagemagick.org/download/windows/legacy/ImageMagick-6.5.8-10.zip ,
unzip and run the installer.
B. Download Rmagick http://rubyforge.org/frs/?group_id=12&release_id=42049 binary,
win-32 version 2.12.0 binary gem for Ruby 1.8.6 (it is proven to work on both 1.87 and 1.92)
Unzip, confirm the ImageMagick Installation (this is the reason why we went for version
6.5.8.10 instead of the latest) by running the installer, and conclude your installation with
the gem installation (from the directory where you have extracted the gem):
gem install rmagick --version=2.12.0 --platform=ruby -- „--with-opt-
lib=“< ImageMagick-6.5.6-Q8 path>lib” --with-opt-include=“< ImageMagick-
6.5.6-Q8 path>include”‟

8. Building the Manifest
The previous steps afford us now to go ahead and proceed building the project with
confidence - albeit measured, as we are still working in an environment that has long past its
prime.
Go to the directory where the project rests and run the command:
bundler install
Please note that this command will make use of the manifests (see gemfile and gemfile.lock in
the root directory of the application) and, in cases, some gems will fail or will need attention
simply because they were never meant to be supported on the Windows platform.
Examples of this kind include the eventmachine or activerecord that earlier versions were either
unsupported on Windows and/or later versions have become part of rails higher than v3. In this
case you will have to edit the manifest with the versions that you can install.
For example, in our case our original manifest was asking for eventmachine "0.12.0“ but that
was impossible to be installed because it was never meant to be available in Windows. So we
proceeded by installing eventmachine “1.0.3 ruby x86-mingw32” and changed the manifest
accordingly and the bundler worked fine!

9. Development Tools (Sapphire & Ruby Mine)
Two are the tools that I wholeheartedly recommend:
 A. Sapphire: Great effort by Huw Collingbourne and his team, that allows for Ruby
development within Visual Studio. All three latest VS versions (2010/2012/2013) are
supported (though in the 2013 that I worked is on pre-release and had with a few issues
that were discovered and communicated to Huw; their fixing is work in progress). Note,
also that Huw has written a great book on Ruby and has also E-Courses for Ruby
beginners in Udemy (here is his profile: https://www.udemy.com/blog/meet-your-
instructors-huw-collingbourne/) .
You can get Sapphire here: http://sapphiresteel.com/ but to visit the forums for access
to the pre-release VS 2013 compatible version.
 B. RubyMine 6: Great, extremely intuitive tool with a superbly customisable editor. I am
using it until Sapphire 3 gets launched. The academic licence costs less than £25 and I
consider getting it; the tool is worth hundreds of pounds.
You can download it from here: http://www.jetbrains.com/ruby/download/

10. Side-by-Side Ruby Installations
Now that you are up and running you may consider upgrading your Ruby to a more recent
version. Have no fear… you can install any version you like and also install pik
(https://github.com/vertiginous/pik)
And you can add and switch between the various versions using command like:
pik add C:UsersYour_User_AccountRubyRuby<Any_Version_You_Like>bin
In order to check what is available, run :
pik list
While in order to switch, run:
pik switch <Any_Version_You_Like>
While you may return to your 187 using:
pik switch 187

11. Conclusions
I hope that in this relatively brief presentation I covered most of the issues that are bound to
cause problems and conflicts – particularly while dealing with MySQL and the compilers.
For example, in my kit I have Cygwin (in order to use my Windows to communicate with a
supercomputer) and to my surprise I realised that the Cygwin gcc compiler and bash were
causing issues. So I had to uninstall it and re-install it after the completion of the installation.
Please follow all the advice given and you wont regret it. This year I am celebrating my 33rd
anniversary of being involved with computing and I have to admit that I struggled enough to
make it work. Actually, if it wasn’t for an extremely intriguing project by a very dear friend of
mine, I would have never involved myself with Ruby on Rails and especially on Windows. But I
am sure, that there are cases when colleagues have to do these migrations and I wouldn’t wish
them going through my experiences; not even to my worst enemy! 
I hope I made it extremely simple. Ideally, a junior IT person (i.e. someone without any
programming knowledge, never mind of Ruby on Rails) should be able to proceed with the
migration successfully.

12. Acknowledgements
I would like to thank the following individuals:
 Ilesh Kotecha, my colleague at the Department of Computer Science at the University of Oxford who
entrusted me with his extremely interesting endeavour; his vision of adaptive tests to measure IQ and
aptitude of individuals, most definitely managed to test mine during this migration! :)
 Balaji Raghavan, Ruby on Rails veteran/expert who helped me along the way as I was struggling with
various issues.
 Huw Collingbourne, creator of Sapphire and leading author on Ruby on Rails, for his immediate attention
to my requests for assistance and help.
Finally, as always, many thanks to all my flatmates, friends and colleagues at Exeter College Oxford
who tolerate my existence inclusive of heavy smoking and drinking coffee late at nightearly in the
morning.
Dominus Illuminatio Mea!