Hosts

In Deployer, you define hosts using the host() function.

Defining a Host

host('example.org');

Each host is associated with configuration key-value pairs. When you define a host, two key configurations are set:

• hostname: Used for connecting to the remote host.
• alias: A unique identifier for the host in recipe.

Example: Using Host Configurations

You can access host configurations within tasks with the currentHost() function:

task('test', function () {
    $hostname = currentHost()->get('hostname');
    $alias = currentHost()->get('alias');
    writeln("The $alias is $hostname");
});

Or using brackets syntax:

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

Running the task:

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

Overriding Hostname

You can override the default hostname with the set() method:

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

Now the hostname is used for SSH connections, but the alias remains unchanged:

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

Configuring Remote User

Specify the remote_user to define which user to connect as:

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

Deployer will now connect using ssh [email protected].

Alternatively, you can use special setter methods for better IDE autocompletion:

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

Host Labels

Labels allow you to group and identify hosts for specific deployments. Labels are defined as key-value pairs:

host('example.org')->setLabels(['stage' => 'prod']);
host('staging.example.org')->setLabels(['stage' => 'staging']);

Labels become powerful in multi-server setups:

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']);

Filtering Hosts by Labels

When deploying, you can filter hosts using label selectors:

$ dep deploy stage=prod&role=web,role=special

• Use & to specify multiple labels that must match on the same host.
• Use , to separate multiple selections.

Set a default selection string for convenience:

set('default_selector', "stage=prod&role=web,role=special");

Host Configurations

Key Host Configurations

Best Practices

Avoid storing sensitive SSH connection parameters in deploy.php. Instead, configure them in ~/.ssh/config:

Host *
  IdentityFile ~/.ssh/id_rsa

Advanced Host Definitions

Multiple Hosts

Define multiple hosts in one call:

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

Host Ranges

For patterns with many hosts, use ranges:

host('www[01:50].example.org'); // Will define hosts "www01.example.org", "www02.example.org", etc.
host('db[a:f].example.org'); // Will define hosts "dba.example.org", "dbb.example.org", etc.

• Numeric ranges can include leading zeros.
• Alphabetic ranges are also supported.

Localhost

Use the localhost() function for local execution:

localhost(); // Alias and hostname are "localhost".
localhost('ci'); // Alias is "ci", hostname is "localhost".

Now run() will execute on command locally. Alternatively, you can use runLocally() function.

YAML Inventory

Separate host definitions into an external file using the import() function:

import('inventory.yaml');

hosts:
  example.org:
    remote_user: deployer
  deployer.org:
    remote_user: deployer

With these tools and configurations, you can manage and deploy to hosts effectively, whether it's a single server or a complex multi-host setup. Happy deploying!