Should I freeze my Rails application?

This page is obsolete.

This page describes how to freeze older versions of Ruby on Rails (before version 3). However, such versions are outdated, and customers with later versions of Rails should not use these instructions. In addition, please note that we no longer support new Rails installations.

Ruby on Rails allows you to "freeze" the version of Rails used by your application. When you freeze Rails, your application will always use that version of Rails and the associated Ruby Gems, regardless of what version is installed on the server. You can choose which version of Rails you want to freeze to.

On this page:

Freezing Rails

To freeze the RubyGems for an application:

  • Open an SSH connection.
  • Change to the html directory:
cd html
  • Change to the directory of the Rails application you would like to freeze. For example, our Ruby support page explains how to create a Ruby application called "railstest". In that case, you would change to the directory named "railstest":
cd railstest
  • Run the following command to freeze this application to the version of Rails that is currently on our servers:
rake rails:freeze:gems

This will copy the Rails files to the "vendor/rails" directory of your application. When the Rails framework runs, your application will first check for the presence of this directory. If it exists, Rails will load the Rails components from the directory instead of using the main server copy of Rails. As long as you do not delete these files, your application will continue to use your "frozen" version of Rails.

Unfreezing (thawing?) Rails

If you decide you want to switch back to the server's main copy of Rails, you can remove the frozen version with this command:

rake rails:unfreeze

Freezing to a different version

Although we've explained how to freeze Rails to the current version on the server, Rails allows you to freeze to almost any version.

For example, this command freezes your application to Rails 2.2.2:

rake rails:freeze:edge RELEASE=2.2.2

And this freezes Rails to the current development version:

rake rails:freeze:edge

The ability to freeze to different versions of rails can be useful when upgrading. For example, imagine you created a new Rails application and froze it to version 2.2.1 to ensure stability. When you became aware of a Rails upgrade (version 2.2.3 became available), you could upgrade your frozen version of Rails during an off-peak hour:

rake rails:freeze:edge RELEASE=2.2.3

Then you'd test your application to ensure it worked properly. If so, you're all set, with the latest version of Rails installed. If not, you could downgrade back to the previous version until you were able to fix the problem, using:

rake rails:freeze:edge RELEASE=2.2.1

By the way, you can tell what version of Rails your application uses with this command:

script/about

Finally, some Rails upgrades provide configuration file changes (in particular, changes to "config/boot.rb"). To get the benefit of these changes, run this command after switching Rails versions:

rake rails:update