updating rails
Last updated 23 August 2014
Upgrading to Rails 4.2, the newest Ruby on Rails version. How to update Rails versions and upgrade Rails applications. Instructions and advice.
This article shows how to add a new version of Rails while keeping an old version. Rails is revised frequently and you’ll likely need more than one version. Don’t simply replace an old version of Rails with another. Instead, set up your development environment with multiple versions of Rails so you can easily switch between them.
Rails is actively maintained by a large community of developers, which means constant innovation, improvements, and attention to security. It also means you must actively and regularly maintain your Rails applications. You should upgrade your Rails applications when a new version of Rails is released. If you neglect to update regularly, upgrading several versions at once may require considerable effort, making it difficult to resolve security vulnerabilities quickly. If you don’t update Rails, you leave your application and its server open to attack.
Developers often install the newest version of Rails but neglect other components needed for Rails to run successfully. Rails is not just a Ruby gem, it is a complex and rapidly evolving ecosystem. It is important to set up your development environment with the most current version of all the gems that are needed for development.
This is an article from the RailsApps project. The RailsApps project provides example applications that developers use as starter apps. Hundreds of developers use the apps, report problems as they arise, and propose solutions. Rails changes frequently; each application is known to work and serves as your personal “reference implementation.” Support for the project comes from subscribers. If this article is helpful, please join the RailsApps project.
These two weekly email newsletters will keep you informed about new Rails releases:
Another weekly email newsletter is more technical, and focused on code arriving in the next version of Rails:
You also can follow @rails_apps on Twitter for news.
You should use the newest version of Ruby when you start work on a new Rails application. Rails versions 3.2 to 4.2 were built to work with any version of Ruby from 1.9.3 to 2.1, allowing flexibility. However, Rails 5.0 will likely require Ruby 2.2. If you have an older application, take time to make sure it runs on the newest version of Ruby, and you’ll be ready to upgrade to Rails 5.0 when needed.
To switch between Ruby versions, you’ll need a Ruby version manager such as RVM, chruby, or Sam Stephenson’s rbenv.
Rails developers love to debate the merits of their tools and you’ll hear strong opinions about preferences for RVM, chruby, or rbenv. Chruby is the simplest; you’ll need a separate tool such as ruby-install to install Ruby versions. Rbenv is a favorite among people who are experienced Unix users. I recommend RVM for beginners because it is robust and full-featured, with options for installing Ruby and managing sets of gems. This article will show how to use RVM to manage Rails versions, though you can adapt the principles for chruby or rbenv.
These articles from the RailsApps project will show you how to install multiple versions of Ruby using RVM:
Install Ruby on Rails – Mac OS X Mavericks
Install Ruby on Rails – Ubuntu
Install Ruby on Rails – Nitrous.io
If you’re using Windows, see the article Installing Rails.
If you are not using RVM already, see the articles to get started with multiple versions of Ruby. The articles are detailed and provide good advice, so it is worthwhile to take a look if you haven’t read the articles previously.
Rails 4.1 is the current stable version.
Rails 4.2.0.beta1 is the newest pre-release version. Notable additions include Active Job for queueing tasks to run separately from the user request-response cycle.
Learn more about Rails 4.2:
What You Need to Know: Rails 4.1 is the current stable version. Upgrade older projects to Rails 4.1 now. Start new projects with the Rails 4.2 pre-release version, especially if you will use the Active Job feature.
RubyGems is the gem manager in Ruby.
Check the installed gem manager version:
$ gem -v 2.2.2
You should have:
- RubyGems 2.2.2
At the time this was written, a newer RubyGems 2.4.1 version was available. Don’t install the newer version. A bug prevents installing the newest Rails pre-release version (see Rails issue 16609) if you use RubyGems 2.4.1.
In the future, when the bug is resolved, you can use gem update --system to upgrade the Ruby gem manager.
RVM gives you gemsets, which are sandboxed environments that let you maintain separate sets of gems. Gemsets are ideal for multiple versions of Rails.
Display a list of gemsets:
$ rvm gemset list gemsets for ruby-2.1.2 => (default) global
Only the “default” and “global” gemsets are pre-installed.
If you get an error “rvm is not a function,” close your console and open it again.
See what gems are installed in the “global” gemset:
$ rvm gemset use global $ gem list
A trouble-free development environment requires the newest versions of the default gems.
Several gems are installed with Ruby or the RVM default gemset:
To get a list of gems that are outdated:
$ gem outdated ### list not shown for brevity
To update all stale gems:
$ gem update ### list not shown for brevity
In particular, rake should be updated to version 10.2.1 or newer.
You can track updates to gems at the RubyGems.org site by creating an account and visiting your dashboard. Search for each gem you use and “subscribe” to see a feed of updates in the dashboard (an RSS feed is available from the dashboard). As an alternative, use the Gemnasium service which surveys your GitHub repo and sends email notifications when gem versions change. Gemnasium is free for public repositories with a premium plan for private repositories.
Here’s the simplest way to update an application to a new version of Rails. Use this method for updates between patch versions, for example from Rails 4.1.5 to 4.1.6. Use this simple procedure if you don’t think you’ll need to move back and forth between versions. Make sure you have committed the Gemfile and Gemfile.lock files to git so you can restore a known working version of your application if necessary. I recommend using RVM, the Ruby Version Manager when you need to switch between Rails versions (described in the nest section).
Your Gemfile specifies the Rails version used by your application. If you have a Rails 4.1.5 application:
source 'https://rubygems.org' gem 'rails', '4.1.5'
You can change the Rails version to a newer version of Rails. For example, update it to Rails 4.1.6:
source 'https://rubygems.org' gem 'rails', '4.1.6'
Then run:
$ bundle update rails
The Rails gem will be updated by bundler and the Gemfile.lock file will be updated to record the new gem version.
You’ll see a message showing which version of Rails is running when you start the web server.
This approach is appropriate if you are moving between patch versions, for example from Rails 4.1.5 to 4.1.6. If you’re making a big upgrade, for example from Rails 3.2 to Rails 4.0, use RVM and follow the procedure below.
You can install Rails directly into the global gemset. However, many developers prefer to keep the global gemset sparse and install Rails into project-specific gemsets, so each project has the appropriate version of Rails. You may also wish to have gemsets for different versions of Rails, for example Rails 4.1 and Rails 4.2.
First, make a gemset just for the current stable release:
$ rvm use ruby-2.1.2@rails4.1 --create
If you want the most recent stable release:
$ gem install rails $ rails -v
Make another gemset for the newest beta version or release candidate using --pre.
$ rvm use ruby-2.1.2@rails4.2 --create $ gem install rails --pre $ rails -v
At this time, you’ll get Rails 4.2.0.beta1. Be sure you are using RubyGems 2.2.2 (check with gem -v) as newer versions of RubyGems have a bug that prevents installing the Rails pre-release version (see Rails issue 16609).
You can install a specific version if you need it.
For example, if you want the Rails 3.2.18 release:
$ rvm use ruby-2.1.2@rails3.2 --create $ gem install rails --version=3.2.18 $ rails -v
You can easily switch between gemsets.
For example, to use Rails 4.1:
$ rvm use ruby-2.1.2@rails4.1
If you’ve already created an application, you can create a project-specific gemset. Here’s how to create a gemset for an application named “myapp” and create .ruby-version and .ruby-gemset files in the application’s project directory:
$ rvm use ruby-2.1.2@myapp --ruby-version --create
The next time you cd into the project directory, RVM will read the .ruby-version and .ruby-gemset files and automatically configure your development environment to use the correct Ruby version and gemset. If it is a new gemset, and a Gemfile is present in the project directory, you can use bundle install to install the necessary gems.
Before you update Rails, take time to find out how the default new Rails application has changed.
You can easily see differences between versions of the Rails default application at the railsdiff.org site.
Or do the research yourself. First, create a starter app with the old version of Rails. Then switch gemsets and create a starter app with the new version of Rails.
Let’s assume you want to compare Rails 4.1 and Rails 4.2.
$ rvm use ruby-2.1.2@rails4.1 $ rails new myapp4.1 $ rvm use ruby-2.1.2@rails4.2 $ rails new myapp4.2
Compare the two applications with a file compare tool.
You may find a few differences in the starter Rails application between versions. Patch updates seldom change the default new Rails application but other updates may change the starter app files. Major Rails updates often make many changes.
With RVM, it’s convenient to preserve the set of gems that are known to work with your application. If you have difficulties with new gem versions, you can switch back to the older gemset easily, without reinstalling your old gems.
Let’s assume you have an application named “myapp” that runs with Ruby 2.1.2 and Rails 4.1.15.
We’ll upgrade it to Rails 4.2.0.beta1.
Start the upgrade in the application’s root directory:
$ cd myapp
If you already have a project-specific gemset, rename it:
$ rvm gemset rename myapp Rails4.1_myapp
If not, create a project-specific gemset using Ruby Ruby 2.1.2 and Rails 4.1:
$ rvm use ruby-2.1.2@rails4.1_myapp --create $ rvm gemset list $ bundle install
Test the application. It should be working as before.
If you are comfortable using git branches, this is a good time to create one.
$ git checkout -b upgrading
The command creates a new branch named “upgrading” and switches to it, analogous to copying all your files to a new directory and moving to work in the new directory (though that is not really what happens with git).
Create a new project-specific gemset for Rails 4.2:
$ rvm use ruby-2.1.0@Rails4.2_myapp --create $ rvm gemset list
Check that the only installed gems are those from the global gemset:
$ gem list *** LOCAL GEMS *** bundler (...) rake (...) rubygems-bundler (...) rvm (...)
Check a list of versions of Rails to find the newest version of Rails.
Your Gemfile specifies the Rails version used by your application:
source 'https://rubygems.org' gem 'rails', '4.1.15' . . .
Change the Rails version to 4.2.0.beta1 (or a newer one if available).
To update to Rails 4.2.0.beta1, you’ll need to specify a newer version of sass-rails (see issue 159):
gem 'sass-rails', '~> 4.0.3'
Change the Gemfile:
gem 'sass-rails', '>= 5.0.0.beta1'
Then update the gems specified in the Gemfile:
$ bundle update
Each gem specified in the Gemfile will be installed by bundler and the Gemfile.lock file will be updated to record the gem versions. You can run gem list again to see the gems that were installed in the gemset.
Check the Rails version:
$ rails -v
Test the application and make any changes needed to run it with Rails 4.2.
Minor Rails version updates seldom require changes to configuration files. Major Rails updates often change configuration files. If you don’t make the required configuration file changes, you’ll likely see deprecation warnings when you launch a Rails application.
Rails provides a rake rails:update task to update configuration files. Be sure you’ve committed your application with git before running rake rails:update in case you need to roll back changes.
$ git commit -m 'before rake rails update' $ rake rails:update
The rake rails:update will identify every configuration file in your application that differs from a new Rails application. When it detects a conflict, it will offer to overwrite your file.
Don’t blindly allow rake rails:update to overwrite your files. Many of your files will be different because you’ve made changes from a default new Rails application. You’ll need to check each file to determine if rake rails:update is seeing your own changes or pointing out changes due to a Rails update.
When rake rails:update offers to overwrite a file, enter d (for “diff”) and review the differences. Most differences will be your own. If you’re uncertain, don’t overwrite the file; make a note for yourself and investigate later. If you are certain that the difference is due to a Rails version change, you can allow rake rails:update to overwrite the file.
If your application is running successfully under Rails 4.2, commit any changes.
$ git add -A $ git commit -m "work in progress" $ git checkout master $ git merge --squash upgrading $ git commit -m "upgrade to Rails 4.2"
The commands commit the changes to the working branch named “upgrading,” switch to the master branch, and then merge the changes into the master branch for a final commit.
It’s important to update the Rails gem when there are security fixes. You’ll seldom need to update other gems once you’ve deployed your application but you may want to stay informed of changes. You can track updates to gems by creating an account and visiting your dashboard at the RubyGems.org site. Search for each gem you use and “subscribe” to see a feed of updates in the dashboard (an RSS feed is available from the dashboard). As an alternative, use the Gemnasium or VersionEye services which survey your GitHub repo and send email notifications when gem versions change. The services are free for public repositories with a premium plan for private repositories.
You can update any gem by running bundle update gem_name. This installs the newest version of the gem (if the Gemfile entry doesn’t require a specific version) and updates the Gemfile.lock file.
You can run bundle update to update all gems at once. Bundler will observe the version rules specified in the Gemfile; when a specific version is specified in the Gemfile, running bundle update without changing the Gemfile entry won’t update a gem. Running bundle update installs new gem versions and updates the Gemfile.lock file. As an alternative to running bundle update, you can delete the Gemfile.lock file and run bundle install to replace the Gemfile.lock file.
If you are using RVM and multiple gemsets, it is best not to run bundle update rails. Instead, create a new gemset for the new Rails version as described above so you can switch gemsets as needed.
After updating Rails and other gems, run your test suite (hopefully, you have tests; this is why you need them!).
Often, when the changes to Rails are minor, you will not need to update your application. When a major new version of Rails is released, you will have to rework parts of your application. Here are resources you can use to identify specific code that needs to be updated.
- Ebook: Andy Lindeman Upgrading to Rails 4
- Ebook: Philip De Smedt Upgrade to Rails 4
- Blog post: Maciej Mensfeld Upgrading to Rails 4.0 from Rails 3.2
- Blog post: Mario Chavez Upgrading a Rails application to 4.0
- Script: Michael de Silva upgrade_rails_3.2.12_to_4.0.0.beta1
- Video: Code School Rails 4: Zombie Outlaws
- Article: RailsGuides Upgrading from Rails 3.2 to Rails 4.0 (work-in-progress document)
- Railscast by Ryan Bates Upgrading to Rails 3.2
By design, Rails encourages practices that avoid common web application vulnerabilities. The Rails security team actively investigates and patches vulnerabilities. If you use the most current version of Rails, you will be protected from known vulnerabilities. See the Ruby On Rails Security Guide for an overview of potential issues and watch the Ruby on Rails Security Mailing List for announcements and discussion.
Rails uses a session store to provide persistence between page requests. The default session store uses cookies. To prevent decoding of cookie data and hijacking a session, Rails encrypts cookie data using a secret key. When you create a new Rails application using the rails new command, a unique secret key is generated and written to the config/initializers/secret_token.rb file. If you’ve generated a Rails application and committed it only to a private GitHub repository, you do not need to change the secret key. However, if you’ve cloned a public GitHub repository or made your application publicly available on GitHub, you must change the secret key when you deploy. The command rake secret generates a new random secret you can use. The command won’t install the key; you have to copy the key from the console output to the config/initializers/secret_token.rb file. Remember, you should never deploy an application to production that uses a publicly available secret token (obviously, it is not secret if it is public!).
Your best source for help with problems is Stack Overflow. Your issue may have been encountered and addressed by others.