︙

Laravel Envoy

Table of Contents

Introduction
Installation
Writing Tasks
- Defining Tasks
- Multiple Servers
- Setup
- Variables
- Stories
- Hooks
Running Tasks
- Confirming Task Execution
Notifications

Introduction

Laravel Envoy は、リモートサーバーで実行する一般的なタスクを実行するためのツールです。Blade スタイルの syntax を使用すると、 deployment や Artisan コマンドなどのタスクを簡単にセットアップできます。現在、Envoy は Mac と Linux オペレーティングシステムのみをサポートしています。しかし、Windows サポートは WSL2 を使用することで実現可能です。

Installation

まず、 Composer パッケージマネージャーを使用して、Envoy をあなたの project にインストールします:

composer require laravel/envoy --dev

Envoy がインストールされると、Envoy の binary がアプリケーションのvendor/binディレクトリで利用可能になります：

php vendor/bin/envoy

Writing Tasks

タスクの定義

タスクは Envoy の基本的な構成要素です。タスクは、タスクが呼び出されたときにリモートサーバーで実行するべきシェルコマンドを定義します。例えば、アプリケーションの queue ワーカーサーバー全てでphp artisan queue:restart command を実行するタスクを定義するかもしれません。

すべての Envoy タスクは、あなたの application の root にある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の array がファイルの上部で定義されており、タスク宣言のonオプションを使ってこれらのサーバーを参照できます。@serversの declaration は常に single の行に配置する必要があります。あなたの@task宣言内では、タスクが呼び出されたときにサーバーで実行すべきシェルコマンドを配置するべきです。

ローカルタスク

あなたは、サーバーの IP アドレスを127.0.0.1と指定することで、ローカルコンピュータでスクリプトを強制的に実行することができます：

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

Envoy タスクのインポート

@importディレクティブを使用すると、他の Envoy ファイルをインポートし、そこに含まれるストーリーやタスクを自分のファイルに追加することができます。ファイルがインポートされた後、それらが自分の Envoy ファイルに定義されているかのように、含まれるタスクを実行することができます：

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

複数のサーバー

Envoy は、複数の servers でタスクを簡単に実行することを可能にします。まず、@servers宣言に追加の servers を追加します。各 servers は unique な名前を割り当てる必要があります。追加の servers を定義したら、タスクのon array で各 servers をリストアップできます：

@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

並行実行

default によると、タスクは各 server で順番に実行されます。つまり、タスクは最初の server での実行が終了してから、2 つ目の server で実行を開始します。もしタスクを複数の server で並行して実行したい場合は、タスク宣言にparalleloption を追加してください:

@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

Setup

時々、Envoy タスクを実行する前に任意の PHP の code を実行する必要があるかもしれません。あなたは、@setupディレクティブを使用して、タスクの前に実行するべき PHP の code のブロックを定義することができます:

@setup
    $now = new DateTime;
@endsetup

タスクが実行される前に他の PHP ファイルを必要とする場合は、Envoy.blade.phpファイルの上部で@includeディレクティブを使用することができます：

@include('vendor/autoload.php')

@task('restart-queues')
    # ...
@endtask

Variables

必要であれば、Envoy のタスクに引数を渡すことができます。それは、Envoy を呼び出す際に command 行で指定することによります:

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

Blade の"echo" syntax を使用して、タスク内の options にアクセスすることができます。また、あなたのタスク内で Blade のifstatements やループを定義することもできます。例えば、git pull command を実行する前に$branchvariable の存在を確認してみましょう:

@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 がサポートする hook タイプには、@before、@after、@error、@success、および@finishedがあります。これらのフック内の全ての code は PHP として解釈され、ローカルで実行されます。これは、あなたのタスクが対話するリモートサーバーではなくです。

これらのフックは何個でも定義できます。それらは、あなたの Envoy スクリプト内で表示される順番に実行されます。

`@before`

各タスクの実行前に、Envoy スクリプトに登録されたすべての @before フックが実行されます。@before フックは、実行されるタスクの名前を受け取ります：

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

`@after`

各タスクの実行後、Envoy スクリプトに登録されているすべての @after フックが実行されます。 @after フックは実行されたタスクの名前を受け取ります：

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

`@error`

すべてのタスクの失敗( status code が0より大きいと退出)の後で、Envoy スクリプトに登録されたすべての@error フックが実行されます。@errorフックは、実行されたタスクの名前を受け取ります：

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

`@success`

すべてのタスクが errors なしに実行された場合、Envoy スクリプトに登録されたすべての@successフックが実行されます：

@success
    // ...
@endsuccess

`@finished`

すべてのタスクが実行された後( status の結果に関わらず)、すべての@finishedフックが実行されます。@finishedフックは、終了したタスクの status code を受け取り、それはnullまたは0以上のintegerである可能性があります：

@finished
    if ($exitCode > 0) {
        // There were errors in one of the tasks...
    }
@endfinished

Running Tasks

アプリケーションのEnvoy.blade.phpファイルで定義されたタスクやストーリーを実行するには、実行したいタスクやストーリーの名前を引数にして Envoy の run command を実行します。Envoy はタスクを実行し、タスクが実行中であるときのリモートサーバーからの output を表示します：

php vendor/bin/envoy run deploy

タスク実行の確認

サーバー上の特定のタスクを実行する前に確認を求めたい場合は、そのタスクの declaration にconfirmディレクティブを追加するべきです。このオプションは、破壊的操作に特に役立ちます:

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

Notifications

Slack

Envoy は、タスクが実行されるたびに、Slack に通知を送信することをサポートしています。@slackディレクティブは、Slack hook URL と channel/user 名を受け付けます。webhook URL は、受信 WebHooks の統合を作成することで Slack コントロールパネルから取得できます。

@slackディレクティブに与えられる最初の引数として、 webhook URL 全体を渡すべきです。@slackディレクティブに与えられる 2 つ目の引数は、 channel の名前(#channel)または user の名前(@user)であるべきです。

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

default として、Envoy 通知は実行されたタスクを説明するメッセージを通知 channel に送信します。ただし、@slackディレクティブに第三引数を渡すことで、このメッセージを自分の custom メッセージで上書きすることができます。

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

Discord

Envoy は、各タスクが実行された後に、Discord に通知を送信することもサポートしています。@discordディレクティブは、Discord のフック URL とメッセージを受け入れます。Server 設定で webhook を作成し、web フックが投稿する channel を選択することで、あなたの web フック URL を取得することができます。@discordディレクティブには、全体の web フック URL を渡す必要があります。

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

Envoy はまた、各タスクが実行された後にTelegram に notifications を送信することもサポートしています。 @telegram ディレクティブは Telegram Bot ID と Chat ID を受け入れます。Bot ID はBotFather を使用して新しい bot を作成することで取得できます。有効な Chat ID は@username_to_id_bot を使って取得できます。@telegramディレクティブには、完全な Bot ID と Chat ID を渡す必要があります：

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

Microsoft Teams

Envoy は、各タスクが実行されるたびに、Microsoft Teams に通知を送信することもサポートしています。 @microsoftTeams ディレクティブは、Teams の webhook(必須)、メッセージ、テーマカラー(成功、 info、警告、 error)、そして options の array を受け入れます。Teams の webhook は、新しくwebhook を受け取ることで取得できます。Teams の API には、タイトル、概要、セクションなどのメッセージボックスをカスタマイズするための他の多くの属性があります。詳細はMicrosoft Teams のドキュメンテーションで確認できます。全体の Webhook URL を @microsoftTeams ディレクティブに渡す必要があります。

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