Laravel (5.7) Laravel Envoy

Introduction

Laravel Envoy provides you with a clean, minimal syntax for defining common tasks you will run on your remote servers. Using the Blade style syntax, you can set up tasks easily for deployment, Artisan commands, and more. Currently, Envoy only has supports for the Mac and Linux operating systems.

Installation

First, you need to install Envoy using the Composer global require command:

composer global require laravel/envoy

Since global Composer libraries could sometimes cause package version conflicts, you may consider using cgr. cgr is a drop-in replacement for the composer global require command. The cgr library's installation instructions are available on GitHub.

Be sure to place the ~/.composer/vendor/bin directory in your PATH so the envoy executable is found when running the envoy command in your terminal.

Updating Envoy

You can also use Composer to keep your Envoy installation up to date. Issuing the composer global update command updates all of your globally installed Composer packages:

composer global update

Writing Tasks

All of your Envoy tasks have to be defined in an Envoy.blade.php file in the root of your project. This is an example to get you started:

@servers(['web' => ['[email protected]']])

@task('foo', ['on' => 'web'])
    ls -la
@endtask

As can be seen, an array of @servers has been defined at the top of the file, this allows you to reference these servers in the on option of your task declarations. Inside your @task declarations, you need to place the Bash code that should run on your server when the task is executed.

Forcing a script to run locally is done by specifying the server's IP address as 127.0.0.1:

@servers(['localhost' => '127.0.0.1'])

Setup

Sometimes, you may want to execute some PHP code before executing your Envoy tasks. You can use the @setup directive to declare variables and do any other general PHP work before any of your other tasks are executed:

@setup
    $now = new DateTime();

    $environment = isset($env) ? $env : "testing";
@endsetup

If you need to require other PHP files before your task is executed, you may use the @include directive at the top of your Envoy.blade.php file:

@include('vendor/autoload.php')

@task('foo')
    # ...
@endtask

Variables

If needed, you can pass option values into Envoy tasks using the command line:

envoy run deploy --branch=master

You can access the options in your tasks via Blade's "echo" syntax. You can also use if statements and loops within your tasks. For instance, let us verify the presence of the $branch variable before executing the git pull command:

@servers(['web' => '192.168.1.1'])
@task('deploy', ['on' => 'web'])
    cd site
    @if ($branch)
        git pull origin {{ $branch }}
    @endif
    php artisan migrate
@endtask

Stories

Stories will group a set of tasks under a single, convenient name, this allows you to group small, focused tasks into large tasks. For example, a deploy story can run the git and composer tasks by listing the task names within its definition:

@servers(['web' => '192.168.1.1'])

@story('deploy')
    git
    composer
@endstory

@task('git')
    git pull origin master
@endtask

@task('composer')
    composer install
@endtask

Once the story is written, you can run it just like a typical task:

envoy run deploy

Multiple Servers

Envoy will allow you to easily run a task across multiple servers. First, you need to add additional servers to your @servers declaration. Each server has to be assigned a unique name. Immediately you define your additional servers, you should list each of the servers in the task's on the array:

@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])
@task('deploy', ['on' => ['web-1', 'web-2']])
    cd site
    git pull origin {{ $branch }}
    php artisan migrate
@endtask

Parallel Execution

By default, tasks are executed on each server serially. This means, a task will have to finish running on the first server before proceeding to execute on the second server. If you want to run a task across multiple servers in parallel, you need to add the parallel option to your task declaration:

@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])

@task('deploy', ['on' => ['web-1', 'web-2'], 'parallel' => true])
    cd site
    git pull origin {{ $branch }}
    php artisan migrate
@endtask

Running Tasks

If you want to run a task or story that is defined in your Envoy.blade.php file, you should execute Envoy's run command, passing the name of the task or story you want to execute. Envoy runs the task and displays the output from the servers as the task is running:

envoy run task

Confirming Task Execution

We always want to receive an acknowledge from a system, when we write an instruction that needs to be executed.

In Envoy, if you want to be prompted for confirmation before running a given task on your servers, you need to add the confirm directive to your task declaration. This option is very useful for destructive operations:

@task('deploy', ['on' => 'web', 'confirm' => true])
    cd site
    git pull origin {{ $branch }}
    php artisan migrate
@endtask

Notifications

Slack

Envoy equally supports sending notifications to Slack after each task has been executed. The @slack directive will accept a Slack hook URL and a channel name. You can retrieve your webhook URL by creating an "Incoming WebHooks" integration in your Slack control panel. You have to pass the entire webhook URL into the @slack directive:

@finished
    @slack('webhook-url', '#bots')
@endfinished

You can provide one of the following as the channel argument:

• To send a notification to a channel: #channel
• To send a notification to a user: @user