Skip to main content
Version: 6.x


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('')    ->stage('production')    ->roles('app')    ->set('deploy_path', '~/app');

Host 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:  stage: production  roles: app  deploy_path: ~/app

Then to deploy.php:


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('')    ->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('');    $port = $host->getPort();});

Multiple hosts#

You can pass multiple hosts to the host function:

host('', '', '', ...)    ->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:


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

You can also define alphabetic ranges:



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('', '')    ->set('deploy_path', '~/{{hostname}}')    ...

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

~└──    β”œβ”€β”€ 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('')    ->set('deploy_path', '~/');    host('beta')    ->hostname('')    ->set('deploy_path', '~/');    

Now you can deploy with these commands:

dep deploy productiondep deploy beta

Inventory file#

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


Here an example of an inventory file hosts.yml with the full set of configuration settings  hostname:  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  ...  <<: *base  stage: production  <<: *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  ...


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

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

Deployer uses sudo privilege escalation method by default.

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

Next: deployment flow.