updating rails
Last updated 16 August 2016
Upgrading to Rails 5.0, 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. This article shows how to switch between versions of Ruby and Rails using RVM, the Ruby Version Manager.
Rails is actively maintained by a large community of developers, which means constant innovation, improvements, and attention to security. You must actively and regularly maintain your Rails applications. Upgrade your Rails applications whenever 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. Here’s advice on timing:
- update security patch versions immediately
- wait a month after a new major version is released to see if others report issues
- upgrade before the next major version is released (within a year, typically)
If you wait too long to upgrade, the community moves on and you’ll find it difficult get help with any issues.
It is important to set up your development environment with the most current version of all the gems that are needed for development. Developers often install the newest version of Rails but neglect other components needed for Rails to run successfully.
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 developers who purchase the Capstone Rails Tutorials.
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 with 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.2, allowing flexibility. However, Rails 5.0 requires Ruby 2.2.2 or newer. If you have an older application, take time to make sure it runs on the newest version of Ruby so you can upgrade to Rails 5.0.
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
Install Ruby on Rails – Ubuntu
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 5.0 is the current stable version. It was released on June 30, 2016 after six months of beta releases.
Notable additions in Rails 5.0 include an option for an API-only application suitable for use as a backend to JavaScript or mobile applications. Also Action Cable for live features such as chat and notifications.
Learn more about Rails 5.0:
- Rails 5.0 Release Notes
- Rails 5.0.0.beta1: Action Cable, API mode, Rails command
- What’s new in Rails 5?
- A Look at Rails 5
- What’s New in Rails 5
What You Need to Know: Rails 5.0 is the current stable version. Update to Rails 5.0 as soon as possible so you can keep your application current.
RubyGems is the gem manager in Ruby.
Check the installed gem manager version. You may see:
$ gem -v 2.4.8
At the time this was written, a newer RubyGems version was available. Use gem update --system to upgrade the Ruby gem manager:
$ gem update --system
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.3.1 => (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
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.
Nokogiri is a gem that is a dependency for many other gems (specifically, the rails-html-sanitizer gem and its dependency, the loofah gem). Nokogiri is a gem that requires compilation for your specific operating system. As such, if your system environment doesn’t match Nokogiri’s requirements, compilation of Nokogiri will fail. If your system is configured properly, you’ll be able to compile Nokogiri. However, compilation takes time. Every time you install the Nokogiri gem, you’ll wait (as long as five minutes).
To save time, install the Nokogiri gem in the RVM global gemset:
$ gem install nokogiri
During installation, Nokogiri will display two lengthy messages in the console. It will also pause without displaying any progress for as long as five minutes. Don’t assume installation has failed unless you see an error message or you’ve waited more than ten minutes.
If installation fails, make sure your system is configured properly (look for help on Stack Overflow).
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.2.4 to 4.2.5. 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 next section).
Your Gemfile specifies the Rails version used by your application. If you have a Rails 4.2.4 application:
source 'https://rubygems.org' gem 'rails', '4.2.4'
You can change the Rails version to a newer version of Rails. For example, update it to Rails 4.2.5:
source 'https://rubygems.org' gem 'rails', '4.2.5'
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. If you’re making a big upgrade, for example from Rails 4.2 to Rails 5.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.2 and Rails 5.0.
First, make a gemset just for the 4.2 release:
$ rvm use [email protected] --create
If you want the Rails 4.2.5 release:
$ gem install rails --version=4.2.5 $ rails -v
Make another gemset for the Rails 5.0 version:
$ rvm use [email protected] --create $ gem install rails $ rails -v
You can install a specific version if you need it.
For example, if you want the Rails 3.2.18 release:
$ rvm use [email protected] --create $ gem install rails --version=3.2.18 $ rails -v
You can easily switch between gemsets.
For example, to use Rails 4.2:
$ rvm use [email protected]
To use Rails 5.0:
$ rvm use [email protected]
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.3.1@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.
There are two ways to compare differences in a simple Rails application:
- visit the site railsdiff.org
- create new Rails starter applications in Rails 4.2 and Rails 5.0 and examine the differences
The best way to see differences between versions of the Rails default application is by visiting the railsdiff.org site.
If you want to see the differences and copy and paste code, you can create two versions of a starter application. 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.2 and Rails 5.0.
$ rvm use [email protected] $ rails new myapp4.2 $ rvm use [email protected] $ rails new myapp5.0
Compare the two applications with a file compare tool.
Major Rails updates often make many changes. Patch updates seldom change the default new Rails application.
First, review the official release notes:
The release notes are very detailed. In many cases, none of the changes will affect your application. Scan the release notes to identify any issues that may affect you. You’ll have to know your application well enough that you recognize changes that may affect your code.
Then try running your application with the newer version of Rails.
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 Rails 4.2.5.
We’ll upgrade it to Rails 5.0.
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.2_myapp
If not, create a project-specific gemset using Ruby Ruby 2.3.1 and Rails 4.2:
$ rvm use [email protected]_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 5.0:
$ rvm use [email protected]_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.2.5' . . .
Change the Rails version to 5.0.0 (or a newer one if available):
source 'https://rubygems.org' gem 'rails', '5.0.0' . . .
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 5.0.
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 rails rails:update task to update configuration files. Be sure you’ve committed your application with git before running rails rails:update in case you need to roll back changes.
$ git add . $ git commit -m 'before rails rails update' $ rails rails:update
The rails 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 rails 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 rails rails:update is seeing your own changes or pointing out changes due to a Rails update.
When rails 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 rails rails:update to overwrite the file.
As of Rails 5.0, a configuration file shows all changed configuration settings in a single initializer file. Take a look at the file:
- config/initializers/new_framework_defaults.rb
Examine this file and see if your application relies on any configuration settings that have changed from defaults in the new Rails version. Most simple applications will not be affected by the changed defaults.
If your application is running successfully under Rails 5.0, 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 5.0"
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.
After updating Rails and configuration files, 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. Take a look at a checklist from Jesse Wolgamott:
- 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
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.
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.