イントロダクション

Laravel Envoy(使節)は、定義した共通タスクをリモートサーバーで実行するために、クリーンで最小限の記法を提供します。Bladeスタイルの記述法を使用し、デプロイやArtisanコマンドなどのタスクを簡単にセットアップできます。

注目: Envoyは、PHPバージョン5.4以上で、MacもしくはLinuxのオペレーティングシステム上で動作します。

インストール

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

composer global require "laravel/envoy=~1.0"

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

次に、Envoy.blade.phpファイルをプロジェクトのルートに作成します。最初のサンプル設定をどうぞ。

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

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

見ての通り、最初に@serversで、配列を定義しています。これらのサーバーへは、タスク宣言のonオプションの中で、参照できます。@task宣言の中に、タスクを実行するサーバーで走らせる、Bashコードを記述します。

initコマンドを使用し、Envoyファイルのスタブを簡単に作成できます。

envoy init user@192.168.1.1

タスク実行

タスクを実行するには、インストールしたEnvoyで、runコマンドを実行してください。

envoy run foo

必要であれば、コマンドラインスイッチを使用し、Envoyファイルへ変数を渡すことができます。

envoy run deploy --branch=master

指定したオプションをBlade記法で使用できます。

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

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

準備コード

@setupディレクティブを使えば、Envoyファイルの中で変数宣言をしたり、一般的なPHPコードを動作させたりできます。

@setup
    $now = new DateTime();

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

また、@includeを使用し、PHPファイルを読み込むことも可能です。

@include('vendor/autoload.php');

タスク実行前の確認

サーバーで指定したタスクを実行する前に確認のプロンプトを表示したい場合は、confirmディレクティブを使ってください。

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

複数サーバー

複数のサーバーに渡り、簡単にタスクを実行できます。タスク宣言で、サーバーのリストを指定するだけです。

@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

タスクマクロ

マクロでは、一つのコマンドで順番に実行する、一連のタスクを定義します。例えば:

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

@macro('deploy')
    foo
    bar
@endmacro

@task('foo')
    echo "HELLO"
@endtask

@task('bar')
    echo "WORLD"
@endtask

これで、deployマクロは、ひとつのシンプルなコマンドにより、実行されます。

envoy run deploy

通知

HipChat

タスクを実行後、あなたのチームのHipChatルームへ、シンプルな@hipchatディレクティブを使用し、通知を送ることができます。

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

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

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

また、カスタムメッセージをHipChatルームに指定することもできます。@setupで変数を直接宣言できますし、@includeでファイルを読み込むこともできます。そうして宣言した変数をメッセージの中で使用できます。

@after
    @hipchat('token', 'room', 'Envoy', "$task ran on [$environment]")
@endafter

これは、サーバーでタスクが実行されたことをチームへ必ず通知できる、とてもシンプルな方法です。

Slack

Slackへ通知を送るには、以下の記述法が使用できます。

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

SlackのWebサイトのIncoming WebHooksインテグレーションを作成し、WebフックURLを取得してください。hook引数はIncoming Webhooksインテグレーションにより提供される完全なWebフックURLを指定します。例えば:

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

channel引数には、以下の形式の一つを指定します。

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

channel引数が指定されない場合は、デフォルトのチャンネルが使用されるでしょう。

注意: Slackへの通知は、全タスクが失敗なく完了した場合のみ行われます。

Envoyのアップデート

Envoyを更新するには、通常通りComposerを使ってください。

composer global update