diff --git a/docs/UPGRADE.md b/docs/UPGRADE.md index afd567e4e..726fbfd49 100644 --- a/docs/UPGRADE.md +++ b/docs/UPGRADE.md @@ -77,7 +77,7 @@ ``` 11. Replace `local()` tasks with combination of `once()` and `runLocally()` func. 12. Replace `locateBinaryPath()` with `which()` func. -13. Configuration property `default_stage` is not supported anymore and has been dropped. +13. Replace `default_stage` with `default_selector`, and adjust the value accordingly (for example: "prod" to "stage=prod"). 14. Replace `onHosts()` and `onStage()` with [labels & selectors](selector.md). 15. Replace `setPrivate()` with [`hidden()`](tasks.md#hidden). 16. Configuration property `writable_recursive` defaults to `false`. This behaviour can be overridden with: diff --git a/docs/basics.md b/docs/basics.md index 6b64acb59..f68cd75af 100644 --- a/docs/basics.md +++ b/docs/basics.md @@ -6,6 +6,8 @@ A **recipe** is a file containing definitions for **hosts** and **tasks**. Deployer CLI requires two arguments to run: a **task** to run and a **selector**. +Hosts can also be [selected via labels](hosts.md#labels), also a default host selection can be configured. + ``` $ dep deploy deployer.org --- ------ ------------ @@ -54,6 +56,10 @@ task my_task $ ``` +If no host is provided and no default_selector is set, Deployer will show an interactive prompt for selecting hosts. +If your recipe contains only one host, Deployer will automatically choose it. +To select all hosts specify `all`. + But where is our `whoami` command output? By default, Deployer runs with normal verbosity level and shows only the names of executed tasks. Let's increase verbosity to verbose, and rerun our task. diff --git a/docs/hosts.md b/docs/hosts.md index 1c8123741..921a64906 100644 --- a/docs/hosts.md +++ b/docs/hosts.md @@ -59,6 +59,63 @@ host('example.org') ->setRemoteUser('deployer'); ``` +## Host labels + +Hosts can receive labels to identify a subselection of all available hosts. This is a flexible approach to manage and deploy multiple hosts. +The label names and values can be chosen freely. For example, a stage name can be applied: + +```php +host('example.org') + ->setLabels(['stage' => 'prod']) +; + +host('staging.example.org') + ->setLabels(['stage' => 'staging']) +; + +``` +The example above can be simplified without labels, by giving the host prod and staging as name, and using setHostname(...). + +But for for multi server setups, labels become much more powerful: + +```php +host('admin.example.org') + ->setLabels(['stage' => 'prod', 'role' => 'web']) +; + +host('web[1:5].example.org') + ->setLabels(['stage' => 'prod', 'role' => 'web']) +; + +host('db[1:2].example.org') + ->setLabels(['stage' => 'prod', 'role' => 'db']) +; + +host('test.example.org') + ->setLabels(['stage' => 'test', 'role' => 'web']) +; + +host('special.example.org') + ->setLabels(['role' => 'special']) +; +``` + +When calling `dep deploy`, you can filter the hosts to deploy by passing a select string: + +``` +$ dep deploy stage=prod&role=web,role=special +``` + +To check for multiple labels that have to be set on the same host, you can use the `&` operator. +To add another selection, you can use `,` as a separator. + +Also you can configure a default selection string, that is used when running 'dep deploy' without arguments. + +```php +set('default_selector', "stage=prod&role=web,role=special"); +``` + + ## Host config ### `alias` diff --git a/src/Command/SelectCommand.php b/src/Command/SelectCommand.php index 34c2ff31e..7503e6657 100644 --- a/src/Command/SelectCommand.php +++ b/src/Command/SelectCommand.php @@ -49,7 +49,7 @@ protected function selectHosts(Input $input, Output $output): array if (!$output->isDecorated() && !defined('NO_ANSI')) { define('NO_ANSI', 'true'); } - $selector = $input->getArgument('selector'); + $selector = Deployer::get()->config->get('default_selector', $input->getArgument('selector')); $selectExpression = is_array($selector) ? implode(',', $selector) : $selector; if (empty($selectExpression)) {