Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@antonmedv
antonmedv committed Nov 28, 2024
1 parent dbc3984 commit 14f9e1a
Show file tree
Hide file tree
Showing 4 changed files with 289 additions and 327 deletions.
192 changes: 96 additions & 96 deletions docs/basics.md
View file
Original file line number Diff line number Diff line change
@@ -1,44 +1,44 @@
# Basics

Deployer has two main concepts: [**hosts**](hosts.md) and [**tasks**](tasks.md).
Deployer operates around two main concepts: [**hosts**](hosts.md) and [**tasks**](tasks.md). These are defined within a
**recipe**, which is simply a file containing **hosts** and **tasks** definitions.

A **recipe** is a file containing definitions for **hosts** and **tasks**.
The Deployer CLI requires two arguments:

Deployer CLI requires two arguments to run: a **task** to run and a **selector**.
1. A **task** to execute.
2. A **selector** to determine the hosts the task will run on.

Hosts can also be [selected via labels](hosts.md#labels), also a default host selection can be configured.
Here's an example:

```
```sh
$ dep deploy deployer.org
--- ------ ------------
| | |
| | `--- Selector
| `------------- Task
`------------------ CLI
------ ------------
task selector
```

Deployer uses the [selector](selector.md) to choose hosts. Next, it takes the given
task, performs some preparation (described later), and executes the task on all
selected hosts.
Deployer uses the [selector](selector.md) to choose which hosts to execute the task on. After selecting hosts, it
prepares the environment (details later) and runs the task.

If a selector is not specified, Deployer will ask you to choose a host from a list.
If your recipe contains only one host, Deployer will automatically choose it.
To select all hosts, specify a special selector: `all`.
### Host Selection

The `dep` CLI looks for a `deploy.php` or `deploy.yaml` file in the current directory.
- If no selector is specified, Deployer prompts you to choose a host.
- If your recipe has only one host, it is automatically selected.
- To run a task on all hosts, use the `all` selector.

Or a recipe can be specified explicitly via `-f` or `--file` option.
By default, the `dep` CLI looks for a `deploy.php` or `deploy.yaml` file in the current directory. Alternatively, you
can specify a recipe file explicitly using the `-f` or `--file` option:

```
```sh
$ dep --file=deploy.php deploy deployer.org
```

Let's write a recipe.
---

## Writing Your First Recipe

Here's an example of a simple recipe:

```php
// We are going to use functions declared primarily in the Deployer namespace,
// to simplify the recipe, we will also use the Deployer namespace. Alternatively,
// you can import individual functions via "use function".
namespace Deployer;

host('deployer.org');
Expand All @@ -48,57 +48,56 @@ task('my_task', function () {
});
```

Let's try to run our task on deployer.org.
To execute this task on `deployer.org`:

```
```sh
$ dep my_task
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.
### Increasing Verbosity

Add `-v` option to increase verbosity. Read more about [CLI usage](cli.md).
By default, Deployer only shows task names. To see detailed output (e.g., the result of the `whoami` command), use the
`-v` option:

```
```sh
$ dep my_task -v
task my_task
[deployer.org] run whoami
[deployer.org] deployer
$
```

Now let's add a second host:
---

## Working with Multiple Hosts

You can define multiple hosts in your recipe:

```php
host('deployer.org');
host('medv.io');
```

How does Deployer know how to connect to a host? It uses the same `~/.ssh/config` file as
the `ssh` command. Alternatively, you can specify [connection options](hosts.md) in the recipe.
Deployer connects to hosts using the same `~/.ssh/config` file as the `ssh` command. Alternatively, you can
specify [connection options](hosts.md) directly in the recipe.

Let's run `my_task` task on both hosts:
Run a task on both hosts:

```
```sh
$ dep my_task -v all
task my_task
[deployer.org] run whoami
[medv.io] run whoami
[medv.io] anton
[deployer.org] deployer
[medv.io] anton
```

Deployer runs a task in parallel on each host. This is why the output is mixed.
We can limit it to run only on one host at a time.
### Controlling Parallelism

```
By default, tasks run in parallel on all selected hosts, which may mix the output. To limit execution to one host at a
time:

```sh
$ dep my_task -v all --limit 1
task my_task
[deployer.org] run whoami
Expand All @@ -107,21 +106,20 @@ task my_task
[medv.io] deployer
```

It is also possible to specify a [limit level](tasks.md#limit) for each individual task.
By specifying the limit level for each task, you can control the degree of parallelism
for each part of your deployment process.
You can also specify a [limit level](tasks.md#limit) for individual tasks to control parallelism.

---

## Configuring Hosts

Each host has a configuration: a list of key-value pairs. Let's define our first
configuration option for both our hosts:
Each host can have a set of key-value configuration options. Here's an example:

```php
host('deployer.org')
->set('my_config', 'foo');
host('medv.io')
->set('my_config', 'bar');
host('deployer.org')->set('my_config', 'foo');
host('medv.io')->set('my_config', 'bar');
```

In the task we can get the currently executing host using the [currentHost](api.md#currenthost) function:
Access these options in a task using the [currentHost](api.md#currenthost) function:

```php
task('my_task', function () {
Expand All @@ -130,41 +128,28 @@ task('my_task', function () {
});
```

Or with the [get](api.md#get) function:
Or more concisely with the [get](api.md#get) function:

```diff
```php
task('my_task', function () {
- $myConfig = currentHost()->get('my_config');
+ $myConfig = get('my_config');
$myConfig = get('my_config');
writeln("my_config: " . $myConfig);
});
```

Or via the [parse](api.md#parse) function which replaces the `{{ ... }}` brackets
and their enclosed values with the corresponding configuration option.

All functions (writeln, run, runLocally, cd, upload, etc) call the **parse** function
internally. So you don't need to call the **parse** function by yourself.
Or using brackets syntax `{{` and `}}`:

```diff
```php
task('my_task', function () {
- $myConfig = get('my_config');
- writeln("my_config: " . $myConfig);
+ writeln("my_config: {{my_config}}");
writeln("my_config: {{my_config}}");
});
```

Let's try to run our task:
---

```
$ dep my_task all
task my_task
[deployer.org] my_config: foo
[medv.io] my_config: bar
```
## Global Configurations

Awesome! Each host configuration inherits global configuration. Let's refactor
our recipe to define one global config option:
Host configurations inherit global options. Here's how to set a global configuration:

```php
set('my_config', 'global');
Expand All @@ -173,11 +158,23 @@ host('deployer.org');
host('medv.io');
```

The config option `my_config` will be equal to `global` on both hosts.
Both hosts will inherit `my_config` with the value `global`. You can override these values for individual hosts as
needed.


```php
set('my_config', 'global');

host('deployer.org');
host('medv.io')->set('my_config', 'bar');
```

---

Additionally, the value of a config option can be defined as a callback.
This callback is executed upon its first access, and the returned result
is then stored in the host configuration.
## Dynamic Configurations

You can define dynamic configuration values using callbacks. These are evaluated the first time they are accessed, and
the result is stored for subsequent use:

```php
set('whoami', function () {
Expand All @@ -189,22 +186,18 @@ task('my_task', function () {
});
```

Let's try to run it:
When executed:

```
```sh
$ dep my_task all
task my_task
[deployer.org] Who am I? deployer
[medv.io] Who am I? anton
```

We can use this to create a dynamic configuration which uses information from the current host.

Only the first call will trigger the callback execution. All subsequent checks use the previously
saved value.
---


Here is an example:
Dynamic configurations are cached after the first use:

```php
set('current_date', function () {
Expand All @@ -218,10 +211,9 @@ task('my_task', function () {
});
```

If we run my_task, we will see that `date` is called only once on
`{{current_date}}` access.
Running this task:

```
```sh
$ dep my_task deployer.org -v
task my_task
[deployer.org] run date
Expand All @@ -231,15 +223,23 @@ task my_task
[deployer.org] What time is it? Wed 03 Nov 2021 01:16:53 PM UTC
```

We can override a config option via CLI option `-o` like this:
---

```
## Overriding Configurations via CLI

You can override configuration values using the `-o` option:

```sh
$ dep my_task deployer.org -v -o current_date="I don't know"
task my_task
[deployer.org] What time is it? I don't know
[deployer.org] run sleep 5
[deployer.org] What time is it? I don't know
```

Since the `current_date` config option is overridden there is no need to call the callback.
So there is no 'run date'.
Since `current_date` is overridden, the callback is never executed.

---

By now, you should have a solid understanding of Deployer’s basics, from defining tasks and hosts to working with
configurations and dynamic values. Happy deploying!
Loading

0 comments on commit 14f9e1a

Please sign in to comment.