tasks.md

Tasks

Define your own tasks, by using the task function. Also, you can setup a description for a task with the desc function:

desc('My task');
task('my_task', function () {
    run(...);
});

To run your task:

dep my_task

To list all available commands:

dep list

To run a task only on a specified host or stage:

dep deploy main

You can specify hosts via the --hosts option (comma separate multiple values) and roles via the --roles option:

dep deploy --hosts domain.com
dep deploy --roles app

Simple tasks

If your task only contains run calls, or just one bash command, you can simplify the task definition:

task('build', 'npm build');

By default all simple tasks cd to release_path, so you don't need to.

Or you can use a multi line script:

task('build', '
    gulp build;
    webpack -p;
    echo "Build done";
');

Task grouping

You can combine tasks in groups:

task('deploy', [
    'deploy:prepare',
    'deploy:update_code',
    'deploy:vendors',
    'deploy:symlink',
    'cleanup'
]);

Before and after

You can define tasks to be run before or after some tasks.

task('deploy:done', function () {
    write('Deploy done!');
});

after('deploy', 'deploy:done');

After the deploy task is called, deploy:done will be executed.

Filtering

You can specify on which hosts/stages/roles you want to run a task.

By stage

Filter hosts by stage:

desc('Run tests for application');
task('test', function () {
    ...
})->onStage('test');

By roles

Filter tasks by roles:

desc('Migrate database');
task('migrate', function () {
    ...
})->onRoles('db');

Also you can specify multiple roles: onRoles('app', 'db', ...).

By hosts

Filter tasks by hosts:

desc('Migrate database');
task('migrate', function () {
    ...
})->onHosts('db.domain.com');

Also you can specify multiple hosts: onHosts('db.domain.com', ...).

Local tasks

Mark a task with local to run it locally and only once, independent from the hosts count.

task('build', function () {
    ...
})->local();

Note that calling run inside a local task will have the same effect as calling runLocally.

Once

To run a task only once:

task('do', ...)->once();

Will run on the first host only.

Reconfigure

You can reconfigure tasks, e.g. those provided by 3rd party recipes by retrieving them by name:

task('notify')->onStage('production');

Overriding tasks

Some times you may want to have a different behavior of some task from the common recipes. Simply override it:

task('deploy:update_code', function () {
    // Your custom update code
    upload(...);
});

Using input options

You can define additional input options and arguments, before defining tasks:

use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Input\InputArgument;

argument('stage', InputArgument::OPTIONAL, 'Run tasks only on this host or stage.');
option('tag', null, InputOption::VALUE_OPTIONAL, 'Tag to deploy.');

To get the input inside a task, this can be used:

task('foo:bar', function() {
    // For arguments
    $stage = null;
    if (input()->hasArgument('stage')) {
        $stage = input()->getArgument('stage');
    }
    
    // For option
    $tag = null;
    if (input()->hasOption('tag')) {
        $tag = input()->getOption('tag');
    }
});

Parallel task execution

When deploying to multiple hosts, Deployer will run one task on each host:

task 2task 2task 2task 2task 1task 1task 1task 1Host 4Host 3Host 2Host 1

To speedup deployment add the --parallel or -p option. This will run tasks in parallel on each host. If execution of the task on a host takes longer then on others, Deployer will wait until all hosts have finished their tasks.

task 2task 2task 2task 2task 1task 1task 1task 1Host 4Host 3Host 2Host 1

Limit the number of concurrent tasks by specifing a number. By default, up to 10 tasks will be processed concurrently.

dep deploy --parallel --limit 2

task 2task 2task 2task 2task 1task 1task 1task 1Host 4Host 3Host 2Host 1

Next: hosts.