はじめに

「Capistrano のバージョンが上がったので使おうとしたら丸一日ハマっていた。」
「な…　何を言ってるのか　わからねーと思うが (ry」

Gemfile
cap install
Capfile
config/deploy.rb
config/deploy/production.rb | staging.rb
参考文献

基本的な使い方などはREADMEを読んでください。
まあ、読んでてもアレだったんですけどね。

Gemfile

Capistranoはどのような言語やフレームワークからでも利用可能」by 公式サイトとのことで、もはやRailsだけのものではありません（以前からですけど）。
よって、本体とは別に、プラグイン形式でGemを追加していきます。

group :development do
  # ...
  gem 'capistrano'
  gem 'capistrano-rails'
  gem 'capistrano-rbenv'
  gem 'capistrano-bundler'
  # ...
end

capistrano-railsに気づかずにエラーと戦っている場合があるので、気をつけてください。

capistrano 2.x時代にcapistrano_colorsをもし使っているなら、もう必要ないので、削除してください。

cap install

cap installにより以下のファイルが生成されますが、上書き保存されてしまうので、それぞれ別名で保存しておくことをおすすめします。

Capfile
config/deploy.rb
config/deploy/production.rb
config/deploy/staging.rb

Capfile

なんとなく存在していたCapfileですが、今回のアップデートでは中身がガラッと変更されました。

以下がデフォで生成されます(2013-10-10現在)

# Load DSL and Setup Up Stages
require 'capistrano/setup'

# Includes default deployment tasks
require 'capistrano/deploy'

# Includes tasks from other gems included in your Gemfile
#
# For documentation on these, see for example:
#
#   https://github.com/capistrano/rvm
#   https://github.com/capistrano/rbenv
#   https://github.com/capistrano/chruby
#   https://github.com/capistrano/bundler
#   https://github.com/capistrano/rails/tree/master/assets
#   https://github.com/capistrano/rails/tree/master/migrations
#
# require 'capistrano/rvm'
# require 'capistrano/rbenv'
# require 'capistrano/chruby'
# require 'capistrano/bundler'
# require 'capistrano/rails/assets'
# require 'capistrano/rails/migrations'

# Loads custom tasks from `lib/capistrano/tasks' if you have any defined.
Dir.glob('lib/capistrano/tasks/*.cap').each { |r| import r }

これを私は以下のように変更しました。

# Load DSL and Setup Up Stages
require 'capistrano/setup'

# Includes default deployment tasks
require 'capistrano/deploy'

require 'capistrano/rbenv'

set :rbenv_type, :user # or :system, depends on your rbenv setup
set :rbenv_ruby, '2.0.0-p247'

require 'capistrano/bundler'
require 'capistrano/rails'

# Loads custom tasks from `lib/capistrano/tasks' if you have any defined.
Dir.glob('lib/capistrano/tasks/*.cap').each { |r| import r }

config/deploy.rb

2.x時代のdeploy.rb を使いまわすことは出来ません。
cap install にて生成されるものをベースに組み立てるのが吉です。

微妙に設定項目名が変更されているので、古いものと見比べながら設定して行きます。
このとき、一点、重要な変更が。

以前はset :applicationしたものをローカル変数applicationとして使えたのですが、今回からはfetch(:application)という形で呼び出します。

コレ非常に重要。

passengerユーザの場合

namespace :deploy do

  desc 'Restart application'
  task :restart do
    on roles(:app), in: :sequence, wait: 5 do
      # Your restart mechanism here, for example:
      execute :mkdir, '-p', release_path.join('tmp') # <= これを追加する
      execute :touch, release_path.join('tmp/restart.txt')
    end
  end
  # ...
end

デプロイ時に、なぜかtmpディレクトリを生成しないので、（誰かのプルリクエストが適用されるまでは）tmpディレクトリを作成するように追記しておくと良いです。

config/deploy/(production.rb|staging.rb)

これも生成されたファイルをよく読んでください。
難しくありません。ただ、fetch(:user)など、変数の呼び出しに注意してください。

参考文献

最後に

capistranoはrailsのものだけじゃない、ということをよく理解させてくれるようなアップデートでした。
capistrano-railsというカタチで外出しされているのはとても良いことですね。

database.ymlのsymlinkとか、migrationとかをサラッとやってくれるので助かります。
皆さんもぜひ、capistranoをv3.0にアップデートしましょうね！

Upgrade to Capistrano 3.0