{{TOC}}

{{DOCVER 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15, 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11}}

== Введение ==
((https://github.com/laravel/envoy Laravel Envoy)) обеспечивает чистый и минималистичный синтаксис для регистрации общих задач, запускаемых на удалённых серверах. Используя синтаксис в стиле ((/docs/v5/templates#blade Blade)), вы легко можете настроить задачи для развёртывания, Artisan-команды и прочее. На данный момент Envoy работает только на ОС Mac/Linux.

=== Установка ===
Сначала установите Envoy с помощью команды Composer %%(sh)global require%%:
%%(sh)
composer global require "laravel/envoy=~1.0"
%%

Поскольку из-за глобальных библиотек Composer иногда могут возникать конфликты версий пакетов, вы можете использовать %%(t)cgr%%, являющийся полноценной заменой для команды %%(sh)composer global require%%. Инструкции по установке библиотеки %%(t)cgr%% можно найти на ((https://github.com/consolidation-org/cgr GitHub)).

.(alert)
Не забудьте поместить каталог %%(t)~/.composer/vendor/bin%% в вашу переменную %%(t)PATH%%, чтобы исполняемый файл %%(t)envoy%% мог быть найден при запуске команды %%(sh)envoy%% в терминале.

**Обновление Envoy**

Также вы можете использовать Composer для обновления вашего Envoy. Выполнение команды %%(sh)composer global update%% обновит все ваши установленные глобально пакеты Composer:
%%(sh)
composer global update
%%

%%(DOCNEW 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
Для простого создания стаб-файла Envoy используйте команду %%(sh)init%%:
%%(sh)
envoy init user@192.168.1.1
~%%
%%

== Написание задач ==
Все ваши Envoy-задачи должны быть определены в файле %%(t)Envoy.blade.php%% в корне вашего проекта. Вот пример для начала:
%%
@servers(['web' => ['user@192.168.1.1']])

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

Как видите, массив %%(t)@servers%% определён в начале файла. Вы можете ссылаться на эти сервера в параметре %%(t)on%% при объявлении задач. Поместите в ваши объявления %%(t)@task%% тот Bash-код, который должен запускаться на сервере при исполнении задачи.

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
Вы можете задать локальное выполнение скрипта, указав IP-адрес сервера %%(t)127.0.0.1%%:
~%%
@servers(['localhost' => '127.0.0.1'])
~%%
%%

=== Начальная настройка ===
Иногда необходимо выполнить некий PHP-код перед выполнением ваших Envoy-задач. Для объявления переменных и выполнения других общих PHP-задач перед выполнением всех остальных ваших задач вы можете использовать директиву %%(t)@setup%%:
%%
@setup
  $now = new DateTime();

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

Если вам необходимо подключить другие PHP-файлы перед выполнением задачи, используйте директиву %%(t)@include%% в начале файла %%(t)Envoy.blade.php%%:
%%
@include('vendor/autoload.php');

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

=== Переменные ===
При необходимости вы можете передать значения параметров в Envoy-задачи с помощью командной строки:
%%(sh)
envoy run deploy --branch=master
%%

Вы можете обращаться к параметрам в своих задачах с помощью Blade-синтаксиса "echo":
%%
  @servers(['web' => '192.168.1.1'])

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

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51)
Само собой, вы также можете использовать операторы %%if%% и циклы в своих задачах. Например, давайте проверим наличие переменной %%$branch%% перед выполнением команды %%(sh)git pull%%:
~%%
@servers(['web' => '192.168.1.1'])

@task('deploy', ['on' => 'web'])
  cd site

  @if ($branch)
    git pull origin {{ $branch }}
  @endif

  php artisan migrate
@endtask
~%%

=== Группа Story ===
Группа Story - набор задач под единым удобным именем, который позволяет вам сгруппировать маленькие узконаправленные задачи в одну большую задачу. Например, группа %%(t)deploy%% может запустить задачи %%(t)git%% и %%(t)composer%%, если указать имена этих задач в её описании:
~%%
@servers(['web' => '192.168.1.1'])

@story('deploy')
  git
  composer
@endstory

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

@task('composer')
  composer install
@endtask
~%%

Теперь группа %%(t)deploy%% может быть запущена как обычная задача:
%%(sh)
envoy run deploy
~%%
%%

%%(DOCNEW 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15, 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
=== Макрос задач ===
Макрос позволяет вам определить набор задач, которые будут запускаться последовательно с помощью одной команды. Например, макрос %%(t)deploy%% может запустить задачи %%(t)git%% и %%(t)composer%%:
~%%
@servers(['web' => '192.168.1.1'])

@macro('deploy')
  git
  composer
@endmacro

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

@task('composer')
  composer install
@endtask
~%%

Теперь макрос %%(t)deploy%% может быть запущен одной простой командой:
%%(sh)
envoy run deploy
~%%
%%

=== Несколько серверов ===
Благодаря Envoy вы легко можете запускать задачи на нескольких серверах. Сначала добавьте дополнительные сервера в объявление %%(t)@servers%%. Каждому серверу должно быть присвоено уникальное имя. Когда вы определили дополнительные сервера, перечислите каждый из них в массиве задачи %%(t)on%%:
%%
@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
%%

**Параллельное выполнение**

По умолчанию задачи будут выполняться на каждом сервере поочерёдно. То есть задача будет завершаться на первом сервере перед переходом к выполнению на следующем.

Если вы хотите запускать задачи на нескольких серверах параллельно, просто добавьте параметр %%(t)parallel%% в объявление задач:
%%
@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
%%

== Запуск задач ==
Для запуска задачи или группы задач из файла %%(t)Envoy.blade.php%% используйте Envoy-команду %%(sh)run%% вашего Envoy, передавая ей название задачи или группы задач для запуска. Envoy запустит задачу и выведет ответ от серверов, когда задача будет запущена:
%%(sh)
envoy run task
%%

=== Запрос подтверждения перед запуском задач ===
Если хотите получать запрос на подтверждение перед запуском определённой задачи на ваших серверах, добавьте директиву %%(t)confirm%% в определение вашей задачи. Этот параметр полезен в основном для необратимых операций:
%%
@task('deploy', ['on' => 'web', 'confirm' => true])
  cd site
  git pull origin {{ $branch }}
  php artisan migrate
@endtask
%%

== Оповещения ==
=== Slack ===
Envoy также поддерживает отправку оповещений в ((https://slack.com Slack)) после выполнения каждой команды.
%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51)
Директива %%(t)@slack%% принимает URL Slack-hook и название канала:
~%%
@finished
  @slack('webhook-url', '#bots')
@endfinished
~%%
%%

%%(DOCNEW 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15, 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
Директива %%(t)@slack%% принимает URL Slack-hook, название канала и сообщение:
~%%
@after
  @slack('hook', 'channel', 'message')
@endafter
~%%
%%

Вы можете получить URL вашего webhook, создав на сайте Slack интеграцию "Incoming WebHooks". Аргумент %%(t)'hook'%% должен содержать полный полученный URL вашего webhook. Например:
%%(t)
https://hooks.slack.com/services/ZZZZZZZZZ/YYYYYYYYY/XXXXXXXXXXXXXXX
%%

А в качестве аргумента %%(t)'channel'%% может быть:
  - %%(t)#channel%% - для отправки уведомлений на канале
  - %%(t)@user%% - для отправки уведомлений пользователю

%%(DOCNEW 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15, 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
===HipChat===
Вы можете посылать оповещение в чат HipChat своей команды после запуска задачи с помощью простой директивы %%(t)@hipchat%%. Директива принимает токен API, название чата, и имя отправителя сообщения:
~%%
@servers(['web' => '192.168.1.1'])

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

@after
  @hipchat('token', 'room', 'Envoy')
@endafter
~%%

Вы также можете задать своё собственное сообщение в чат HipChat, в котором можете использовать любые переменные, доступные вашим Envoy-задачам:
%%

%%(DOCNEW 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
~%%
@after
  @hipchat('token', 'room', 'Envoy', "$task ran in the $env environment.")
@endafter
~%%
%%

%%(DOCNEW 5.1=f60f8b3697b3ffe381df4ddb7e2875ffce940643 1.04.2016 17:39:10, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
~%%
@after
  @hipchat('token', 'room', 'Envoy', "{{ $task }} ran in the {{ $env }} environment.")
@endafter
~%%
%%