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
It will be nice if you may share this link in any developer community or anywhere else, from where other developers may find this content. Thanks.
https://www.w3resource.com/laravel/laravel-envoy.php
- Weekly Trends and Language Statistics
- Weekly Trends and Language Statistics