Official Ruby on Rails specific tasks for Capistrano
Latest commit 7fe416a Jan 10, 2017 @mattbrictson mattbrictson Preparing v1.2.2
Failed to load latest commit information.
lib Added BC support for rake < 11 Jan 10, 2017
.gitignore initial commit Mar 24, 2013 Preparing v1.2.2 Jan 10, 2017
Gemfile initial commit Mar 24, 2013
LICENSE.txt initial commit Mar 24, 2013 Preparing v1.2.0 Oct 26, 2016
Rakefile initial commit Mar 24, 2013
capistrano-rails.gemspec Preparing v1.2.2 Jan 10, 2017


Rails specific tasks for Capistrano v3:

  • cap deploy:migrate
  • cap deploy:compile_assets


Add these lines to your application's Gemfile:

group :development do
  gem 'capistrano', '~> 3.6'
  gem 'capistrano-rails', '~> 1.2'

Run the following command to install the gems:

bundle install

Then run the generator to create a basic set of configuration files:

bundle exec cap install


Require everything (bundler, rails/assets and rails/migrations):

# Capfile
require 'capistrano/rails'

Or require just what you need manually:

# Capfile
require 'capistrano/bundler' # Rails needs Bundler, right?
require 'capistrano/rails/assets'
require 'capistrano/rails/migrations'

Please note that any requires should be placed in Capfile, not in config/deploy.rb.

You can tweak some Rails-specific options in config/deploy.rb:

# If the environment differs from the stage name
set :rails_env, 'staging'

# Defaults to :db role
set :migration_role, :db

# Defaults to the primary :db server
set :migration_servers, -> { primary(fetch(:migration_role)) }

# Defaults to false
# Skip migration if files in db/migrate were not modified
set :conditionally_migrate, true

# Defaults to [:web]
set :assets_roles, [:web, :app]

# Defaults to 'assets'
# This should match config.assets.prefix in your rails config/application.rb
set :assets_prefix, 'prepackaged-assets'

# If you need to touch public/images, public/javascripts, and public/stylesheets on each deploy
set :normalize_asset_timestamps, %w{public/images public/javascripts public/stylesheets}

# Defaults to nil (no asset cleanup is performed)
# If you use Rails 4+ and you'd like to clean up old assets after each deploy,
# set this to the number of versions to keep
set :keep_assets, 2


You'll probably want to symlink Rails shared files and directories like log, tmp and public/uploads. Make sure you enable it by setting linked_dirs and linked_files options:

# deploy.rb
set :linked_dirs, fetch(:linked_dirs, []).push('log', 'tmp/pids', 'tmp/cache', 'tmp/sockets', 'vendor/bundle', 'public/system', 'public/uploads')
set :linked_files, fetch(:linked_files, []).push('config/database.yml', 'config/secrets.yml')


While migrations looks like a concern of the database layer, Rails migrations are strictly related to the framework. Therefore, it's recommended to set the role to :app instead of :db like:

set :migration_role, :app

The advantage is you won't need to deploy your application to your database server, and overall a better separation of concerns.


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request