Skip to main content
Version: 6.x

Hosts

Defining a host in Deployer is necessary to deploy your application. It can be a remote machine, a local machine or Amazon EC2 instances. Each host contains a hostname, a stage, one or more roles and configuration parameters.

You can define hosts with the host function in deploy.php file. Here is an example of a host definition:

host('domain.com')
->stage('production')
->roles('app')
->set('deploy_path', '~/app');

Host domain.com has stage production, one role app and a configuration parameter deploy_path = ~/app.

Hosts can also be described by using yaml syntax. Write this in a hosts.yml file:

domain.com:
stage: production
roles: app
deploy_path: ~/app

Then to deploy.php:

inventory('hosts.yml');

Make sure that your ~/.ssh/config file contains information about your domains and how to connect. Or you can specify that information in the deploy.php file itself.

host('domain.com')
->user('name')
->port(22)
->configFile('~/.ssh/config')
->identityFile('~/.ssh/id_rsa')
->forwardAgent(true)
->multiplexing(true)
->addSshOption('UserKnownHostsFile', '/dev/null')
->addSshOption('StrictHostKeyChecking', 'no');

Best practice is to leave connecting information for hosts in the ~/.ssh/config file. That way you allow different users to connect in different ways.

Overriding config per host​

For example, if you have some global configuration you can override it per host:

set('branch', 'master');

host('prod')
...
->set('branch', 'production');

Now onthe prod host the branch is set to production, on others to master.

Gathering host info​

Inside any task, you can get host config with the get function, and the host object with the host function.

task('...', function () {
$deployPath = get('deploy_path');

$host = host('domain.com');
$port = $host->getPort();
});

Multiple hosts​

You can pass multiple hosts to the host function:

host('110.164.16.59', '110.164.16.34', '110.164.16.50', ...)
->stage('production')
...

If your inventory hosts.yml file contains multiple, you can change the config for all of them in the same way.

inventory('hosts.yml')
->roles('app')
...

Host ranges​

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

host('www[01:50].domain.com');

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

You can also define alphabetic ranges:

host('db[a:f].domain.com');

Localhost​

If you need to build your release before deploying on a remote machine, or deploy to localhost instead of remote, you need to define localhost:

localhost()
->stage('production')
->roles('test', 'build')
...

Host aliases​

If you want to deploy an app to one host, but for example in different directories, you can describe two host aliases:

host('domain.com/green', 'domain.com/blue')
->set('deploy_path', '~/{{hostname}}')
...

For Deployer, those hosts are different ones, and after deploying to both hosts you will see this directory structure:

~
└── domain.com
β”œβ”€β”€ green
β”‚ └── ...
└── blue
└── ...

One host for a few stages​

Often you have only one server for prod and beta stages. You can easily configure them:

host('production')
->hostname('domain.com')
->set('deploy_path', '~/domain.com');

host('beta')
->hostname('domain.com')
->set('deploy_path', '~/beta.domain.com');

Now you can deploy with these commands:

dep deploy production
dep deploy beta

Inventory file​

Include hosts defined in inventory files hosts.yml by inventory function:

inventory('hosts.yml');

Here an example of an inventory file hosts.yml with the full set of configuration settings

domain.com:
hostname: domain.com
user: name
port: 22
configFile: ~/.ssh/config
identityFile: ~/.ssh/id_rsa
forwardAgent: true
multiplexing: true
sshOptions:
UserKnownHostsFile: /dev/null
StrictHostKeyChecking: no
stage: production
roles:
- app
- db
deploy_path: ~/app
extra_param: "foo {{hostname}}"

Note that, as with the host function in the deploy.php file, it's better to omit information such as user, port, identityFile, forwardAgent and use it from the ~/.ssh/config file instead.

If your inventory file contains many similar host definitions, you can use YAML extend syntax:

.base: &base
roles: app
deploy_path: ~/app
...

www1.domain.com:
<<: *base
stage: production

beta1.domain.com:
<<: *base
stage: beta

...

Hosts that start with . (dot) are called hidden and are not visible outside that file.

To define localhost in inventory files add a local key:

localhost:
local: true
roles: build
...

Become​

Deployer allows you to β€˜become’ another user, different from the user that logged into the machine (remote user).

host('domain.com')
->become('deployer')
...

Deployer uses sudo privilege escalation method by default.

Note that become doesn't work with tty run option.

Next: deployment flow.