Ruby on Rails Microsoft Windows Troubleshooting Tips

ruby_rails_windows.md

Ruby on Rails Windows Troubleshooting Tips & Survival Guide

Intro/Overview

The Ruby on Rails Windows Troubleshooting tips & Survival Guide is a random catalogue of issues I faced working with Ruby on Rails on Windows (Windows 7 specifically). This guide is not exhaustive, but covers many of the challenges that causes Windows Ruby developers to jump ship to Linux or Mac. If you're reading this guide then you're probably new to Ruby/Rails, so also included is more general beginner advice to help you get going.

Personal Side Note

Before you follow this guide, I strongly recommend you consider using Linux or Mac OS X for Ruby Development instead. Looking to prove a point as a challenge, I ignored this strongly given advice while learning Ruby/Rails. While I eventually did succeed in getting Ruby on Rails to work in Windows, it was not easy, and I easily lost 40+ hours on StackOverFlow to Windows/Ruby configuration issues--time I could have devoted to learning more about the Ruby language, its frameworks, and its gems. To save other Windows users from a similar headache, and in the hopes of making Windows someday viable for Ruby development, I created this guide to document my struggles.

If you would like to help expand this guide, or fix incorrect content, feel free to contact me at kelseyh(AT)gmail(DOT)com.

Getting Started on Windows

IMPORTANT NOTE: If you need to switch easily between Ruby versions on Windows, a popular option was Pik instead of RailsInstaller. However Pik's Github activity is now dead and the maintainers have abandoned the project. https://github.com/vertiginous/pik The maintainers now recommend Uru as a promising replacement: https://bitbucket.org/jonforums/uru/

IMPORTANT NOTE 2: The information about Ruby versions here is out of date. For latest updates on versions, visit the Railsinstaller website: http://railsinstaller.org/en

Step 1: Install Ruby AND Rails Together With RailsInstaller

You can avoid many problems if you install both Ruby + Rails onto Windows together. When I started Ruby development, many of my problems emerged from installing the latest windows version of Ruby 2.0+, and trying to get this separate installed version of Ruby to work with a separately installed version of Rails.

Fortunately, Windows users can now rely on RailsInstaller to take care of compatibility problems. RailsInstaller comes with a custom version of Ruby1.9.3 (the Ruby2.0.0 is currently in alpha), bundler & Devkit that are specially configured to make popular gems compatible with Windows.

1. To avoid problems, if you have previous Ruby versions installed already, uninstall other versions of Ruby (e.g. Ruby2.0.0 if not packaged with RailsInstaller). You can typically achieve this by deleting a folder named Ruby 2.0.0 with the Ruby version number. If you would like to keep multiple versions of Ruby, check the important note below before going through with these step. Deletion is recommended to avoid multiple ruby versions, gems, bundler and rake versions conflicting with one another, a common problem faced by beginners who install Ruby separately before installing Rails.

2. Download and Install RailsInstaller (http://railsinstaller.org/en). Install to a file location such as c:/RailsInstaller, importantly for whatever file path is chosen, make sure there are no spaces between any of the letters/words.

3. If you now check the RailsInstaller folder (e.g. c:/RailsInstaller), you will find the folder contains a custom installation of Ruby 1.9.3 (e.g. c:/RailsInstaller/Ruby1.9.3) and the Ruby Devkit (e.g. c:/RailsInstaller/Devkit). Make note of this, and make sure that the relevant sections of this folder were added to your Path (see the section on adding files to your path for details).

4. It's easiest to have all Rails projects stored inside the RailsInstaller folder, or within the folder of your default PATH. However, if you choose to store your Rails projects in a separate folder like c:/Websites, then be aware that issues involving your PATH may arise when you execute commands from the console.

Step 2: Install Cygwin to get access to Unix commands in your shell

Visit: http://cygwin.com/

Using Windows Command Line & its Ruby Oddities

When Using Rails in Console/Command Line (cmd.exe):

1. RailsInstaller bundles many of the production/development gems for you. To ensure the proper gem dependencies are provided for, replace rake actions such as rake db:migrate, with bundle exec in front.. so instead of typing rake db:create, type ~> bundle exec rake db:create You can never go wrong doing this, even if its annoying. (That is unless bundler is broken...)

Weird Printouts in IRB

1. In ruby console, you will often see printouts that look like "[1m [5m" surrounding your data. This is caused by gems that attempt to add nice colours to highlight console commands using ANSI character sets not supported natively in windows. You can either go into your gems to disable this, or better, install Ansicon, which allows you to enjoy the nice colours by handling the ANSI conversion for your command line. Here is a useful installer: https://github.com/mcandre/ansicon-win Take note of that there is a x64(64 bit) and x86 (32 bit) version, I'm running the 32 bit version to great success, but issues exist regarding which to install, so YMMV.

Navigating Console/Command Line in Windows

2. Navigation: Console navigation is a little different in Windows due to differences in file structure relative to Unix-based systems like Mac OS X and Linux. It's important to remember these difference when writing scripts that navigate local file structures. Useful commands:

Action	Before	Console Command	After
Select and go to folder	C:\RailsInstaller	~>cd Ruby1.9.3	C:\RailsInstaller\Ruby1.9.3
Go back one folder	C:\RailsInstaller\Ruby1.9.3	~>cd ..	*C:\Railsinstaller*
List files/folders in current directory	C:\RailsInstaller	~>dir	Lists files/folders: Devkit Git Ruby1.9.3 ...
Go back to c:/ root directory	C:\RailsInstaller\Ruby.1.9.3	~>cd /.	*C:*
create new folder	*C:*	~>mkdir NewFolder	Creates C:\NewFolder
Auto-find folder/file name while typing	~>cd m	press TAB	~>cd my_app

Navigating your PATH in Windows

Many Windows/Ruby problems are caused by not having the proper program or dependencies configured within your path. If a Ruby, Rails, Bundler, Rake or an installed gem command within console (cmd.exe) is raising a not found type error, then you may have an issue with your Path. Adding a file to your Path will allow that program to be found and executed within Console/Command Line. Once a file directory is added to your Path, all files added to that folder and its subfolders will be executable from the command line.

Here's how to add a program folder to your Path if it's not added by default (be careful with this).

1. In Windows 7, click the Windows Icon and search for System. Inside System go to Advanced System Properties. Under the advanced tab, click & open Environment Variables

2. Inside Environment Variables, under both User Variables and System Variables you will see variable section called Path. Your choice depends on whether you want your changes to affect the computer globally or your local user account. In our case let's go with User Variables, and under that section select Path, then click edit.

3. Within the window Edit User Variable, under Variable Value you will see a long list of directories to folder, separated by a ; To add a folder to your Path, simply add the directions to that folder separated by a ;. E.g. if your folder was for Rails via RailsInstaller, then we would need to add three directories: C:\RailsInstaller\Git\cmd; , C:\RailsInstaller\Ruby1.9.3\bin; & C:\RailsInstaller\Ruby1.9.3\DevKit\bin; to the end, making sure you separate each item with a semi-colon(;) and no spaces.

4. When finished, the Variable Value for Path will look something like this: ...C:\Program Files\nodejs\;C:\RailsInstaller\Git\cmd;C:\RailsInstaller\Ruby1.9.3\bin;C:\RailsInstaller\Ruby1.9.3\DevKit\bin;

Windows Debug Tip: A common problem in Windows, especially if you install multiple Ruby versions with different installed bases of gems--is to have Ruby/Rails components from different versions mish-mashing together unbeknownst to the developer who innocently installed multiple versions. This can continue unnoticed for a long time until a weird behaviour happens after trying something like a spec test (e.g. you find Rake can access the gem but Bundle does not). Understanding how & where the Command Line makes calls from files via your PATH is critical to solving these issues if they arise for you or somebody you know.

Open Sublime Text from the Command Line:

To open Sublime from your console, you need to add it to your path.

1. In Windows 7, click the Windows Icon and search for System. Inside System go to Advanced System Properties. Under the advanced tab, click & open Environment Variables

2. Inside Environment Variables, click NEW under System Variables. Under Variable Name type SUBLIME_HOME. Under Variable Value add C:\Program Files\Sublime Text 2\, or an alternative path of where you installed Sublime Text. Click Ok.

3. Inside Environment Variables, you will see a section called Path (under System Variables). Select Path then click edit.

4. In Path, add %SUBLIME_HOME% to the end, making sure there is a ; to separate it from the last item. E.g. similar to this: ...C:\Program Files\nodejs\;%SUBLIME_HOME%

5. To test: restart your command line (e.g. cmd.exe) and cd to C:\RailsInstaller\Ruby1.9.3. If ~>cd my_app goes to your app's folder, then instead you can type ~>sublime_text my_app to open the entire my_app project folder within Sublime for editing. Alternatively, if you are inside my_app already (e.g. C:\RailsInstaller\Ruby1.9.3\my_app ) you can get the same result by typing ~> sublime_text .

This is one method to set up your shortcut. For further reading: http://stackoverflow.com/questions/9440639/sublime-text-from-command-line-win7

Deployment

Heroku SSH Keys:

1. Windows users when deploying to Heroku need to exchange SSH keys. The answer is not clear, but there can be complications with this. Windows users need to use PuttyGen to generate an SSH keys. Be careful about how you format your files. I recommend only have one key pair, mine are titled: id_rsa.pub which solved the problem for me... you may not be so lucky.

Ruby Versions & Cloned Projects

Gem compatibility with Mac and Linux Environments

On windows you will encounter group projects not compatible with Windows. You can specify the gem differences by segregating problem gems and changes to specific platforms within your Gemfile:

platforms :ruby do # linux/Mac
  #gems specific to linux/Mac OS X
end

platforms :mswin do
  # gems specific to windows
end

Ruby 2.0 Version Issues when using RailsInstaller w/ Ruby 1.9.3

The latest RailsInstaller Ruby version is Ruby 1.9.3, but Ruby is now past version 2.0 You may run into problems when doing production on a newer version of Ruby.

1. If you are pulling a Git repo of a Rails project that uses a Ruby version of 2.0 or higher, add gem 'tzinfo-data', group: :development to your Gemfile. This will solve your compatibility issues locally, and should not negatively affect your Apple co-workers. Note that when you create a Rails project with RailsInstaller, tzinfo-data gem is already added in for you -- the problem comes when you pull from other Rails projects on Git that haven't added it.

Note: RailsInstaller with Ruby2.0.0 is now in Alpha, so by the time you read this it may be out of date.

Database Set up

PostGreSQL Issues:

This one is a headache. To deploy a database-driven Rails or Sinatra app to Heroku, you will need to replace SQLite3 with a remote relational database -- a popular option being PostgreSQL. Unfortunately for Windows users, setting up PostgreSQL can be quite an ordeal. The best writeup on this is here: http://stackoverflow.com/questions/7086654/installing-postgres-on-windows-for-use-with-ruby-on-rails But in short, to get PostGreSQL to work on windows you need to install PostGreSQL, particularly PGAdmin, and run it (since it acts like a remote server) to ensure your app's data properties in development work.

If you successfully installed PostGreSQL in Windows, to have PostGreSQL work in local development, create a user account in your Windows PostGreSQL PGAdmin program and make sure its database status is connected. Inside your Rails project within the config database.yml file, remove all mention of SQLite3 if referenced, and replace instead with login credentials that match your PGAdmin user account. e.g. looking something like this (only the development and test database configurations matter for our local machine):

development:
  adapter: postgresql
  encoding: unicode
  database: db/development
  username: ADD_USER_NAME
  password: ADD_PASSSWORD
  pool: 5
  timeout: 5000

test:
  adapter: postgresql
  encoding: unicode
  database: db/test
  username: ADD_USER_NAME
  password: ADD_PASSSWORD
  pool: 5
  timeout: 5000

It's a good idea to add the database.yml file to your .gitignore, given it contains sensitive login credentials. It's a good practice to include a database.yml.example file instead so that those who clone your project can set up their own database configuration with their own credentials, and then rename this file to database.yml to use for their own use.

Also make sure that you specify PostGreSQL by adding gem 'pg' and removing gem 'sqlite3' (if its referenced) from your Gemfile. Then run bundle install.

MySQL:

If you succeed in getting PostgreSQL to work, then MySQL installation on Windows is relatively straight forward if you download and install MySQL using the auto-installer ( https://dev.mysql.com/downloads/installer/ ), rather than try to manually install it yourself. Go to Oracle's site, register for a free account and download/install the latest version of MySQL. Make sure you have the Ruby connector installed with your installation. Within the MySQL workbench program, you can configure a root entry account and user accounts with logins.

The rest follows as you would do in Linux or Mac OS X: To add MySQL to a Rails project, add gem 'mysql2' to your Gemfile and then run bundle install. You will need to need to configure your database.yml file to include your database username and password, credentials which should match the credentials you entered within the MySQL WorkBench program you set up. It is then strongly advisable that you add the database.yml file to your .gitignore, since it contains your password.

For further reading: https://stackoverflow.com/questions/15613646/how-can-i-connect-to-mysql-in-ruby-on-rails

Memcache/Memcached

Among all the problems facing Windows Ruby users, install Memcache proved to be the only one I could never could get to work. Memcache as a caching tool is written heavily in C-extensions, with Window ports being hard to come by. Hacky solutions relying on outdated Memcache versions exist exist, but I could not get them to work. (If any one reading this figures out how to install Memcached to Windows, let me know and I will add it to this guide.)

Gems that Hate Windows

In theory Ruby gems work with Windows. Then you realize that many of them have major portions of their source code written in native C extensions. A lack of compatibility at this layer is a source of (most) if not all of Window's Ruby compatibility problems.

RubyRacer Gem

TheRubyRacer gem will cause problems in Windows, due to a Javascript engine dependency that the therubyracer gem has with the libv8 gem. Workarounds exist, but they are unreliable and technically confusing at best. A popular solution is to just ditch RubyRacer and install Node.js instead (http://nodejs.org/) to achieve the Javascript support that therubyracer would provide within the local windows machine development environment.

If you work on a project with Max/Linux developers relying on the therubyracer gem, you can avoid a breaking conflict by safely changing the Gemfile reference to gem 'therubyracer', :platform => :ruby. This will ensure therubyracer gem is only installed on linux and OSX, and not Windows. Everybody wins.

For more indepth information on therubyracer & Windows: https://stackoverflow.com/questions/6356450/therubyracer-gem-on-windows

ImageMagick and RMagick Gem

This one can be a bit tricky. The easiest solution I have found on this is here: http://www.redmine.org/projects/redmine/wiki/HowTo_install_rmagick_gem_on_Windows The installation involves carefully installing the right version of ImageMagick, correcting your path to include ImageMagick, and then installing the RMagick gem. For further reading: https://stackoverflow.com/questions/4451213/ruby-1-9-2-how-to-install-rmagick-on-windows

Twitter API Gem SSL Key

When using the Twitter API gem(https://sferik.github.io/twitter/) to access Twitter accounts you gained permissions to, you may encounter an error that mentions ssl_connect returned = 0... This is caused by not having the file cacert.ppm available for Twitter's API.

Solution To solve this, go to http://curl.haxx.se/ca/cacert.pem and save that page as the file cacert.pem somewhere within your path close to your Ruby development environment. E.g. C:\RailsInstaller\Ruby193\cacert.pem. Then in your console type SET SSL_CERT_FILE= + the path to that cacert.pem file, e.g. in my example the command would look like: SET SSL_CERT_FILE=c:\RailsInstaller\ruby193\cacert.ppm

To Test the solution: Assuming you already have permissions to Twitter accounts via Twitter's API on your webpage, then to test that you have fixed the SSL issue: open a new console/command line, type gem install 'twitter' if you haven't installed the gem already. Once that is finished installing from the console, open up IRB and type require 'twitter' then hit enter. Next, to test calling Twitter's API with a client key you fetched from a user json's tokens, paste the following into a text editor:

client = Twitter::REST::Client.new do |config|
  config.consumer_key        = "YOUR_CONSUMER_KEY"
  config.consumer_secret     = "YOUR_CONSUMER_SECRET"
  config.access_token        = "YOUR_ACCESS_TOKEN"
  config.access_token_secret = "YOUR_ACCESS_SECRET"
end

Fill in all four token/key fields with the applicable access keys based on the JSON printout of the user's Twitter API log in to your site, paste the above code filled in properly into your IRB console, and hit enter. You should now have access via Twitter's API to user's who signed up to your site via Twitter!

File differences between Mac/Unix and Windows

Folder and Directory Structure (Path Separators)

Windows tends to have different path separators from the rest of the world, Therefore, it is recommended that you use File.join to build up your paths so that they are relative. For example:

home = Dir.home
File.join(home, ".ssh") #=> /root/.ssh or C:/Users/MyUser/.ssh depending on the platform.

When writing code to navigate around the file system, hardcoding the path will make your code incompatible with either Linux, OS X, or Windows. For example:

ssh_folder = "/root/.ssh" #=> Doesn't work on windows.
ssh_folder = "C:/Users/MyUser/.ssh" #=> Doesn't work on linux or OS X.

For more information on navigating the local file system in Ruby: https://richonrails.com/articles/basic-file-and-directory-operations-in-ruby

Tar.gz files:

Unix/Max environments often pack files for program together in tar.gz files which you can unpack to manually install them with.

If you have MinGW/MSYS or Cygwin installed, you can use the tar command to unpack such files in Console:

~>tar xvf for a .tar file

~>tar xzvf for a .tar.gz file

~>tar xjvf for a .tar.bz2 file

You can also use 7-zip.

To learn more about this check: http://www.haskell.org/haskellwiki/How_to_unpack_a_tar_file_in_windows

Beautiful post; thank you for presenting, in "Gems that Hate Windows," a concrete reason to use the linux subsystem instead of just installing everything directly onto windows. All the other resources I found were a bit vague about the reasons, this is something I can bring to my team. 👍