イントロダクション

Laravel Envoy(使節)はリモートサーバー間で共通のタスクを実行するために、美しいで最小限の記法を提供します。デプロイやArtisanコマンドなどのタスクをBlade記法により簡単に準備できます。EnvoyはMacとLinuxのオペレーションシステムのみサポートしています。

インストール

最初にEnvoyをComposerのglobalコマンドでインストールします。

composer global require "laravel/envoy=~1.0"

envoyコマンドを端末で実行するときにenvoyの実行ファイルが見つかるように、~/.composer/vendor/binディレクトリーに実行パスを通しておくのを忘れないでください。

Envoyの更新

インストールしたEnvoyを更新するときもComposerを使用します。

composer global update

タスク記述

Envoyの全タスクはプロジェクトルートのEnvoy.blade.phpファイルの中で定義します。簡単な例を見てください。

@servers(['web' => 'user@192.168.1.1'])

@task('foo', ['on' => 'web'])
    ls -la
@endtask

見ての通り、@serversの配列をファイルの最初で定義し、タスク定義のonオプションでそれらのサーバーを参照できるようにしています。@task定義の中には、タスクが実行されるときにサーバーで実行するBASHコードを記述します。

初期処理

Envoyタスクを評価する前にPHPコードを実行する必要がある場合もあります。変数を宣言するために@setupディレクティブを使用し、Envoyファイルの中で通常のPHPを動かせます。

@setup
    $now = new DateTime();

    $environment = isset($env) ? $env : "testing";
@endsetup

また、外部のPHPファイルを@includeで読み込むこともできます。

@include('vendor/autoload.php')

タスクの実行確認

サーバーで指定したタスクを実行する前に確認したい時もあるでしょう。タスクの宣言でconfirmディレクティブを追加してください。

@task('deploy', ['on' => 'web', 'confirm' => true])
    cd site
    git pull origin {{ $branch }}
    php artisan migrate
@endtask

タスク変数

必要であればタスクのカスタマイズを行うために、コマンドラインスイッチでEnvoyへ変数を渡すこともできます。

envoy run deploy --branch=master

オプションはBladeの"echo"記法により、タスクで使用できます。

@servers(['web' => '192.168.1.1'])

@task('deploy', ['on' => 'web'])
    cd site
    git pull origin {{ $branch }}
    php artisan migrate
@endtask

複数サーバー

複数のサーバーに渡りタスクを実行するのも簡単です。最初に追加のサーバーを@serversディレクティブで指定してください。各サーバーには一意な名前を割り当ててください。追加サーバーを定義したら、タスク宣言のon配列にサーバーをリストするだけです。

@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])

@task('deploy', ['on' => ['web-1', 'web-2']])
    cd site
    git pull origin {{ $branch }}
    php artisan migrate
@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 site
    git pull origin {{ $branch }}
    php artisan migrate
@endtask

タスクマクロ

マクロにより一つのコマンドで一連のタスクを順番に実行できます。たとえば、deployマクロでgitcomposerタスクを実行するとしましょう。

@servers(['web' => '192.168.1.1'])

@macro('deploy')
    git
    composer
@endmacro

@task('git')
    git pull origin master
@endtask

@task('composer')
    composer install
@endtask

マクロが定義できたら、シンプルに1コマンドで実行しましょう。

envoy run deploy

タスク実行

Envoy.blade.phpファイルのタスクを実行するには実行したいタスクかマクロの名前を指定し、Envoyのrunコマンドを実行します。

envoy run task

通知

HipChat

タスク実行後、チームのHipChatルームへ通知するには@hipchatディレクティブを使います。ディレクティブにはAPIトークン、ルームの名前、メッセージの送信者名として表示されるユーザー名を指定します。

@servers(['web' => '192.168.1.1'])

@task('foo', ['on' => 'web'])
    ls -la
@endtask

@after
    @hipchat('token', 'room', 'Envoy')
@endafter

HipChatルームにカスタムメッセージを送信することもできます。メッセージを構築するためにEnvoyタスクのどんな変数でも使用できます。

@after
    @hipchat('token', 'room', 'Envoy', "{{ $task }} ran in the {{ $env }} environment.")
@endafter

Slack

HipChatに加え、EnvoyはSlackへの通知もサポートしています。@slackディレクティブでSlackフックURL、チャンネル名、そのチャンネルに送信したいメッセージを指定します。

@after
    @slack('hook', 'channel', 'message')
@endafter

WebフックURLはSlackのWebサイトでIncoming WebHooksインテグレーションを作成することで、取得できます。hook引数はIncoming Webhooks Slackインテグレーションにより指定されるWebhook URL全体を指定します。

https://hooks.slack.com/services/ZZZZZZZZZ/YYYYYYYYY/XXXXXXXXXXXXXXX

チャンネル引数には以下のどちらかを指定します。

  • チャンネルに通知するには: #channel
  • ユーザーに通知するには: @user