Laravel Envoy для деплоя и обслуживания рабочих проектов на php-фреймворке Laravel. Официальная документация.

Информация о материале: Родительская категория: Документация Laravel 10 по-русски; Категория: Пакеты Laravel

Laravel Envoy — пакет управления, обслуживания и деплоя рабочих проектов на Laravel — Laravel Envoy — стандартный пакет управления развёртыванием проектов на Laravel

Введение

Laravel Envoy — это инструмент для выполнения стандартных задач на удаленных серверах. Используя синтаксис в стиле Blade, можно легко настраивать задачи для развертывания, команды Artisan и многое другое. В настоящее время Envoy поддерживает только операционные системы Mac и Linux. Однако поддержка Windows возможна с помощью WSL2.

Установка

В первую очередь установите Envoy в проект с помощью менеджера пакетов Composer:

composer require laravel/envoy --dev

После установки Envoy бинарный файл Envoy будет доступен в каталоге vendor/bin вашего приложения:

php vendor/bin/envoy

Написание задач

Определение задач

Задачи (task) — это основной конструктивный элемент Envoy. Задачи определяют команды оболочки, которые должны выполняться на удаленных серверах при их вызове. Например, можно определить задачу, выполняющую команду php artisan queue:restart на всех рабочих серверах вашего приложения.

Все задачи Envoy должны быть определены в файле Envoy.blade.php в корне вашего приложения. Ниже приведен пример для ознакомления:

@servers(['web' => ['user@192.168.1.1'], 'workers' => ['user@192.168.1.2']])
 
@task('restart-queues', ['on' => 'workers'])
    cd /home/user/example.com
    php artisan queue:restart
@endtask

Как видно, в самом начале файла определен массив @servers, позволяющий ссылаться на эти серверы через опцию on в объявлении задачи. Объявление @servers всегда должно располагаться в одной строке. Внутри объявления @task следует поместить команды командной строки, которые должны выполняться на серверах при вызове задачи.

Локальные задачи

Можно заставить скрипт выполняться на локальном компьютере, указав IP-адрес сервера как 127.0.0.1:

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

Импорт задач Envoy

Используя директиву @import, можно импортировать другие файлы Envoy, чтобы их истории и задачи были добавлены к существующим. После импорта файлов можно выполнять содержащиеся в них задачи так, как если бы они были определены в текущем файле Envoy:

@import('vendor/package/Envoy.blade.php')

Работа с несколькими серверами

Envoy позволяет с легкостью запускать задачу на нескольких серверах. Сначала добавьте дополнительные серверы в объявление @servers. Каждому серверу должно быть присвоено уникальное имя. После определения дополнительных серверов можно перечислить каждый из них в массиве on задачи:

@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])
 
@task('deploy', ['on' => ['web-1', 'web-2']])
    cd /home/user/example.com
    git pull origin {{ $branch }}
    php artisan migrate --force
@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 /home/user/example.com
    git pull origin {{ $branch }}
    php artisan migrate --force
@endtask

Настройка

Иногда перед запуском задач Envoy может потребоваться выполнить произвольный PHP-код. Для этого можно использовать директиву @setup, определяющую блок PHP-кода, который должен выполняться перед выполнением задач:

@setup
    $now = new DateTime;
@endsetup

Если перед выполнением задания необходимо вызвать другие PHP-файлы, можно использовать директиву @include в верхней части файла Envoy.blade.php:

@include('vendor/autoload.php')
 
@task('restart-queues')
    # ...
@endtask

Переменные

При необходимости в задачи Envoy можно передавать аргументы, указывая их в командной строке при вызове Envoy:

php vendor/bin/envoy run deploy --branch=master

Для доступа к опциям в задачах используется синтаксис Blade "echo". Также в задачах Blade можно определять операторы if и циклы. Например, проверим наличие переменной $branch перед выполнением команды git pull:

@servers(['web' => ['user@192.168.1.1']])
 
@task('deploy', ['on' => 'web'])
    cd /home/user/example.com
 
    @if ($branch)
        git pull origin {{ $branch }}
    @endif
 
    php artisan migrate --force
@endtask

Истории (Stories)

Истории группируют наборы задач под одним удобным именем. Например, история deploy может запускать задачи update-code и install-dependencies, перечисляя имена задач в своем определении:

@servers(['web' => ['user@192.168.1.1']])
 
@story('deploy')
    update-code
    install-dependencies
@endstory
 
@task('update-code')
    cd /home/user/example.com
    git pull origin master
@endtask
 
@task('install-dependencies')
    cd /home/user/example.com
    composer install
@endtask

После того как история написана, ее можно вызвать тем же способом, что и задачу:

php vendor/bin/envoy run deploy

Хуки (Hooks)

При выполнении задач и историй выполняется ряд хуков. Envoy поддерживает следующие варианты хуков: @before, @after, @error, @success и @finished. Весь код в этих хуках интерпретируется как PHP и выполняется локально, а не на удаленных серверах, с которыми взаимодействуют ваши задачи.

Вы можете определить любое количество этих хуков. Они будут выполняться в том порядке, в котором они появляются в вашем сценарии Envoy.

`@before`

Перед выполнением каждой задачи будут выполняться все хуки @before, зарегистрированные в вашем скрипте Envoy. Хуки @before получают имя задачи, которая будет выполняться:

@before
    if ($task === 'deploy') {
        // ...
    }
@endbefore

`@after`

После выполнения каждой задачи будут выполняться все хуки @after, зарегистрированные в вашем скрипте Envoy. Хуки @after получают имя задачи, которая была выполнена:

@after
    if ($task === 'deploy') {
        // ...
    }
@endafter

`@error`

После каждого сбоя задачи (выхода с кодом состояния больше 0) будут выполняться все хуки @error, зарегистрированные в вашем скрипте Envoy. Хуки @error получают имя задачи, которая была выполнена:

@error
    if ($task === 'deploy') {
        // ...
    }
@enderror

`@success`

Если все задачи выполнены без ошибок, то все хуки @success, зарегистрированные в вашем сценарии Envoy, будут выполнены:

@success
    // ...
@endsuccess

`@finished`

После выполнения всех задач (независимо от статуса выхода) будут выполнены все хуки @finished. Хуки @finished получают код состояния завершенной задачи, который может быть null или integer, большим или равным 0:

@finished
    if ($exitCode > 0) {
        // В одной из задач были обнаружены ошибки...
    }
@endfinished

Выполнение задач

Чтобы запустить задачу или историю, определенную в файле Envoy.blade.php вашего приложения, выполните в Envoy команду run, передав имя задачи или истории, которую вы хотите выполнить. Envoy выполнит задачу и отобразит вывод данных с удаленных серверов по мере выполнения задачи:

php vendor/bin/envoy run deploy

Подтверждение выполнения задачи

Если необходимо запрашивать подтверждение перед запуском той или иной задачи на серверах, следует добавить директиву confirm в объявление задачи. Эта опция особенно полезна при выполнении деструктивных операций:

@task('deploy', ['on' => 'web', 'confirm' => true])
    cd /home/user/example.com
    git pull origin {{ $branch }}
    php artisan migrate
@endtask

Уведомления

Slack

Envoy поддерживает отправку уведомлений в Slack после выполнения каждой задачи. Директива @slack принимает URL хука Slack и имя канала/пользователя. URL webhook можно получить, создав интеграцию "Incoming WebHooks" в панели управления Slack.

В качестве первого аргумента директивы @slack следует передать весь URL webhook. Вторым аргументом директивы @slack должно быть имя канала (#channel) или имя пользователя (@user):

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

По умолчанию уведомления Envoy отправляются в канал уведомлений с описанием выполненной задачи. Однако его можно заменить своим собственным сообщением, передав третий аргумент директивы @slack:

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

Discord

Envoy также поддерживает отправку уведомлений в Discord после выполнения каждой задачи. Директива @discord принимает URL хука Discord и сообщение. URL webhook можно получить, создав "Webhook" в настройках сервера и выбрав канал, на который он должен отправляться. В директиве @discord следует передать весь URL Webhook:

@finished
    @discord('discord-webhook-url')
@endfinished

Envoy также поддерживает отправку уведомлений в Telegram после выполнения каждой задачи. Директива @telegram принимает ID Bot Telegram и ID Chat. Идентификатор бота можно получить, создав нового бота с помощью BotFather. Получить действительный идентификатор чата можно с помощью @username_to_id_bot. В директиву @telegram следует передавать полный идентификатор бота и идентификатор чата:

@finished
    @telegram('bot-id','chat-id')
@endfinished

Microsoft Teams

Envoy также поддерживает отправку уведомлений в Microsoft Teams после выполнения каждой задачи. Директива @microsoftTeams принимает Teams Webhook (обязательно), сообщение, цвет темы (success, info, warning, error) и массив параметров. Вы можете получить свой Teams Webhook, создав новый входящий webhook. В Teams API имеется множество других атрибутов для настройки окна сообщения, таких как заголовок, аннотация и разделы. Дополнительную информацию можно найти в документации по Microsoft Teams. В директиве @microsoftTeams следует передать весь URL Webhook:

@finished
    @microsoftTeams('webhook-url')
@endfinished

Перевод с английского официальной документации Laravel 10.x:
https://laravel.com/docs/10.x/envoy

Заберите ссылку на статью к себе, чтобы потом легко её найти!
Раз уж досюда дочитали, то может может есть желание рассказать об этом месте своим друзьям, знакомым и просто мимо проходящим?
Не надо себя сдерживать! ;)

Laravel Envoy