1. Upgrading to Rails 3.1

Add Rails 3.1 to your Gemfile. Add or change the gem 'rails' line:

gem 'rails', '3.1.0'

Bundle install:

$ bundle install

Run the update task to get your Rails files up to date, but beware! Just overwriting all files will probably mess up your app, so make sure to backup files or take notice of what changes you need to add to the new files before overwriting them. It will ask you what to do:

$ rake rails:update

Now your app should be running Rails 3.1. You can try running it using rails s but it probably won’t look great because we’ve not yet migrated the assets.

2. Migrating your assets

Try switching off the assets pipeline by commenting out the following line in config/application.rb:

# config.assets.enabled = true

Your app should now be running as usual. If it doesn’t, try ironing out any issues before switching on the assets again:

config.assets.enabled = true

We’re now ready to migrate the assets.

First, add this to your Gemfile:

gem 'jquery-rails'
group :assets do
  gem 'sass-rails', "  ~> 3.1.0"
  gem 'coffee-rails', "~> 3.1.0"
  gem 'uglifier'
end

And install:

$ bundle install

Now to the actual migration:

1. Make sure you have the images, javascripts, and stylesheets folders in your app/assets folder.
2. Move all content from public/images into app/assets/images.
3. Move all content from public/javascripts into app/assets/javascripts.
4. Move all content from public/stylesheets into app/assets/stylesheets.

Your javascripts and stylesheets will be compiled into a single application.js and application.css, so add or change this in your app/views/layouts/application.html.erb:

<%= stylesheet_link_tag 'application' %>
<%= javascript_include_tag 'application' %>

To make sure that the assets generator will find all your javascripts and stylesheets, we will include all your javascripts in application.js and all your stylesheets in application.css. Assuming you are using jQuery, you can delete jquery.js and jquery-ui.js as they will be required and inserted automatically. Add the following to the top of app/assets/javascripts/application.js:

//= require jquery
//= require jquery_ujs
//= require_tree .

And to the top of app/assets/stylesheets/application.css:

/*
 *= require_self
 *= require_tree .
*/

Your javascripts and stylesheets will now be included automatically.

At last update all your image paths from /images to /assets. If you’re using the image_tag helper, all paths will be updated automatically.

3. Deploying your assets

Assuming you are deploying using Capistrano, add the following to your config/deploy.rb:

before "deploy:symlink", "assets:precompile"

namespace :assets do
  desc "Compile assets"
  task :precompile, :roles => :app do
    run "cd #{release_path} && rake RAILS_ENV=#{rails_env} assets:precompile"
  end
end

Your assets will now be compiled right before your app is moved into place in your production environment.

Try deploying your app:

$ cap deploy

If the deployment went as expected, great. If you get an error complaining about a missing JavaScript engine, try adding the following to the assets section of your Gemfile:

gem 'therubyracer'

And run the deployment again.

Your assets should now be in place! If you run into other problems, please write a comment below, and I’ll see if I can help.

Follow me on Twitter

In your deploy.rb:

after "deploy:update_code", "bundle:install"

namespace :bundle do
  desc "Bundle install"
  task :install, :roles => :app do
    run "cd #{current_release} && #{sudo} bundle install"
  end
end

It’s as easy as that. Let me know if you have any comments.

Follow me on Twitter

Thought I’d share this because I had a lot of trouble figuring out how and where to run the “rake gems:install” when deploying with Capistrano. I wanted it to automatically deploy the gems when I call “cap deploy:migrations” – this is done by installing the gems right after update_code, like this:

# config/deploy.rb
after "deploy:update_code", "gems:install"

namespace :gems do
  desc "Install gems"
  task :install, :roles => :app do
    run "cd #{current_release} && #{sudo} rake gems:install"
  end
end

Some of the examples I’ve seen use “cd #{current_path}” but I don’t think this would work as the “current” symlink hasn’t been updated at the time the “update_code” task is run. That’s why I use “current_release”.

Also others use “rake RAILS_ENV=production gems:install” but I can’t see why you should have to use RAILS_ENV here. If I’m wrong, please correct me.

Some of the links I found when trying to get this to work:

• Capistrano recipes: deploy
• cap gems:install and a Gem dependency gotcha
• Install required gems remotely with capistrano
• lib/capistrano/recipes/deploy.rb

Follow me on Twitter