55 Minutes

Welcome to the 55 Minutes blog.
55 Minutes is a web development consultancy in San Francisco building apps for design-led businesses and startups. On this blog we discuss the technology tools of our trade: Ruby on Rails, Django, Sass, OS X, and more.

Upgrading to Rails 4 with Capistrano

There are plenty of good guides that explain how migrate a Rails 3 codebase to Rails 4. However if you deploy using Capistrano, there are few more things to consider. Here’s what to watch out for when doing your first Rails 4 deploy after upgrading.

A JavaScript runtime is needed on all servers

In Rails 3, asset pipeline related gems were confined to a special :assets group in the Gemfile. In practice this meant those gems were only loaded during asset compilation, which happens on the web server. Your web server would therefore need a JavaScript runtime (e.g. Node) installed in order to load things like the coffee-script gem.

In Rails 4, the standard Gemfile no longer has an :assets group, which means asset pipeline gems are always loaded in production, on all servers. Make sure you have a JavaScript runtime installed on all of your servers or you may get this error when starting your app:

Could not find a JavaScript runtime.

There are two common ways to resolve this:

Capistrano’s manifest backup fails

The capistrano-rails plugin for Capistrano 3 automatically makes a backup of your asset pipeline manifest during deployment. The script is written in such a way that it assumes only a single manifest file will exist.

When doing your first deploy of a Rails 4 app after upgrading from Rails 3, you will end up with multiple manifests: the old Rails 3 manifest will still be in shared/public/assets from previous deployments, and the new Rails 4 manifest (which uses a different format and filename) will be created alongside it.

In this situation Capistrano deployment will fail with an error:

assets_manifest_backup is not a directory

To correct the problem, SSH into your server and move the old *manifest.yml files out of shared/public/assets and into a backup location. Then re-run the deployment.

Specify secret_key_base

Rails 4 uses a mechanism for encrypting sessions that makes use of a new configuration setting called secret_key_base. Since it is not stored in source control, make sure your deployment environment is somehow specifying this value.

Don’t attempt upgrading from Capistrano 2.x at the same time

If your Rails 3 project uses Capistrano 2.x and you are considering upgrading to Capistrano 3, resist the temptation to do the Capistrano upgrade and the Rails update at the same time. Upgrading Capistrano brings its own set of headaches, so I recommend a staggered approach.

  1. Upgrade your app to Rails 4 first. In your Gemfile, pin the capistrano gem at the older version using gem "capistrano", "~> 2.15.5".
  2. Deploy your Rails 4 app. Use a staging/test environment to work out the kinks, then take it all the way to production.
  3. Once Rails 4 is working nicely, then tackle the Capistrano 3 upgrade.

Good luck!

comments powered by Disqus