deployer/docs/hosts.md

# Hosts

To define a new host use [host()](api.md#host) function. Deployer keeps list of
all defined tasks in the `Deployer::get()->hosts` collection.

```php
host('example.org');
```

Each host contains own configuration key-value pairs. The [host()](api.md#host)
call defines two important configs: **alias** and **hostname**.

- **hostname** - used then connecting to remote host.
- **alias** - used as a key in `Deployer::get()->hosts` collection.

```php
task('test', function () {
    writeln('The {{alias}} is {{hostname}}');
});
```

```
$ dep test
[example.org] The example.org is example.org
```

We can override hostname via `set()` method:

```php
host('example.org')
    ->set('hostname', 'example.cloud.google.com');
```

Now new hostname will be used for ssh connect, and host will be referred in
Deployer via the alias.

```
$ dep test
[example.org] The example.org is example.cloud.google.com
```

Another important ssh connection parameter is `remote_user`.

```php
host('example.org')
    ->set('hostname', 'example.cloud.google.com');
    ->set('remote_user', 'deployer');
```

Now Deployer will be using something
like `ssh deployer@example.cloud.google.com`
for establishing connection.

Also, Deployer's `Host` class has special setter methods (for better IDE
autocompletion).

```php
host('example.org')
    ->setHostname('example.cloud.google.com');
    ->setRemoteUser('deployer');
```

:::info Config file
It is a good practice to keep connection parameters out of `deploy.php` file, as
they can change depending on where are deploy executed. Only specify `hostname`
and `remote_user` and other keep in `~/.ssh/config`:

```
Host *
  IdentityFile ~/.ssh/id_rsa
```
:::

## Host config

|Method|Value|
|------|-----|
|`setHostname` | The `hostname` |
|`setRemoteUser` | The `remote_user` |
|`setPort` | The `port` |
|`setConfigFile` | For example, `~/.ssh/config`. |
|`setIdentityFile` | For example, `~/.ssh/id_rsa`. |
|`setForwardAgent` | Default: `true`. |
|`setSshMultiplexing` | Default: `true`. |
|`setShell` | Default: `bash -ls`. |
|`setDeployPath` | For example, `~/myapp`. |
|`setLabels` | Key-value pairs for host selector. |
|`setSshArguments` | For example, `['-o UserKnownHostsFile=/dev/null']` |

## Multiple hosts

You can pass multiple hosts to the host function:

```php
host('example.org', 'deployer.org', ...)
    ->setRemoteUser('anton');
```

## Host ranges

If you have a lot of hosts following similar patterns, you can describe them 
like this rather than listing each hostname:

```php
host('www[01:50].example.org');
```

For numeric patterns, leading zeros can be included or removed, as desired. 
Ranges are inclusive.

You can also define alphabetic ranges:

```php
host('db[a:f].example.org');
```

## Localhost

A special function [localhost()](api.md#localhost) defines a special local host.
Deployer will not connect to this host and will execute commands locally.

```php
localhost(); // Alias and hostname will be "localhost".
localhost('ci'); // Alias is "ci", hostname is "localhost".
```

## YAML Inventory

You can use [import()](api.md#import) function to keep host separately in, for
example, *inventory.yaml* file.

```php title="deploy.php"
import('inventory.yaml');
```

```yaml title="inventory.yaml"
hosts:
  example.org:
    remote_user: deployer
  deployer.org:
    remote_user: deployer
```