Servers

You can define servers with the server function. Here is an example of a server definition:

server('prod_1', 'domain.com')
    ->user('user')
    ->password('pass')
    ->set('deploy_path', '/home/www')
    ->stage('production');

server('prod_2', 'domain.com')
    ->user('user')
    ->password('pass')
    ->set('deploy_path', '/home/www')
    ->set('branch', 'master')
    ->set('extra_stuff', '...')
    ->stage('production');

This function takes 2 parameters, like this: server(server_name, host) (Port can be passed as 3rd parameter). It returns a Deployer\Server\Builder object.

To specify how to connect to a server using SSH, there are a few ways:

With a username and a password

server(...)
  ->user('name')
  ->password('pass')

With a username and a typed password

server(...)
  ->user('name')
  ->password(null)

Set password to null and it will be asked.

With an identity file

server(...)
    ->user('name')
    ->identityFile();

If your keys were created with a password or if they are located outside of the .ssh directory, you can specify the location by providing the full path:

server(...)
    ...
    ->identityFile('~/.ssh/id_rsa.pub', '~/.ssh/id_rsa', 'pass phrase');

2-factor authentication with an identity file and password or google-authenticator:

If your server is secured with 2-factor, you can connect via your private key + the second factor (password or google-authenticator). Note this the current version only supports PhpSecLib:

server(...)
    ->user('name')
    ->identityFileAndPassword();

As with the normal identityFile() call, if your keys were created with a password or if they are located outside of the .ssh directory, you can specify the location by providing the full path:

server(...)
    ...
    ->identityFileAndPassword('~/.ssh/id_rsa.pub', '~/.ssh/id_rsa', 'pass phrase', 'password');

The ~ symbol will be replaced with your home directory.

With a config file

Deployer can use your SSH config file.

server(...)
    ->user('name')
    ->configFile('/path/to/file');

With a pem file

server('ec2', 'host.aws.amazon.com')
    ->user('ec2-user')
    ->pemFile('~/.ssh/keys.pem');

Authentication using a pem file is currently only supported with PhpSecLib.

Using PHP SSH2 extension

Package herzult/php-ssh is required for this to work but is not included inside deployer.phar so you should install deployer/deployer and herzult/php-ssh using composer:

composer require deployer/deployer herzult/php-ssh

Example deploy.php file:

require 'vendor/autoload.php';
require 'vendor/deployer/deployer/recipe/symfony.php';

set('ssh_type', 'ext-ssh2');
//...

Upload and download

You can upload a file or directory with the upload(local, remote) function.

You can download a file with the download(local, remote) function.

Servers list

You can define servers in YAML file:

prod:
  host: domain.com
  user: www
  identity_file: ~
  stage: production
  deploy_path: /home/www/

prod.a:
  host: a.domain.com
  user: www
  identity_file:
    public_key:  /path/to/public.key
    private_key: /path/to/private.key
    password:    optional-password-for-private-key-or-null
  stage: production
  deploy_path: /home/www/  

beta:
  host: beta.domain.com
  user: www
  password: pass
  stage: beta
  deploy_path: /home/www/

test:
  host: test.domain.com
  user: www
  password: pass
  stage: beta
  deploy_path: /home/www/  

And then in deploy.php:

serverList('servers.yml');

Server list YAML file and server configuration

You can set config variables per server definition. When parsing server configurations, all keys other than the one listed below are treated as server config variables and can be retrieved using get('key') or {{ key }}:

  • local
  • host
  • port
  • identity_file
  • forward_agent
  • user
  • password
  • stage
  • pem_file

Local Server

Also, you can define localServer, it runs all commands locally without ssh.

localServer(...)
    ->stage('local');

In external .yml definition the keyword local:can be used.

development:
    local: true
    # ....

For instance, you can use it to update your local project.

Stages

You can define every server with a stage, or list of stages:

server(...)
    ->stage('prod');

server(...)
    ->stage(['prod', 'stage']);    

server(...)
    ->env('stages', ['stage']);    

And then you call command dep [task] [server or stage], it will be executed only on specified stage servers.

It is possible to specify a default stage that will be executed if you do not give a stage on the command line. You can do this by setting the default_stage parameter.

set('default_stage', 'staging'); 

If you run a command without specifying a stage or a default, it will be executed on the server without a specified stage.