[Laravel 5.2 Documentation] service--Envoy Task Runner

1. Introduction

Laravel envoy provides a clean and simplified set of syntax for defining common tasks that run on remote hosts. With blade style syntax, you can easily set tasks for development, artisan commands, and more, currently, Envoy only supports MAC and Linux operating systems.

1.1 Installation

First, install Envoy using the Composer Global command:

Composer global require "laravel/envoy=~1.0"

Make sure that the ~/.composer/vendor/bin directory is in the system path or that the command cannot be executed in the terminal because envoy is not found.

Update envoy

You can also use Composer to keep the Envoy installed as the latest version:

Composer Global Update

2. Writing tasks

All Envoy tasks are defined in the Envoy.blade.php file under the project root, and here is an example that lets you begin:

@servers ([' web ' = ' user@192.168.1.1 ']) @task (' foo ', [' on ' = ' web '])    Ls-la@endtask

As you can see, the @servers array is defined at the top of the file, allowing you to refer to these servers using the on option in the task Declaration, and in @task declaration, you should place the bash code that will run on the server.

Start

Sometimes you need to execute some PHP code before evaluating the envoy task, and you can use the @setup directive in the envoy file to declare variables and the PHP code to execute:

@setup    $now = new DateTime ();    $environment = Isset ($env)? $ENV: "Testing"; @endsetup

You can also use @include to introduce external PHP files:

@include (' vendor/autoload.php ');

Confirm Task

If you want to pop up a pop-up prompt for confirmation before running a given task on the server, you can use the Confirm directive in the task statement:

@task (' Deploy ', [' on ' + ' web ', ' confirm ' = ' = True])    CD site    Git pull origin {{$branch}}    php artisan mi Grate@endtask

2.1 Task variables

If necessary, you can use command-line switches to pass variables to the envoy file, allowing you to customize the task:

Envoy Run Deploy--branch=master

You can use this option with the Blade "echo" syntax in a task:

@servers ([' web ' = ' 192.168.1.1 ']) @task (' Deploy ', [' on ' = ' web '])    CD site    Git pull origin {{$branch}}
  php Artisan Migrate@endtask

2.2 + Servers

You can easily run the same task on multiple hosts, first, add additional servers to the @servers declaration, and each server should be assigned a unique name. Once you have defined the server, simply list all the servers in the task declaration:

@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

By default, the task executes on each server in turn, which means that the task will not start running on the second server until it finishes running on the first server.

Run parallel

If you want to run parallel on multiple servers, add the parallel option to the 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

2.3 Task macros

Macros allow you to define multiple, sequential tasks using a single command. For example, the Deploy macro will run the Git and composer tasks:

@servers ([' web ' = ' 192.168.1.1 ']) @macro (' deploy ')    git    composer@endmacro@task (' git ')    git pull Origin Master@endtask@task (' composer ')    composer Install@endtask

Once the macro is defined, you can run it by following a single command:

Envoy Run Deploy

3. Running Tasks

To run a task from a Envoy.blade.php file, you need to execute the Envoy Run command, and then pass the command name or macro of the task you want to perform. Envoy will run the command and print the output from the service:

Envoy Run Task

4. Notice

4.1 Hipchat

After running a task, you can use Envoy's @hipchat directive to send a notification to the team's Hipchat room, which receives an API token, room name, and user name:

@servers ([' web ' = ' 192.168.1.1 ']) @task (' foo ', [' on ' + ' web '])    ls-la@endtask@after    @hipchat (' token ', ' Guest ', ' Envoy ') @endafter

If you want, you can also pass a custom message to the Hipchat room, and all the variables that are valid in the envoy task are also valid when building the message:

@after    @hipchat (' token ', ' guest ', ' Envoy ', ' {$task} ran in the {$env} environment. ') @endafter

4.2 Slack

In addition to Hipchat, Envoy also supports sending notifications to Slack. The @slack instruction receives a slack hook URL, a channel name, and the message you want to send to the channel:

@after    @slack (' Hook ', ' channel ', ' message ') @endafter

You can get the hook URL by creating a Incoming Webhooks integrated into the Slack website, which is a complete Webhooks URL provided by Incoming Slack Webhook integration, for example:

Https://hooks.slack.com/services/ZZZZZZZZZ/YYYYYYYYY/XXXXXXXXXXXXXXX

You can provide one of the following two types of channel parameters:

• Send Message to channel: #channel
• Send message to User: @user

