2.x DSL Configuration Tasks Task

Definition

task(name, options={}, &block)

Module

Capistrano::Configuration::Namespaces

Tasks are the fundamental unit of work in Capistrano. With the task method, you can declare certain actions to be taken against some set of servers. You can also invoke other tasks.

Arguments

name

This should be a symbol naming the task. The name should include only letters, numbers, and the underscore character; using other characters in task names may make it difficult to invoke the task from other tasks.

options

When declaring a task, you can specify any of the options that run accepts. Additionally, you can specify:

• :desc A string describing the task. This is typically provided via the desc method, but sometimes it is more convenient to pass it as an option.
• :on_error This must be a symbol, or nil. If a symbol, it must be either :continue, or :abort. If nil, it defaults to :abort. If this value is :abort, then a command that fails within the task will cause Capistrano to abort processing at this task. If it is :continue, then a command that fails within the task will allow Capistrano to proceed, despite the failure.

Note that, of the additional options that run provides, typically you'll only use :roles, :only, or :except with task. However, you are free to use any of them if you need them.

&block

A block must be given; it defines the body of the task. Within the body of a task, you'll typically make use of run, transaction, on_rollback, and so forth. You can also invoke other tasks, either via find_and_execute_task, or by invoking the task directly, as if it were a method.

Examples

task :restart, :roles => [:web, :app] do
  parallel do |session|
    session.when "in?(:web)", "#{sudo} apachectl restart"
    session.when "in?(:app)", "#{sudo} restart_mongrel"
  end
end

task :deploy do
  transaction do
    update_code
    symlink
  end

  restart
end

task :backup_database, :roles => :db, :only => { :backup => true } do
  run "#{sudo} mysqldump ... > /tmp/backup.sql"
  run "#{sudo} bzip2 /tmp/backup.sql"
  run "scp /tmp/backup.sql.bz2 offsite.host:/u/backups"
  run "#{sudo} rm /tmp/backup.sql.bz2"
end

namespace :apache do
  [:stop, :start, :restart, :reload].each do |action|
    desc "#{action.to_s} server"
    task action, :roles => :web do
      run "apachectl -f /usr/apache2/conf/httpd.conf -k #{action.to_s}"
    end
  end
end