イントロダクション

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

インストール

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

composer global require "laravel/envoy=~1.0"

グローバルComposerライブラリは、時々パッケージバージョンのコンフリクトを起こすため、composer global requireコマンドの代替として、cgrの使用を考慮してください。cgrライブラリのインストール方法は、GitHubで見つけられます

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

Envoyの更新

インストールしたEnvoyをアップデートするためにも、Composerを使用します。composer global updateコマンドの実行により、インストール済みのグローバル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コードを記述します。

サーバのIPアドレスを127.0.0.1にすることで、強制的にスクリプトをローカルで実行できます。

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

準備

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

@setup
    $now = new DateTime();

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

タスク実行前に他のPHPライブラリを読み込む必要がある場合は、Envoy.blade.phpファイルの先頭で、@includeディレティブを使用してください。

@include('vendor/autoload.php')

@task('foo')
    # ...
@endtask

変数

必要であれば、コマンドラインを使い、Envoyタスクへオプション値を渡すことができます。

envoy run deploy --branch=master

オプションはBladeの"echo"記法により、タスクで使用できます。もちろん、if文も使用できますし、タスク内で繰り返しも可能です。例としてgit pullコマンドを実行する前に、$branchの存在を確認してみましょう。

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

@task('deploy', ['on' => 'web'])
    cd site

    @if ($branch)
        git pull origin {{ $branch }}
    @endif

    php artisan migrate
@endtask

ストーリー

ストーリーにより、選択した小さなタスクを大きなタスクにまとめることができます。名前を付け、一連のタスクを一つにまとめます。一例としてタスク名をリストすることにより、deployストーリーを定義し、gitcomposerタスクを実行してみます。

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

@story('deploy')
    git
    composer
@endstory

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

@task('composer')
    composer install
@endtask

ストーリーを書き上げたら、通常のタスクと同じように実行します。

envoy run deploy

複数サーバ

Envoyでは、複数のサーバーに渡りタスクを実行するのも簡単です。最初に追加のサーバーを@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

タスク実行

Envoy.blade.phpファイルのタスクやストーリーを実行するには、実行したいタスクかストーリーの名前を指定し、Envoyのrunコマンドを実行します。Envoyはタスクを実行し、タスク実行中にサーバからの出力を表示します。

envoy run task

タスク実行の確認

サーバ上の特定タスク実行前に、確認のプロンプトを出したい場合は、タスク宣言でconfirmディレクティブを追加してください。このオプションは、破壊的な操作を行う場合に特に便利です。

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

通知

Slack

Envoyは各タスク実行後の、Slackへの通知もサポートしています。@slackディレクティブは、SlackフックURLとチャンネル名を引数に取ります。WebフックURLは、Slackコントロールパネルで"Incoming WebHooks"統合を作成することにより、作成されます。WebフックURL全体を@slackディレクティブへ渡してください。

@after
    @slack('webhook-url', '#bots')
@endafter

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

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