installing rails
Last updated 29 April 2012
Installing Rails 3.2.3: Detailed (and current) instructions on how to install the latest release of Rails 3.2 with advice and troubleshooting tips.
This is a guide for developers using the starter apps from the Rails Apps repository. Others may find it helpful as well.
See a list of recommended resources for Rails if you are just getting started.
You can read more about how the building blocks of the Rails platform work together by reading the article Managing Rails Versions and Gems. It explains the relationships among Ruby, RubyGems, Rails, Rake, Bundler, and gemfiles and offers some advice.
Rails 3.2.3 was released March 31, 2012 with improved protection from mass assignment vulnerabilities (see the Rails 3.2.3 Announcement and an explanation by Michael Hartl). Rails 3.2.2 was released March 1, 2012 with some minor bug fixes plus two important security fixes (see the Rails 3.2.2 Announcement). Rails 3.2.1 was released January 26, 2012 with some minor fixes (see Ruby on Rails v3.2.1 Changelogs).
Rails 3.2 was released January 20, 2012. Improvements include faster execution in development mode. The speed of resolving routes also improved. There are many tiny (but helpful) improvements throughout the framework. Rails 3.2 deprecates plugins (Rails 4.0 will remove them completely) so find Ruby gems to replace any plugins you may still be using. You can use Ruby 1.8.7 but consider moving to Ruby 1.9.3 (the current stable and recommended Ruby version) because Rails 4.0 will require Ruby 1.9.3. See the Rails 3.2.0 Announcement and Ruby on Rails 3.2 Release Notes (with upgrade instructions). There’s a Railscast from Ryan Bates titiled Upgrading to Rails 3.2. Michael Hartl’s popular Ruby on Rails Tutorial book has been rewritten to cover Rails 3.2 with improved treatment of RSpec and Cucumber (Ruby on Rails Tutorial Version 3.2). Finally, José Valim highlights his Five Favorite ‘Hidden’ features in Rails 3.2.
What You Need to Know: Upgrading from Rails 3.1 to Rails 3.2 is easy and yields faster performance (especially in development mode). You may run into issues if your application has routing complexities (the routing engine has changed). For an older application, upgrade to Rails 3.1 before upgrading to Rails 3.2.
Rails 3.1.0 was released August 31, 2011. Eight release candidates were released beginning May 21, 2011. Rails 3.1 introduced the asset pipeline which enables proper organization of CSS and JavaScript. Other features include HTTP streaming, default jQuery, reversible migrations, mountable engines, identity map, prepared statements, Rack::Cache on by default, forced SSL, role-based mass-assignment protection, has_secure_password, and custom serializers. See the Rails 3.1 release candidate announcement for details. There’s a Rails 3.1 Overview from Ryan Bates and a changelog for all the details. Yehuda Katz explains What’s Up With All These Changes in Rails?. The best overview of Rails 3.1 is Michael Hartl’s chapter on Rails 3.1 in his Ruby on Rails Tutorial book.
What You Need to Know: The greatest impact for developers moving from Rails 3.0 to 3.1 is the new location for CSS and JavaScript files and changes to the application layout file. See the official Rails 3.1 Asset Pipeline guide for details.
RubyGems is a package management framework for Ruby. RubyGems installs as part of Ruby 1.9.3.
RubyGems 1.8.24 was released April 27, 2012 and increased the security used when RubyGems is talking to an https server (from the RailsApps blog: RubyGems 1.8.24 Is Out).
If you think a gem may be failing because of an incompatibility with the newest RubyGems implementation, you can troubleshoot by rolling back to an earlier RubyGems system gem with gem update --system 1.7.2 or gem update --system 1.3.7.
What You Need to Know: Use gem update --system to upgrade to the newest RubyGems system gem.
Rake is the build tool for Ruby. Rake version 0.9.2 was released on June 5, 2011 and followed by Rake version 0.9.2.2 on October 22, 2011. Rake 0.9.2.2 installs as part of Ruby 1.9.3.
Many gems depend on Rake and conflicting dependencies can be a problem, especially since the release of Rake version 0.9.0 (May 20, 2011). For an explanation, see David Chelimsky’s blog post. If needed, you can specify an earlier version of Rake in your gemfile to force the use of an earlier Rake version.
You may may heard that it is good practice to use the command bundle exec rake instead of rake to force use of executables specified in your gemfile (or a dependency specified in the Gemfile.lock file) instead of other versions. For example, instead of rake db:migrate, run bundle exec rake db:migrate. If you’re using rvm, the Ruby Version Manager, as recommended below, you don’t need to use bundle exec rake instead of rake (rvm versions 1.11.0 and newer include the rubygems-bundler gem to handle this).
What You Need to Know: Make sure you are using Rake 0.9.2.2 (or newer) with gem update rake before installing Rails 3.2.
Bundler version 1.1.3 was released March 24, 2012. Version 1.1.0 released March 7, 2012 is significantly faster than previous versions.
What You Need to Know: Use gem update bundler to upgrade to the newest Bundler gem.
Follow these instructions to set up Rails 3.2 as a platform for the Rails example apps or any other apps you may build.
Recommended: You should use rvm, the Ruby Version Manager, to create a new gemset and install the new Rails version. Then you can switch between versions if necessary.
Not recommended: If you have an older version of Rails installed, it is possible to run gem update rails to get the newest version of Rails. But it is well worth the effort to install and use rvm to manage Rails versions.
You need a C language compiler to install Ruby and any gems that require native extensions. Linux operating systems include the necessary gcc compiler. Default installations of Windows or Mac OS X don’t include gcc.
The best guide is from Moncef Belyamani: How to Install Xcode, Homebrew, Git, RVM, & Ruby 1.9.3 on Snow Leopard & Lion.
If you’d like the process to be easier, contribute to Yehuda Katz’s Rails.app Kickstarter project to improve the Mac OS X install experience.
To install Ruby 1.9.3 on Ubuntu Linux, there are several useful guides:
- Installing Rails on Ubuntu from Railsbridge Installfest
- Mircea Goia’s tutorial
- Joshua Frye’s Rails Ready setup script
- Ryan Bigg’s tutorial
- Peter Cooper’s screencast
Note: You can develop with Rails on Windows but be aware that most developers use Mac OS X or Ubuntu to develop Rails applications. Some gems requiring native extensions may be difficult to install on Windows. Developers (including The Code Shop) are working to improve the speed of Ruby 1.9.3 on Windows (see a benchmark) as earlier versions were frustratingly slow.
To prepare Windows for installation of Ruby 1.9.3, start with RailsInstaller from Engine Yard. RailsInstaller includes a “DevKit” which installs Ruby 1.9.3 and Rails 3.2 as well as gcc and other Unix build tools. See a guide to Installing Rails on Windows from Railsbridge Installfest for step-by-step instructions. On Windows, use Pik for services similar to rvm.
Another option on Windows is to install Ruby under Cygwin. This gives you a Linux environment on Windows. Make sure you have the following Cygwin packages installed: git, readline, wget, patch, make, gcc, libsqlite3-devel, libxml2-devel, libxslt-devel. Then install RVM as described in the next section.
You should install Ruby 1.9.3 on your computer using Wayne Seguin’s rvm, the Ruby Version Manager.
You’ll use rvm to manage your Rails versions and create a gemset specifically for each application you build. If you encounter conflicting gem dependencies, you can isolate the errors by creating different gemsets with rvm.
Sam Stephenson offers an alternative to rvm named rbenv. With rbenv, use Jamis Buck’s rbenv-gemset to switch between gemsets. The utilities rbenv and rbenv-gemset are less “magic” than rvm and can be useful if you encounter issues with rvm. If you want to try rbenv, see notes for installing Ruby on MacOS X 10.7.3 with XCode 4.3 and rbenv.
Most Rails developers use and recommend rvm.
The rvm website explains how to install rvm.
If you have an older version of Ruby installed you don’t need to remove it. Any older Ruby and Rails versions will remain on your system and the rvm versions will take precedence. Rvm will leave your system version of Ruby untouched and use your shell to intercept any calls to Ruby.
If you already have rvm installed, update it to the latest version.
$ rvm get latest $ rvm reload $ rvm -v
Check for the current recommended version of Ruby. Ruby 1.9.3 patch level 194 was current when this was written. There are other Ruby interpreters (REE from Phusion, JRuby, Rubinius, MagLev, and MacRuby) but Ruby 1.9.3 is your best choice for most Rails application development.
Ruby may already be installed on your computer (Mac OS X 10.7 comes with Ruby 1.8.7 preinstalled). You don’t need to remove an earlier version of Ruby if you install Ruby 1.9.3 using rvm.
Check for rvm installation notes for your operating system version:
$ rvm requirements
Use rvm to install the recommended version of Ruby and make it your default:
$ rvm install ruby-1.9.3-p194 $ rvm --default use ruby-1.9.3-p194 $ ruby -v
Note: On a Mac with OSX 10.7.3 and XCode 4.3.1 you should be able to install Ruby 1.9.3-p194 using rvm without any special command line options. Installing Ruby 1.9.3-p194 on Mac OS X 10.7.3 with Xcode 4.2.1 requires the following command line switch to succeed: rvm install 1.9.3-p194 --with-gcc=clang because XCode 4.2 doesn’t use the standard gcc compiler. If you encounter this issue, you can also use Kenneth Reitz’s OSX GCC Installer to install the gcc compiler.
The RubyGems package management system comes as part of a standard Ruby language installation.
What version of the RubyGems system is installed on your machine? Check with:
$ gem -v
Check for the newest version of RubyGems. It should be version 1.8.24 or newer.
Use gem update --system to upgrade the RubyGems system.
See the article Managing Rails Versions and Gems if you have problems with gem incompatibilities.
See what gems are installed by running gem list.
Only two gems are installed with Ruby 1.9.3:
- bundler
- rake
Rvm installs two additional gems:
- rubygems-bundler
- rvm
Ruby 1.9.3 includes Rake version 0.9.2.2. Rake version 0.9.2.2 was current when this was written.
Update to the newest version of Rake before you install Rails 3.2.
$ gem update rake $ rake --version
Create a default Rails 3.2 gemset. It’s advisable to create a new gemset for each application you build. But to get started, create just one new Rails 3.2 gemset as your default.
$ rvm ruby-1.9.3-p194 @rails32 --create --default
To see a list of the gemsets you have installed:
$ rvm gemset list
Bundler version 1.1.3 was released March 24, 2012. Version 1.1.0 released March 7, 2012 is significantly faster than previous versions.
Update to the newest version of Bundler before you install Rails 3.2.
$ gem update bundler $ bundle --version
Now you can install Rails 3.2.3.
Check for the current version of Rails.
If you want the most recent stable release:
$ gem install rails $ rails -v
If you want the newest beta version or release candidate, you can install with --pre.
$ gem install rails --pre $ rails -v
Or, as an alternative to --pre, for the newest version:
$ gem install rails -v ">=3.2.3" $ rails -v
Or you can get a specific version (just in case the newest version is broken).
For example, if you want the Rails 3.2.0 release, install with --version=3.2.0.
Since Rails 3.1, a JavaScript runtime has been needed for development on Ubuntu Linux. It is not needed for Mac OS X or Windows.
For development on Linux Ubuntu, it is best to install the Node.js server-side JavaScript environment:
sudo apt-get install nodejs
and set it in your $PATH.
If you don’t install Node.js, you’ll need to add this to the Gemfile for each Rails application you build:
gem 'therubyracer'
You can create a test application:
$ rails new testapp
Switch to the application root directory to examine and test what you’ve built.
$ cd testapp
For a “smoke test” to see if everything runs, display a list of Rake tasks.
$ rake -T
There’s no need to run bundle exec rake instead of rake when you are using rvm (see rvm and bundler integration).
The newest Ruby and RubyGems versions (starting with Ruby 1.9.3p194 and RubyGems 1.8.23) require verification of server SSL certificates when Ruby makes an Internet connection via https. If you run rails new and get an error “Gem::RemoteFetcher::FetchError: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate” see this article suggesting solutions: OpenSSL errors and Rails.
Are you getting an error “OpenSSL certificate verify failed” when you try to generate a new Rails app from an application template? See this article suggesting solutions: OpenSSL errors and Rails.
If you see:
The template ... could not be loaded. Error: You have already activated rake 0.8.7, but your Gemfile requires rake 0.9.x. Consider using bundle exec.
If you are using Ruby 1.9.2, you must update the standard Ruby installation from Rake 0.8.7 to Rake 0.9.2 (or newer) before using the application templates to generate a new Rails app. It’s advisable to update to Ruby 1.9.3 which will provide Rake 0.9.2.
See a list of recommended resources for Rails if you’re just getting started.
- Recommended Resources for Rails
- Example Gemfiles for Rails 3.2
- Using Git with Rails
- Rails Default Application Layout for HTML5
The starter apps from the Rails Apps repository provide good examples of Rails apps.
Plus, by using one of these starter apps, you can minimize the effort needed to stay current with changing Rails and gem versions.
Each app provides a set of useful, popular Rails gems integrated into a working application. Each example is known to work and can serve as your personal “reference implementation”. Each is an open source project. Dozens of developers use the apps, report problems as they arise, and propose solutions as GitHub issues. There is a tutorial for each one so there’s no mystery code.
| Author | Starter App | Tutorial | App Template | Comments |
|---|---|---|---|---|
| Daniel Kehoe | Devise, RSpec, Cucumber | Tutorial | App Template | Uses Devise for authentication with ActiveRecord and SQLite for a database |
| Daniel Kehoe | Twitter Bootstrap, Devise, CanCan | Tutorial | App Template | Devise for authentication, CanCan for authorization, Twitter Bootstrap for CSS |
| Daniel Kehoe | Startup Prelaunch Signup | Tutorial | App Template | For a startup prelaunch signup site |
| Daniel Kehoe | Devise, Mongoid | Tutorial | App Template | Uses Devise for authentication with a MongoDB datastore |
| Daniel Kehoe | OmniAuth, Mongoid | Tutorial | App Template | OmniAuth for authentication with a MongoDB datastore |
| Daniel Kehoe | Subdomains, Devise, Mongoid | Tutorial | App Template | Basecamp-style subdomains with Devise and MongoDB |
These starter apps were created with the Rails Apps Composer gem.
You can use the files in the Rails Application Templates repository to build the starter apps.
Use the "rails new myapp -m" command to generate a Rails web application from a template.
You can add the -T flags to skip Test::Unit if you are using RSpec.
You can add the -O flags to skip Active Record if you are using a NoSQL datastore such as MongoDB.
See the README or tutorial to learn how to install, configure and run the starter application.
After you’ve created an rvm gemset that you’ll use for a project and begun to build the app, you can create an .rvmrc file in the application’s root directory. RVM recgonizes an .rvmrc file in a directory and loads the gemset specified inside.
Here’s how to create an .rvmrc file if you’re using a gemset named “ruby-1.9.3-p194 @rails32”:
$ echo "rvm ruby-1.9.3-p194 @rails32" > .rvmrc
Using an .rvmrc file means you’ll automatically be using the correct Rails and gem version when you run your application on your local machine. This works best if you create an rvm gemset specifically for your application.
Your best source for help with problems is Stack Overflow. Your issue may have been encountered and addressed by others.
You can also try Rails Hotline, a free telephone hotline for Rails help staffed by volunteers.