イントロダクション
Laravel Envoyは、リモートサーバ上で実行する一般的なタスクを実行するためのツールです。bladeスタイルの構文を使用し、デプロイやArtisanコマンドなどのタスクを簡単に設定できます。現在、EnvoyはMacおよびLinuxオペレーティングシステムのみをサポートしています。ただし、WindowsサポートはWSL2を使用して実現できます。
インストール
まず、Composerパッケージマネージャを使用してEnvoyをプロジェクトにインストールします。
composer require laravel/envoy --dev
Envoyがインストールされると、Envoyバイナリはアプリケーションのvendor/bin
ディレクトリで利用できるようになります。
php vendor/bin/envoy
タスクの記述
タスク定義
タスクは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
宣言は常に1行に配置する必要があります。@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
並列実行
デフォルトでは、タスクは各サーバで順次実行されます。つまり、タスクは、2番目のサーバでの実行に進む前に、最初のサーバでの実行を終了します。複数のサーバ間でタスクを並行して実行する場合は、タスク宣言に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ファイルをリクエストする必要がある場合は、Envoy.blade.php
ファイルの先頭にある@include
ディレクティブを使用できます。
@include('vendor/autoload.php')
@task('restart-queues')
# ...
@endtask
変数
必要に応じて、Envoyを呼び出すときにコマンドラインで引数を指定することにより、Envoyタスクに引数を渡すことができます。
php vendor/bin/envoy run deploy --branch=master
Bladeの「エコー(echo)」構文を使用して、タスク内のオプションにアクセスできます。タスク内でBladeのif
ステートメントとループを定義することもできます。例としてgit pull
コマンドを実行する前に、$branch
変数の存在を確認してみましょう。
@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
ストーリー
ストーリーは、一連のタスクを1つの便利な名前でグループ化します。たとえば、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
フック
タスクとストーリーが実行されると、いくつかのフックが実行されます。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
すべてのタスクがエラーなしで実行された場合は、Envoyスクリプトで登録したすべての@success
フックが実行されます。
@success
// ...
@endsuccess
@finished
すべてのタスクが実行された後(終了ステータスに関係なく)、すべての@finished
フックが実行されます。@finished
フックはnull
か0
以上のinteger
を終了したタスクのステータスコードとして受け取ります。
@finished
if ($exitCode > 0) {
// 1つのタスクにエラーがあった
}
@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
ディレクティブは、SlackフックURLとチャネル/ユーザー名を受け入れます。Slackのコントロールパネルで"Incoming
WebHooks"統合を作成し、WebフックURLを取得してください。
@slack
ディレクティブに指定する最初の引数に、WebフックURL全体を渡す必要があります。@slack
ディレクティブの2番目の引数は、チャネル名(#channel
)またはユーザー名(@user
)です。
@finished
@slack('webhook-url', '#bots')
@endfinished
デフォルトでEnvoy
の通知は、実行したタスクを説明するメッセージを通知チャネルに送信します。しかし、@slack
ディレクティブに第三引数を渡すことで、このメッセージを自分のカスタムメッセージで上書きすることができます。
@finished
@slack('webhook-url', '#bots', 'Hello, Slack.')
@endfinished
Discord
Envoyは、各タスクの実行後のDiscordへの通知送信もサポートしています。@discord
ディレクティブは、DiscordフックのURLとメッセージを受け入れます。サーバ設定で"Webhook"を作成し、Webフックが投稿するチャンネルを選択することで、WebフックURLを取得できます。WebフックURL全体を@discord
ディレクティブに渡す必要があります。
@finished
@discord('discord-webhook-url')
@endfinished
Telegram
Envoyは、各タスクの実行後のTelegramへの通知送信もサポートしています。@telegram
ディレクティブは、TelegramボットIDとチャットIDを受け入れます。BotFatherを使用して新しいボットを作成することにより、ボットIDを取得できます。@username_to_id_botを使用して有効なチャットIDを取得できます。ボットIDとチャットID全体を@telegram
ディレクティブに渡す必要があります。
@finished
@telegram('bot-id','chat-id')
@endfinished
Microsoft Teams
Envoyは各タスクを実行した後の、Microsoft
Teamsへの通知送信もサポートしています。@microsoftTeams
ディレクティブは、TeamsのWebフック(必須)、メッセージ、テーマカラー
(success、info、warning、error)、およびオプションの配列を引数に取ります。新しい受信Webフック
を作成すれば、Teams Webookを取得できます。Teams API
には、タイトルやサマリー、セクションなど、メッセージボックスをカスタマイズするためのさまざまな属性が用意されています。詳細は、Microsoft
Teamsのドキュメントを確認してください。WebフックのURL全体を@microsoftTeams
ディレクティブに渡す必要があります。
@finished
@microsoftTeams('webhook-url')
@endfinished