Ruby on Rails Windows Troubleshooting Tips & Survival Guide
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),
Devkit that are specially configured to make popular gems compatible with Windows.
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.0with 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.
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.
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).
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
Using Windows Command Line & its Ruby Oddities
When Using Rails in Console/Command Line (cmd.exe):
- 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 execin front.. so instead of typing
rake db:create, type ~>
bundle exec rake db:createYou can never go wrong doing this, even if its annoying. (That is unless
Weird Printouts in IRB
- 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
- 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:
|Select and go to folder||C:\RailsInstaller||~>
|Go back one folder||C:\RailsInstaller\Ruby1.9.3||~>
|List files/folders in current directory||C:\RailsInstaller||~>
||Lists files/folders: Devkit Git Ruby1.9.3 ...|
|Go back to c:/ root directory||C:\RailsInstaller\Ruby.1.9.3||~>
|create new folder||*C:*||~>
|Auto-find folder/file name while typing||~>
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
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).
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
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.
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\Ruby1.9.3\DevKit\bin;to the end, making sure you separate each item with a semi-colon(
;) and no spaces.
When finished, the Variable Value for Path will look something like this: ...
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.
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
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.
Inside Environment Variables, you will see a section called Path (under System Variables). Select Path then click edit.
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: ...
To test: restart your command line (e.g. cmd.exe) and cd to C:\RailsInstaller\Ruby1.9.3. If ~>
cd my_appgoes to your app's folder, then instead you can type ~>
sublime_text my_appto open the entire
my_appproject folder within Sublime for editing. Alternatively, if you are inside
my_appalready (e.g. C:\RailsInstaller\Ruby1.9.3\my_app ) you can get the same result by typing ~>
This is one method to set up your shortcut. For further reading: http://stackoverflow.com/questions/9440639/sublime-text-from-command-line-win7
Heroku SSH Keys:
- 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.
- 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: :developmentto 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-datagem 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
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
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.
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.
therubyracer gem has with the
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.
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:
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
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