Skip to content
Official Ruby on Rails specific tasks for Capistrano
Branch: master
Clone or download

Latest commit

Latest commit 7d233fa May 15, 2020


Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Add some helpful github templates Oct 1, 2017
lib handle restore of multiple asset manifests on rollback (#226) May 11, 2020
.gitignore initial commit Mar 24, 2013
.travis.yml Set up Travis and Danger Jan 27, 2017 Release 1.5.0 May 15, 2020
Dangerfile Use shared capistrano/danger Dangerfile Mar 5, 2017
Gemfile initial commit Mar 24, 2013
LICENSE.txt initial commit Mar 24, 2013 Release 1.5.0 May 15, 2020
Rakefile Set up Travis and Danger Jan 27, 2017
capistrano-rails.gemspec Release 1.5.0 May 15, 2020


Rails specific tasks for Capistrano v3:

  • cap deploy:migrate
  • cap deploy:compile_assets


Add these Capistrano gems to your application's Gemfile using require: false:

group :development do
  gem "capistrano", "~> 3.10", require: false
  gem "capistrano-rails", "~> 1.5", require: false

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'

# Defaults to ["/path/to/release_path/public/#{fetch(:assets_prefix)}/.sprockets-manifest*", "/path/to/release_path/public/#{fetch(:assets_prefix)}/manifest*.*"]
# This should match config.assets.manifest in your rails config/application.rb
set :assets_manifests, ['app/assets/config/manifest.js']

# RAILS_GROUPS env value for the assets:precompile task. Default to nil.
set :rails_assets_groups, :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
append :linked_dirs, 'log', 'tmp/pids', 'tmp/cache', 'tmp/sockets', 'vendor/bundle', '.bundle', 'public/system', 'public/uploads'
append :linked_files, 'config/database.yml', 'config/secrets.yml'

In capistrano < 3.5, before append was introduced, you can use fetch and push to get the same result.


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.

Uploading your master.key

You can use the below configuration to upload your master.key to the server if it isn't already present.

append :linked_files, "config/master.key"

namespace :deploy do
  namespace :check do
    before :linked_files, :set_master_key do
      on roles(:app), in: :sequence, wait: 10 do
        unless test("[ -f #{shared_path}/config/master.key ]")
          upload! 'config/master.key', "#{shared_path}/config/master.key"


  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
You can’t perform that action at this time.