私のブックマーク
ブックマークを追加
ブックマークを削除はじめに
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' => [''], 'workers' => ['']])@task('restart-queues', ['on' => 'workers'])cd /home/user/example.comphp 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.comgit 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.comgit 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' => ['']])@task('deploy', ['on' => 'web'])cd /home/user/example.com@if ($branch)git pull origin {{ $branch }}@endifphp artisan migrate --force@endtask
ストーリー
ストーリーは、一連のタスクを単一の便利な名前の下にグループ化します。たとえば、deploy ストーリーは、定義内にタスク名をリストすることで update-code および install-dependencies タスクを実行できます:
@servers(['web' => ['']])@story('deploy')update-codeinstall-dependencies@endstory@task('update-code')cd /home/user/example.comgit pull origin master@endtask@task('install-dependencies')cd /home/user/example.comcomposer install@endtask
ストーリーが書かれたら、タスクを呼び出すのと同じ方法で呼び出すことができます:
php vendor/bin/envoy run deploy
フック
タスクとストーリーが実行されると、いくつかのフックが実行されます。Envoy がサポートするフックの種類は @before、@after、@error、@success、および @finished です。これらのフック内のすべてのコードは PHP として解釈され、リモートサーバーではなくローカルで実行されます。
これらのフックは、必要に応じていくつでも定義できます。Envoy スクリプト内に表示される順序で実行されます。
@before
各タスクの実行前に、Envoy スクリプトに登録されたすべての @before フックが実行されます。@before フックは、実行されるタスクの名前を受け取ります:
@beforeif ($task === 'deploy') {// ...}@endbefore
@after
各タスクの実行後に、Envoy スクリプトに登録されたすべての @after フックが実行されます。@after フックは、実行されたタスクの名前を受け取ります:
@afterif ($task === 'deploy') {// ...}@endafter
@error
タスクが失敗した後（ステータスコードが 0 より大きい場合）、Envoy スクリプトに登録されたすべての @error フックが実行されます。@error フックは、実行されたタスクの名前を受け取ります:
@errorif ($task === 'deploy') {// ...}@enderror
@success
すべてのタスクがエラーなしで実行された場合、Envoy スクリプトに登録されたすべての @success フックが実行されます:
@success// ...@endsuccess
@finished
すべてのタスクが実行された後（終了ステータスに関係なく）、すべての @finished フックが実行されます。@finished フックは、完了したタスクのステータスコードを受け取ります。これは null または integer が 0 以上である可能性があります:
@finishedif ($exitCode > 0) {// There were errors in one of the tasks...}@endfinished
タスクの実行
アプリケーションの Envoy.blade.php ファイルに定義されたタスクまたはストーリーを実行するには、Envoy の run コマンドを実行し、実行したいタスクまたはストーリーの名前を渡します。Envoy はタスクを実行し、タスクが実行されている間にリモートサーバーからの出力を表示します:
php vendor/bin/envoy run deploy
タスク実行の確認
サーバーで特定のタスクを実行する前に確認を求められたい場合は、タスク宣言に confirm ディレクティブを追加する必要があります。このオプションは、破壊的な操作に特に便利です:
@task('deploy', ['on' => 'web', 'confirm' => true])cd /home/user/example.comgit pull origin {{ $branch }}php artisan migrate@endtask
通知
Slack
Envoy は、各タスクが実行された後に Slack に通知を送信することをサポートしています。@slack ディレクティブは、Slack フック URL とチャンネル / ユーザー名を受け入れます。Slack コントロールパネルで「Incoming WebHooks」統合を作成することで、Webhook URL を取得できます。
最初の引数として @slack ディレクティブに全体の Webhook URL を渡す必要があります。@slack ディレクティブに渡す2番目の引数は、チャンネル名 (#channel) またはユーザー名 (@user) である必要があります:
@finished@slack('webhook-url', '#bots')@endfinished
デフォルトでは、Envoy の通知は、実行されたタスクを説明するメッセージを通知チャンネルに送信します。ただし、@slack ディレクティブに3番目の引数を渡すことで、このメッセージを独自のカスタムメッセージで上書きできます:
@finished@slack('webhook-url', '#bots', 'Hello, Slack.')@endfinished
Discord
Envoy は、各タスクが実行された後に Discord に通知を送信することもサポートしています。@discord ディレクティブは、Discord フック URL とメッセージを受け入れます。サーバー設定で「Webhook」を作成し、Webhook が投稿するチャンネルを選択することで、Webhook URL を取得できます。@discord ディレクティブに全体の Webhook URL を渡す必要があります:
@finished@discord('discord-webhook-url')@endfinished
Telegram
Envoy は、各タスクが実行された後に Telegram に通知を送信することもサポートしています。@telegram ディレクティブは、Telegram ボット ID とチャット ID を受け入れます。新しいボットを BotFather を使用して作成することで、ボット ID を取得できます。有効なチャット ID は @username_to_id_bot を使用して取得できます。@telegram ディレクティブに全体のボット ID とチャット ID を渡す必要があります:
@finished@telegram('bot-id','chat-id')@endfinished
Microsoft Teams
Envoy は、各タスクが実行された後に Microsoft Teams に通知を送信することもサポートしています。@microsoftTeams ディレクティブは、Teams Webhook（必須）、メッセージ、テーマカラー（成功、情報、警告、エラー）、およびオプションの配列を受け入れます。新しい incoming webhook を作成することで、Teams Webhook を取得できます。Teams API には、タイトル、要約、セクションなど、メッセージボックスをカスタマイズするための多くの他の属性があります。詳細については、Microsoft Teams ドキュメント を参照してください。@microsoftTeams ディレクティブに全体の Webhook URL を渡す必要があります:
@finished@microsoftTeams('webhook-url')@endfinished
