Upgrading to Rails 4 with Capistrano

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:

• Install Node on the server (sudo apt-get install nodejs)
• Add therubyracer gem to your Gemfile

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.

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

Good luck!