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.

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

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.

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

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:\Users\Your_User_Account\Ruby 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:\Users\Your_User_Account\Ruby\Ruby187& C:\Users\Your_User_Account\Ruby\Devkit

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:\Users\Your_User_Account\Ruby\Devkit\ruby dk.rb init <press enter> C:\Users\Your_User_Account\Ruby\Devkit\ruby dk.rb install

F. Downgrade your version of gem engine! EXTREMELY IMPORTANT by issuing the command: C:\Users\Your_User_Account\Ruby\Ruby187\gem upgrade --system 1.8.7

G. Install the Rails of your choice using the command: C:\Users\Your_User_Account\Ruby\Ruby187\gem 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).

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:\Users\Your_User_Account\Ruby\Ruby187\bin 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)\MySQL\MySQL Server 5.6\lib“ --with-mysql-include=“C:\Program Files (x86)\MySQL\MySQL Server 5.6\include" --with-mysql-dir=“C:\Program Files (x86)\MySQL\MySQL Server 5.6"‘andgem install mysql2 -v 0.3.6 -- '--with-mysql-lib=“C:\Program Files (x86)\MySQL\MySQL Server 5.6\lib“ --with-mysql-include=“C:\Program Files (x86)\MySQL\MySQL Server 5.6\include" --with-mysql-dir=“C:\Program Files (x86)\MySQL\MySQL 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)

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”’

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!

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/

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:\Users\Your_User_Account\Ruby\Ruby<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

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.

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 night\early in the morning.

Dominus Illuminatio Mea!