updating rails
Last updated 2 April 2013
Installing Rails 3.2 and Rails 4.0, how to update Rails versions, and upgrading Rails applications. Instructions and advice.
If you’re a Rails developer, you really don’t want to replace an old version of Rails with another. Instead, you’ll want to install multiple versions of Rails and switch between them as you step through the process of updating your Rails applications. This article details a process you can use to update any Rails application. I also provide links to address the specifics of upgrading from Rails 3.2 to Rails 4.0.
Before you start, install multiple versions of Rails, as explained in this article:
The Installing Rails article will show you how to install Rails 3.2.13 and Rails 4.0 so you can easily switch between the most recent stable release and the newest version of Rails (Rails 4.0.0.beta1). With these versions on your machine, you’ll be able to begin updating your Rails applications.
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” so you can stay up to date. Each is accompanied by a tutorial so there is no mystery code. Maintenance and development of the RailsApps applications is supported by subscriptions to the RailsApps tutorials.
You should upgrade your Rails applications when a new version of Rails is released. Occasionally a critical security fix 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 avoid updating Rails, you could leave your application and its server open to security vulnerabilities (for example, applications that have not been updated to Rails 3.2.13 are open to attack). If you cannot upgrade Rails regularly, at least stay informed of changes in each release and be prepared to upgrade through multiple versions if a security fix is released.
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 deploy with the most current version of Rails. It is just as important to set up your development environment with the most current version of the gems that are needed for development.
If you’ve just installed Ruby as described in the Installing Rails article, your gems will be up to date.
You should have:
- RubyGems 2.0.3 — newest RubyGems system gem
- Rake 10.0.4 — newest Rake gem
- Bundler 1.3.4 — newest Bundler gem
- Rubygems-Bundler 1.1.1 — newest version of Rubygems-Bundler
Check the gem versions:
$ gem -v
Use gem update --system to upgrade the RubyGems system gem.
$ gem list
Use gem update rake to upgrade Rake.
Use gem update bundler to upgrade Bundler.
Use gem update rubygems-bundler to upgrade Rubygems-Bundler.
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 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.
Before you update Rails, take time to find out if 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 3.2.12 and Rails 3.2.13.
$ rvm use ruby-1.9.3-p392@Rails3.2.12 $ rails new myapp3.2.12 $ rvm use ruby-2.0.0@Rails3.2.13 $ rails new myapp3.2.13
Compare the two applications with a file compare tool.
In this case, you’ll find there are no differences in the starter Rails application between versions Rails 3.2.12 and Rails3.2.13. Minor Rails version updates seldom change the default new Rails application.
Major Rails updates often make many changes. You’ll be able to see the changes by comparing the old and new default Rails applications. Use the same procedure to compare Rails 3.2.13 and Rails 4.0.
It’s better to use RVM, the Ruby Version Manager, as described below, so you can switch between Rails versions. You can try this simple procedure instead if you don’t think you’ll need to move back and forth between versions. If you don’t use RVM, 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.
In most cases, your Gemfile specifies the Rails version used by your application:
source 'https://rubygems.org' gem 'rails', '3.2.13'
Change the Rails version to a newer version of Rails.
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 webserver.
This approach is simple but doesn’t give you much flexibility to move between Rails versions. If you’re making a major upgrade, for example from Rails 3.2 to Rails 4.0, use RVM and follow the procedure below.
If you have installed rvm, the Ruby Version Manager, you’ll have greater flexibility in maintaining your Rails applications and updating 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 and compiling your old gems.
The article Installing Rails shows how to install multiple versions of Ruby and create gemsets for more than one version of Rails.
Let’s assume you have an application named “myapp” that runs with Ruby 1.9.3-p392 and Rails 3.2.12.
First, you’ll update it to Ruby 2.0 and Rails 3.2.13, a version of Rails patched for Ruby 2.0.
Then you’ll upgrade it to Ruby 2.0 and Rails 4.0.
If you followed the instructions in the article Installing Rails, you installed Ruby 1.9.3-p392 and Ruby 2.0.0-p0.
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 Rails3.2.12_myapp
If not, create a project-specific gemset using Ruby 1.9.3-p392 and Rails 3.2.12:
$ rvm use ruby-1.9.3-p392@Rails3.2.12_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 Ruby 2.0 and Rails 3.2.13:
$ rvm use ruby-2.0.0@Rails3.2.13_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 3.2.13.
Your Gemfile specifies the Rails version used by your application:
source 'https://rubygems.org' gem 'rails', '3.2.12' . . .
Change the Rails version to 3.2.13. (or a newer one if released).
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 Ruby 2.0 and Rails 3.2.13.
You’ll repeat the process for Ruby 2.0 and Rails 4.0.
If your application is running successfully under Ruby 2.0 and Rails 3.2.13, commit any changes.
$ git add -A $ git commit -m "upgrade to Rails 3.2.13" $ git checkout master $ git merge --squash upgrading $ git commit -m "upgrade to Rails 3.2.13"
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.
Switch back to the “upgrading” branch to begin the update to Rails 4.0:
$ git checkout upgrading
Create a new project-specific gemset for Ruby 2.0 and Rails 4.0.beta1:
$ rvm use ruby-2.0.0@Rails4.0_myapp --create $ rvm gemset list
Check that the only installed gems are those from the global gemset:
$ gem list *** LOCAL GEMS *** bigdecimal (...) bundler (...) io-console (...) json (...) minitest (...) psych (...) rake (...) rdoc (...) rubygems-bundler (...) rvm (...)
Check for the newest version of Rails.
Your Gemfile specifies the Rails version used by your application:
source 'https://rubygems.org' gem 'rails', '3.2.13' ' . . .
Change the Rails version to 4.0.0.beta1 (or a newer version if released).
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 Ruby 2.0 and Rails 4.0.
See the section Updating Your Application for links to articles that detail the specifics of upgrading to Rails 4.0.
You can follow the progress of Rails 4.0 development on the EdgeRails.info site.
If your application is running successfully under Ruby 2.0 and Rails 4.0, commit any changes.
$ git add -A $ git commit -m "upgrade to Rails 4.0" $ git checkout master $ git merge --squash upgrading $ git commit -m "upgrade to Rails 4.0"
Then delete the “upgrading” branch:
$ git branch -D upgrading
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 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.
Instead of running rake rails:update on your application, it may be easier to use the rake command to compare two default Rails applications to identify changes to configuration files. Using the older version of Rails that you’ve used to build your application run rails new my_old_app. Update the “my_old_app” application to the newest version of Rails by changing the Gemfile and running bundle update. Then run rake rails:update to find how configuration files changed between versions.
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 by Andy Lindeman Upgrading to Rails 4
- Bblog post by Mario Chavez Upgrading a Rails application to 4.0
- Script by Michael de Silva upgrade_rails_3.2.12_to_4.0.0.beta1
- 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 encypts 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.
You can also try Rails Hotline, a free telephone hotline for Rails help staffed by volunteers.