====== Capistrano ======
==== Capistrano 2 Default Execution Path ====
{{:capistrano_execution_path.jpg|}}
==== Overview of some common Capistrano tasks ====
=== cap deploy ===

Deploys your project. This calls both `update' and `restart'. Note that this
will generally only work for applications that have already been deployed once.
For a "cold" deploy, you'll want to take a look at the `deploy:cold' task, which
handles the cold start specifically.

  task :default do
    update
    restart
  end


=== cap deploy:cold ===

Deploys and starts a `cold' application. This is useful if you have not deployed
your application before, or if your application is (for some other reason) not
currently running. It will deploy the code, run any pending migrations, and then
instead of invoking `deploy:restart', it will invoke `deploy:start' to fire up
the application servers.

  task :cold do
    update
    migrate
    start
  end

=== cap deploy:update ===

Copies your project and updates the symlink. It does this in a transaction, so
that if either `update_code' or `symlink' fail, all changes made to the remote
servers will be rolled back, leaving your system in the same state it was in
before `update' was invoked. Usually, you will want to call `deploy' instead of
`update', but `update' can be handy if you want to deploy, but not immediately
restart your application.

  task :update do
    transaction do
      update_code
      symlink
    end
  end

=== cap deploy:update_code ===

Copies your project to the remote servers. This is the first stage of any
deployment; moving your updated code and assets to the deployment servers. You
will rarely call this task directly, however; instead, you should call the
`deploy' task (to do a complete deploy) or the `update' task (if you want to
perform the `restart' task separately).

You will need to make sure you set the :scm variable to the source control
software you are using (it defaults to :subversion), and the :deploy_via
variable to the strategy you want to use to deploy (it defaults to :checkout).

  task :update_code, :except => { :no_release => true } do
    on_rollback { run "rm -rf #{release_path}; true" }
    strategy.deploy!
    finalize_update
  end

=== cap deploy:migrate ===

Run the migrate rake task. By default, it runs this in most recently deployed
version of the app. However, you can specify a different release via the
migrate_target variable, which must be one of :latest (for the default
behavior), or :current (for the release indicated by the `current' symlink).
Strings will work for those values instead of symbols, too. You can also specify
additional environment variables to pass to rake via the migrate_env variable.
Finally, you can specify the full path to the rake executable by setting the
rake variable. The defaults are:

  set :rake,           "rake"
  set :rails_env,      "production"
  set :migrate_env,    ""
  set :migrate_target, :latest

  task :migrate, :roles => :db, :only => { :primary => true } do
    rake = fetch(:rake, "rake")
    rails_env = fetch(:rails_env, "production")
    migrate_env = fetch(:migrate_env, "")
    migrate_target = fetch(:migrate_target, :latest)

    directory = case migrate_target.to_sym
      when :current then current_path
      when :latest  then latest_release
      else raise ArgumentError, "unknown migration target #{migrate_target.inspect}"
      end
    run "cd #{directory}; #{rake} RAILS_ENV=#{rails_env} #{migrate_env} db:migrate"
  end

==== Capistrano Errors ====
Below are some possible errors that you could encounter while running cap tasks

== ssh is not opened from build to target server or target server not responding ==

  connection failed for: prdweb1.exphosted.com (Errno::ETIMEDOUT: Connection timed out - connect(2)) 

== ssh public key authentication is not set ==
You will get Password prompt:

  Password:

== Incorrect ssh password or authentication ==

  connection failed for: prdweb1.exphosted.com (Net::SSH::AuthenticationFailed: expprdw1)

== Lack of proper permissions on /deploy folder on target server ==
  
  *** [err :: prdweb1.exphosted.com] mkdir: cannot create directory `/deploy': Permission denied (or)
  *** [err :: prdweb1.exphosted.com] mkdir: cannot create directory `/deploy/crossbow': Permission denied
  failed: "sh -c 'mkdir -p /deploy/crossbow /deploy/crossbow/releases /deploy/crossbow/shared /deploy/crossbow/shared/system /deploy/crossbow/shared/log /deploy/crossbow/shared/pids &&  chmod g+w /deploy/crossbow /deploy/crossbow/releases /deploy/crossbow/shared /deploy/crossbow/shared/system /deploy/crossbow/shared/log /deploy/crossbow/shared/pids'" on prdweb1.exphosted.com

== Symlink or file not present errors ==
  
  *** [err :: prdweb1.exphosted.com] ln: creating symbolic link `/deploy/crossbow/releases/20110525203341/config/database.yml' to `/deploy/crossbow/database.yml': No such file or directory

== DB Migrate (production settings not in database.yml) ==
  
   * executing `deploy:migrate'
   * executing "cd /deploy/crossbow/releases/20110525213821; bundle exec rake RAILS_ENV=production  db:migrate"
    servers: ["prdweb1.exphosted.com"]
    [prdweb1.exphosted.com] executing command
   *** [err :: prdweb1.exphosted.com] rake aborted!
   *** [err :: prdweb1.exphosted.com]
   *** [err :: prdweb1.exphosted.com] production database is not configured

== DB Migrate (no slave database setting in database.yml) ==
  
   * executing `deploy:migrate'
   * executing "cd /deploy/crossbow/releases/20110525215013; bundle exec rake RAILS_ENV=production  db:migrate"
    servers: ["prdweb1.exphosted.com"]
    [prdweb1.exphosted.com] executing command
   *** [err :: prdweb1.exphosted.com] rake aborted!
   *** [err :: prdweb1.exphosted.com]
   *** [err :: prdweb1.exphosted.com] No slaves databases defined for environment: production

== DB Migrate (incorrect mysql user/passwd) ==
  
   * executing `deploy:migrate'
   * executing "cd /deploy/crossbow/releases/20110525220110; bundle exec rake RAILS_ENV=production  db:migrate"
    servers: ["prdweb1.exphosted.com"]
    [prdweb1.exphosted.com] executing command
   *** [err :: prdweb1.exphosted.com] rake aborted!
   *** [err :: prdweb1.exphosted.com]
   *** [err :: prdweb1.exphosted.com] Access denied for user 'cbprod'@'localhost' (using password: YES)

== DB Migrate (code related issue) ==
  
   *** [out :: prdweb1.exphosted.com] ==  AddDescriptionToCompany: migrated (0.0088s) ===============================
   *** [err :: prdweb1.exphosted.com] rake aborted!
   *** [err :: prdweb1.exphosted.com] An error has occurred, all later migrations canceled:
   *** [err :: prdweb1.exphosted.com]
   *** [err :: prdweb1.exphosted.com] Constant CreateSelections from create_selections.rb not found
   *** [err :: prdweb1.exphosted.com]
   *** [err :: prdweb1.exphosted.com] (See full trace by running task with --trace)
   command finished in 23233ms
   failed: "sh -c 'cd /deploy/crossbow/releases/20110525220437; bundle exec rake RAILS_ENV=production  db:migrate'" on prdweb1.exphosted.com

== DB Migrate (mysql service is not running) ==
  
   * executing `deploy:migrate'
   * executing "cd /deploy/crossbow/releases/20110526161732; bundle exec rake RAILS_ENV=production  db:migrate"
    servers: ["prdweb1.exphosted.com"]
    [prdweb1.exphosted.com] executing command
   *** [err :: prdweb1.exphosted.com] rake aborted!
   *** [err :: prdweb1.exphosted.com]
   *** [err :: prdweb1.exphosted.com] Can't connect to local MySQL server through socket '/var/lib/mysql/mysql.sock' (2)
   *** [err :: prdweb1.exphosted.com]
   *** [err :: prdweb1.exphosted.com]
   *** [err :: prdweb1.exphosted.com] (See full trace by running task with --trace)
   *** [err :: prdweb1.exphosted.com]
   ** [out :: prdweb1.exphosted.com] (in /deploy/crossbow/releases/20110526161732)
   command finished in 13643ms
   failed: "sh -c 'cd /deploy/crossbow/releases/20110526161732; bundle exec rake RAILS_ENV=production  db:migrate'" on prdweb1.exphosted.com