Введение
Laravel Envoy обеспечивает чистый и минималистичный синтаксис для регистрации общих задач, запускаемых на удалённых серверах. Используя синтаксис в стиле Blade, вы легко можете настроить задачи для развёртывания, Artisan-команды и прочее. На данный момент Envoy работает только на ОС Mac/Linux.
Установка
Сначала установите Envoy с помощью команды Composer shglobal require
:
shcomposer global require "laravel/envoy=~1.0"
Поскольку из-за глобальных библиотек Composer иногда могут возникать конфликты версий пакетов, вы можете использовать cgr, являющийся полноценной заменой для команды shcomposer global require
. Инструкции по установке библиотеки cgr можно найти на GitHub.
Не забудьте поместить каталог ~/.composer/vendor/bin в вашу переменную PATH, чтобы исполняемый файл envoy мог быть найден при запуске команды shenvoy
в терминале.
Также вы можете использовать Composer для обновления вашего Envoy. Выполнение команды shcomposer global update
обновит все ваши установленные глобально пакеты Composer:
shcomposer global update
добавлено в 5.0 ()
Написание задач
Все ваши Envoy-задачи должны быть определены в файле Envoy.blade.php в корне вашего проекта. Вот пример для начала:
@servers(['web' => ['user@192.168.1.1']])
@task('foo', ['on' => 'web'])
ls -la
@endtask
Как видите, массив @servers определён в начале файла. Вы можете ссылаться на эти сервера в параметре on при объявлении задач. Поместите в ваши объявления @task тот Bash-код, который должен запускаться на сервере при исполнении задачи.
Начальная настройка
Иногда необходимо выполнить некий PHP-код перед выполнением ваших Envoy-задач. Для объявления переменных и выполнения других общих PHP-задач перед выполнением всех остальных ваших задач вы можете использовать директиву @setup:
@setup
$now = new DateTime();
$environment = isset($env) ? $env : "testing";
@endsetup
Если вам необходимо подключить другие PHP-файлы перед выполнением задачи, используйте директиву @include в начале файла Envoy.blade.php:
@include('vendor/autoload.php');
@task('foo')
# ...
@endtask
Переменные
При необходимости вы можете передать значения параметров в Envoy-задачи с помощью командной строки:
shenvoy 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
добавлено в 5.3 ()
Само собой, вы также можете использовать операторы PHPif
и циклы в своих задачах. Например, давайте проверим наличие переменной PHP$branch
перед выполнением команды shgit 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 — набор задач под единым удобным именем, который позволяет вам сгруппировать маленькие узконаправленные задачи в одну большую задачу. Например, группа deploy может запустить задачи git и composer, если указать имена этих задач в её описании:
@servers(['web' => '192.168.1.1'])
@story('deploy')
git
composer
@endstory
@task('git')
git pull origin master
@endtask
@task('composer')
composer install
@endtask
Теперь группа deploy может быть запущена как обычная задача:
shenvoy run deploy
добавлено в 5.2 () 5.1 () 5.0 ()
Макрос задач
Макрос позволяет вам определить набор задач, которые будут запускаться последовательно с помощью одной команды. Например, макрос deploy может запустить задачи git и composer:
@servers(['web' => '192.168.1.1'])
@macro('deploy')
git
composer
@endmacro
@task('git')
git pull origin master
@endtask
@task('composer')
composer install
@endtask
Теперь макрос deploy может быть запущен одной простой командой:
shenvoy run deploy
Несколько серверов
Благодаря Envoy вы легко можете запускать задачи на нескольких серверах. Сначала добавьте дополнительные сервера в объявление @servers. Каждому серверу должно быть присвоено уникальное имя. Когда вы определили дополнительные сервера, перечислите каждый из них в массиве задачи 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
По умолчанию задачи будут выполняться на каждом сервере поочерёдно. То есть задача будет завершаться на первом сервере перед переходом к выполнению на следующем.
Если вы хотите запускать задачи на нескольких серверах параллельно, просто добавьте параметр 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
Запуск задач
Для запуска задачи или группы задач из файла Envoy.blade.php используйте Envoy-команду shrun
вашего Envoy, передавая ей название задачи или группы задач для запуска. Envoy запустит задачу и выведет ответ от серверов, когда задача будет запущена:
shenvoy run task
Запрос подтверждения перед запуском задач
Если хотите получать запрос на подтверждение перед запуском определённой задачи на ваших серверах, добавьте директиву confirm в определение вашей задачи. Этот параметр полезен в основном для необратимых операций:
@task('deploy', ['on' => 'web', 'confirm' => true])
cd site
git pull origin {{ $branch }}
php artisan migrate
@endtask
Оповещения
Slack
Envoy также поддерживает отправку оповещений в Slack после выполнения каждой команды.
добавлено в 5.3 ()
Вы можете получить URL вашего webhook, создав на сайте Slack интеграцию «Incoming WebHooks». Аргумент 'hook' должен содержать полный полученный URL вашего webhook. Например:
https://hooks.slack.com/services/ZZZZZZZZZ/YYYYYYYYY/XXXXXXXXXXXXXXX
А в качестве аргумента 'channel' может быть:
- #channel — для отправки уведомлений на канале
- @user — для отправки уведомлений пользователю
добавлено в 5.2 () 5.1 () 5.0 ()
HipChat
Вы можете посылать оповещение в чат HipChat своей команды после запуска задачи с помощью простой директивы @hipchat. Директива принимает токен API, название чата, и имя отправителя сообщения:
@servers(['web' => '192.168.1.1'])
@task('foo', ['on' => 'web'])
ls -la
@endtask
@after
@hipchat('token', 'room', 'Envoy')
@endafter
Вы также можете задать своё собственное сообщение в чат HipChat, в котором можете использовать любые переменные, доступные вашим Envoy-задачам:
добавлено в 5.2 ()
@after
@hipchat('token', 'room', 'Envoy', "$task ran in the $env environment.")
@endafter