Skip to content

hosts.md

Latest commit

 

History

History
195 lines (137 loc) · 5.5 KB

hosts.md

File metadata and controls

195 lines (137 loc) · 5.5 KB

Hosts

Define hosts with host().

Defining a Host

host('example.org');

Hosts hold key-value config. Each host gets two keys for free:

  • hostname — used for the SSH connection.
  • alias — unique identifier in the recipe.

Reading Host Configurations

Read host config inside a task with currentHost():

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

Or with {{...}} interpolation:

task('test', function () {
    writeln('The {{alias}} is {{hostname}}');
});
$ dep test
[example.org] The example.org is example.org

Overriding Hostname

Override hostname to connect to a different address than the alias suggests:

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

The alias stays example.org; SSH connects to example.cloud.google.com.

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

Configuring Remote User

Set remote_user to choose the SSH user:

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

Connection becomes ssh deployer@example.cloud.google.com.

The typed setter methods give better IDE autocompletion:

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

Host Labels

Labels are key-value tags used to group hosts:

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

They scale to multi-server fleets:

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

Filter at deploy time with a selector:

$ dep deploy stage=prod&role=web,role=special
  • & — all conditions must match the same host (AND).
  • , — match either group (OR).

Set a default selector:

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

Host Configurations

Key Host Configurations

Config Key Description
alias Identifier for the host (e.g., prod, staging).
hostname Actual hostname or IP address used for SSH connections.
remote_user SSH username. Defaults to the current OS user or ~/.ssh/config.
port SSH port. Default is 22.
config_file SSH config file location. Default is ~/.ssh/config.
identity_file SSH private key file. E.g., ~/.ssh/id_rsa.
forward_agent Enable SSH agent forwarding. Default is true.
ssh_multiplexing Enable SSH multiplexing for performance. Default is true.
shell Shell to use. Default is bash -ls.
deploy_path Directory for deployments. E.g., ~/myapp.
labels Key-value pairs for host selection.
ssh_arguments Additional SSH options. E.g., ['-o UserKnownHostsFile=/dev/null'].
ssh_control_path Control path for SSH multiplexing. Default is ~/.ssh/%C or /dev/shm/%C in CI environments.

Best Practices

Keep sensitive SSH parameters out of deploy.php. Put them in ~/.ssh/config instead:

Host *
  IdentityFile ~/.ssh/id_rsa

Advanced Host Definitions

Multiple Hosts

Define several hosts with shared config in one call:

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

Host Ranges

Expand a range into many hosts:

host('www[01:50].example.org'); // www01.example.org … www50.example.org
host('db[a:f].example.org');    // dba.example.org … dbf.example.org

Numeric ranges keep leading zeros; alphabetic ranges work too.

Localhost

Run commands on the local machine with localhost():

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

run() then executes locally. runLocally() does the same without needing a localhost host.

YAML Inventory

Move host definitions to a separate file and pull them in with import():

import('inventory.yaml');
hosts:
  example.org:
    remote_user: deployer
  deployer.org:
    remote_user: deployer