Skip to main content
Version: 7.x

Getting Started

Deployer consists of two main parts: core task runner and recipes.

First, install the Deployer.

Let's create our first recipe! Create a file named deploy.php and define our first task and one host we are going to deploy to:

<?phpnamespace Deployer;
task('hello', function () {    run('ls -1');});

We are using namespace Deployer as we're going to primarily use functions defined in this namespace.

Read more about task's definitions.

Now let's run our task:

$ dep hellotask hello

What just happen? Deployer connected to and executed ls -1 command. Let's count how many files ls command returned:

task('hello', function () {    $output = run('ls -1');    $lines = substr_count($output, "\n");    writeln("Total files: $lines");});
$ dep hellotask hello[] Total files: 4

Awesome! But let's debug our task and take a look what ls -1 command actually returned. We can place writeln($output) call in our task, but there is an easier way: just add -v option:

$ dep hello -vtask hello[] run ls -1[] dev[][][][] Total files: 4

Adding -v option instructs Deployer to print each commands it executes with it's output. Looks like our task is executed in wrong directory. Let's cd to correct one:

task('hello', function () {+   cd('~/');    $output = run('ls -1');    $lines = substr_count($output, "\n");    writeln("Total files: $lines");});

Tasks and hosts are two main concepts of Deployer. We define what to do in tasks and hosts define there to run it. Now let's add another host to run out task on:


Read more about host's definition.

Now let's run dep hello again. This time Deployer will ask us what hosts do we intend to run on. Let's run this command again this time with special selector all which indicated what we're planning to run our task on all defined hosts.

$ dep hello alltask hello[] Total files: 15[] error in deploy.php on line 8:[] run cd ~/ && (ls -1)[] err bash: line 1: cd: /home/deployer/ [] err bash: No such file or directory[] exit code 1 (General error)

That's right. There is no ~/ dir on our beta host. To fix it we need to cd in correct dir on each host. To do that, let's define config per host.

Each host has own configuration parameters. To access it inside task use get()/set() functions. Also, each Deployer function can parse config parameters via {{...}} syntax.

Read more about host's configuration.

host('')    ->set('my_path', '~/');host('')    ->set('my_path', '~/');

And let's use this config in our task:

task('hello', function () {-   cd('~/');+   cd(get('my_path'));    $output = run('ls -1');    $lines = substr_count($output, "\n");    writeln("Total files: $lines");});

Let's test it:

$ dep hello alltask hello[] Total files: 15[] Total files: 15

Success! This is a basics of Deployer. We can define hosts with config and tasks. Using those we can create our own deployment recipes.

Deployer comes with a bunch of recipes for most popular frameworks. Let's use, for example, Laravel recipe to deploy our Laravel project.

$ dep init

Follow instructions, choose one of types for your recipe: php or yaml. Read more about writing yaml recipes here. Let's choose php recipe for our case.

You can mix php and yaml recipes. For example, you can add yaml recipe to your php recipe via import() function, or import php recipes from yaml recipe.

Let's take a look on generated deploy.php recipe. It requires Laravel recipe:

require 'recipe/laravel.php';

In recipes, you can use require to import recipes defined in recipes and contrib dirs. But you can always require recipes by absolute path.

Then there are three sections: config, hosts and tasks. All other tasks defined in Laravel or in common recipes. To get list of all possible tasks let's run dep without any arguments:

$ depAvailable commands:  deploy                     Deploy your project  init                       Initialize deployer in your project  rollback                   Rollback to previous release  run                        Run any arbitrary command on hosts  ssh                        Connect to host through ssh  status                     Show releases status  tree                       Display the task-tree for a given task artisan  artisan:cache:clear        Flush the application cache  ... deploy  deploy:update_code         Updates code  ...

Let's see what task defined in deploy task via dep tree command:

$ dep tree deployThe task-tree for deploy:โ””โ”€โ”€ deploy    โ”œโ”€โ”€ deploy:prepare    โ”‚   โ”œโ”€โ”€ deploy:info    โ”‚   โ”œโ”€โ”€ deploy:setup    โ”‚   โ”œโ”€โ”€ deploy:lock    โ”‚   โ”œโ”€โ”€ deploy:release    โ”‚   โ”œโ”€โ”€ deploy:update_code    โ”‚   โ”œโ”€โ”€ deploy:shared    โ”‚   โ””โ”€โ”€ deploy:writable    โ”œโ”€โ”€ deploy:vendors    โ”œโ”€โ”€ artisan:storage:link    โ”œโ”€โ”€ artisan:view:cache    โ”œโ”€โ”€ artisan:config:cache    โ””โ”€โ”€ deploy:publish        โ”œโ”€โ”€ deploy:symlink        โ”œโ”€โ”€ deploy:unlock        โ”œโ”€โ”€ deploy:cleanup        โ””โ”€โ”€ deploy:success

We can override deploy task if we want to in our recipe:

task('deploy', [    'deploy:prepare',    'deploy:vendors',    'artisan:storage:link',    'artisan:view:cache',    'artisan:config:cache',    'deploy:publish',    'my_task',]);

Or we can use hooks to add our own tasks:

after('deploy', 'my_task');

Let's try to connect to host via dep command:

dep ssh

If everything went well we now can deploy our application:

$ dep deploy[] info deploying HEADtask deploy:setuptask deploy:locktask deploy:releasetask deploy:update_codetask deploy:sharedtask deploy:writabletask deploy:vendorstask artisan:storage:linktask artisan:view:cachetask artisan:config:cachetask deploy:symlinktask deploy:unlocktask deploy:cleanup[] info successfully deployed!