Selector

Deployer uses the selector to choose hosts. Each host can have a set of labels. Labels are key-value pairs.

For example, stage: production or role: web.

You can use labels to select hosts. For example, dep deploy stage=production will deploy to all hosts with stage: production label.

Let's define two labels, type and env, to our hosts:

host('web.example.com')
    ->setLabels([
        'type' => 'web',
        'env' => 'prod',
    ]);

host('db.example.com')
    ->setLabels([
        'type' => 'db',
        'env' => 'prod',
    ]);

or use ->addLables() method to add labels to the existing host.

Now let's define a task to check labels:

task('info', function () {
    writeln('type:' . get('labels')['type'] . ' env:' . get('labels')['env']);
});

Now we can run this task with a selector:

$ dep info env=prod
task info
[web.example.com] type:web env:prod
[db.example.com] type:db env:prod

As you can see, Deployer will run this task on all hosts with the env: prod label. And if we define only the type label, Deployer will run this task on the specified host.

dep info type=web
task info
[web.example.com] type:web env:prod

Selector syntax

Selector syntax consists of a list of conditions, separated by , or &. There comma means OR and & means AND.

For example, type=web,env=prod is a selector of: type=web OR env=prod.

$ dep info 'type=web,env=prod'
task info
[web.example.com] type:web env:prod
[db.example.com] type:db env:prod

As you can see, both hosts are selected (as both of them have the env: prod label).

We can use & to define AND. For example, type=web & env=prod is a selector for hosts with type: web AND env: prod labels.

$ dep info 'type=web & env=prod'
task info
[web.example.com] type:web env:prod

We can use | to define OR in a subquery. For example, type=web|db & env=prod is a selector for hosts with (type: web OR type: db) AND env: prod labels.

$ dep info 'type=web|db & env=prod'
task info
[web.example.com] type:web env:prod
[db.example.com] type:db env:prod

We can also use != to negate a label. For example, type!=web is a selector for all hosts which do not have a type: web label.

$ dep info 'type!=web'
task info
[db.example.com] type:db env:prod

note

Deployer CLI can take a few selectors as arguments. For example, dep info type=web env=prod is the same as dep info 'type=web,env=prod'.

You can install bash autocompletion for Deployer CLI, which will help you to write selectors. See installation for more.

Deployer also has a few special selectors:

• all - select all hosts
• alias=... - select host by alias

If a selector does not contain an = sign, Deployer will assume that it is an alias.

For example dep info web.example.com is the same as dep info alias=web.example.com.

$ dep info web.example.com
task info
[web.example.com] type:web env:prod

$ dep info 'web.example.com' 'db.example.com'
$ # Same as: 
$ dep info 'alias=web.example.com,alias=db.example.com'

Using the select() function

You can use the select() function to select hosts by selector in your PHP code.

task('info', function () {
    $hosts = select('type=web|db,env=prod');
    foreach ($hosts as $host) {
        writeln('type:' . $host->get('labels')['type'] . ' env:' . $host->get('labels')['env']);
    }
});

Or you can use the on() function to run a task on selected hosts.

task('info', function () {
    on(select('all'), function () {
        writeln('type:' . get('labels')['type'] . ' env:' . get('labels')['env']);
    });
});

Task selectors

To restrict a task to run only on selected hosts, you can use the select() method.

task('info', function () {
    // ...
})->select('type=web|db,env=prod');

Labels in YAML

You can also define labels in a YAML recipe. For example:

hosts:
  web.example.com:
    remote_user: deployer
    env:
      environment: production
    labels:
      env: prod

But make sure to distinguish between the env and labels.env keys. env is a configuration key, and labels.env is a label.

task('info', function () {
    writeln('env:' . get('env')['environment'] . ' labels.env:' . get('labels')['env']);
});

Will print:

$ dep info env=prod
task info
[web.example.com] env:production labels.env:prod