Laravel Envoy

• Вступ
• Встановлення
• Написання завдань
  • Визначення Завдань
  • Кілька серверів
  • Налаштування
  • Змінні
  • Історії
  • Хуки
• Запуск завдань
  • Підтвердження Виконання Завдання
• Сповіщення
  • Slack
  • Discord
  • Telegram
  • Microsoft Teams

Вступ

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

Встановлення

Спочатку встановіть Envoy у ваш проект, використовуючи менеджер пакетів компонувальник:

composer require laravel/envoy --dev

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

php vendor/bin/envoy

Завдання з написання

Визначення Завдань

Завдання є основним будівельним блоком Envoy. Завдання визначають shell-команди, які повинні виконуватися на ваших віддалених серверах, коли завдання викликається. Наприклад, ви можете визначити завдання, яке виконує команду php artisan queue:restart на всіх серверах обробників черги вашого застосунку.

Усі ваші завдання Envoy повинні бути визначені у файлі Envoy.blade.php у корені вашого застосунку. Ось приклад, щоб почати:

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

Як ви можете бачити, масив @servers визначено на початку файлу, що дозволяє вам посилатися на ці сервери через опцію on у ваших оголошеннях завдань. Оголошення @servers завжди повинно бути розміщено на одному рядку. У межах ваших оголошень @task ви повинні розміщувати shell-команди, які повинні виконуватися на ваших серверах, коли завдання викликається.

Локальні завдання

Ви можете примусити скрипт виконуватись на вашому локальному комп'ютері, вказавши 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

Налаштування

Іноді вам може знадобитися виконати довільний PHP-код перед запуском ваших завдань Envoy. Ви можете використовувати директиву @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' => ['example@example.com']])
 
@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' => ['example@example.com']])
 
@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

Хуки

Коли завдання та історії виконуються, виконується ряд хуків. Типи хуків, які підтримуються Envoy, це @before, @after, @error, @success та @finished. Весь код у цих хуках інтерпретується як PHP і виконується локально, а не на віддалених серверах, з якими взаємодіють ваші завдання.

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

@before

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

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

@after

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

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

@error

Після кожного збою завдання (виходить зі статус-кодом більшим за 0), всі зареєстровані у вашому скрипті Envoy хуки @error будуть виконані. Хуки @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 вашого застосунку, виконайте команду run Envoy, передавши ім'я завдання або історії, яку ви хочете виконати. 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 hook та ім'я каналу / користувача. Ви можете отримати свій URL вебхука, створивши інтеграцію "Incoming WebHooks" у вашій панелі керування Slack.

Ви повинні передати повний URL вебхука як перший аргумент, наданий директиві @slack. Другий аргумент, наданий директиві @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 hook та повідомлення. Ви можете отримати URL-адресу вашого вебхука, створивши "Webhook" у налаштуваннях сервера та вибравши канал, до якого вебхук повинен надсилати повідомлення. Ви повинні передати всю URL-адресу Webhook у директиву @discord:

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

Telegram

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

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

Microsoft Teams

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

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