Laravel 5.2 Envoyタスクランナー

イントロダクションIntroduction

Laravel Envoy（使節）はリモートサーバー間で共通のタスクを実行するために、美しく最小限の記法を提供します。デプロイやArtisanコマンドなどのタスクをBlade記法により簡単に準備できます。EnvoyはMacとLinuxのオペレーションシステムのみサポートしています。Laravel Envoy[https://github.com/laravel/envoy] provides a clean, minimal syntax for defining common tasks you run on your remote servers. Using a Blade style syntax, you can easily setup tasks for deployment, Artisan commands, and more. Currently, Envoy only supports the Mac and Linux operating systems.

インストールInstallation

最初にEnvoyをComposerのglobalコマンドでインストールします。First, install Envoy using the Composer global command:

composer global require "laravel/envoy=~1.0"

envoyコマンドを端末で実行するときにenvoyの実行ファイルが見つかるように、~/.composer/vendor/binディレクトリに実行パスを通しておくのを忘れないでください。Make sure to place the ~/.composer/vendor/bin directory in your PATH so the envoy executable is found when you run the envoy command in your terminal.

Envoyの更新Updating Envoy

インストールしたEnvoyを更新するときもComposerを使用します。You may also use Composer to keep your Envoy installation up to date:

composer global update

タスク記述Writing Tasks

Envoyの全タスクはプロジェクトルートのEnvoy.blade.phpファイルの中で定義します。簡単な例を見てください。All of your Envoy tasks should be defined in an Envoy.blade.php file in the root of your project. Here's an example to get you started:

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

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

見ての通り、@serversの配列をファイルの最初で定義し、タスク定義のonオプションでそれらのサーバーを参照できるようにしています。@task定義の中には、タスクが実行されるときにサーバーで実行するBASHコードを記述します。As you can see, an array of @servers is defined at the top of the file, allowing you to reference these servers in the on option of your task declarations. Within your @task declarations, you should place the Bash code that will be run on your server when the task is executed.

ローカルタスクLocal Tasks

ローカルホストを参照するサーバを定義することにより、スクリプトをローカルで実行可能です。You can define a script to run locally by defining a server reference to the local host:

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

初期処理Bootstrapping

Envoyタスクを実行する前に、PHPコードを評価する必要がある場合もあります。変数を宣言するために@setupディレクティブを使用し、Envoyファイルの中で通常のPHPを動かせます。Sometimes, you may need to execute some PHP code before evaluating your Envoy tasks. You may use the @setup directive to declare variables and do general PHP work inside the Envoy file:

@setup
    $now = new DateTime();

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

また、外部のPHPファイルを@includeで読み込むこともできます。You may also use @include to include any outside PHP files:

@include('vendor/autoload.php')

タスクの実行確認Confirming Tasks

サーバーで指定したタスクを実行する前に確認したい時もあるでしょう。タスクの宣言でconfirmディレクティブを追加してください。If you would like to be prompted for confirmation before running a given task on your servers, you may add the confirm directive to your task declaration:

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

タスク変数Task Variables

必要であればタスクのカスタマイズを行うために、コマンドラインスイッチでEnvoyへ変数を渡すこともできます。If needed, you may pass variables into the Envoy file using command line switches, allowing you to customize your tasks:

envoy run deploy --branch=master

オプションはBladeの"echo"記法により、タスクで使用できます。You may use the options in your tasks via Blade's "echo" syntax:

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

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

複数サーバーMultiple Servers

複数のサーバーに渡りタスクを実行するのも簡単です。最初に追加のサーバーを@serversディレクティブで指定してください。各サーバーには一意な名前を割り当ててください。追加サーバーを定義したら、タスク宣言のon配列にサーバーをリストするだけです。You may easily run a task across multiple servers. First, add additional servers to your @servers declaration. Each server should be assigned a unique name. Once you have defined your additional servers, simply list the servers in the task declaration's on array:

@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

デフォルトでタスクは各サーバーで順番に実行されます。つまり最初のサーバーで実行を終えたら、次のサーバーで実行されます。By default, the task will be executed on each server serially. Meaning, the task will finish running on the first server before proceeding to execute on the next server.

並列実行Parallel Execution

タスクを複数サーバーで並列実行したい場合は、タスク宣言にparallelオプションを追加してください。If you would like to run a task across multiple servers in parallel, add the parallel option to your task declaration:

@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

タスクマクロTask Macros

マクロにより一つのコマンドで一連のタスクを順番に実行できます。たとえば、deployマクロでgitとcomposerタスクを実行するとしましょう。Macros allow you to define a set of tasks to be run in sequence using a single command. For instance, a deploy macro may run the git and composer tasks:

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

@macro('deploy')
    git
    composer
@endmacro

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

@task('composer')
    composer install
@endtask

マクロが定義できたら、シンプルに１コマンドで実行しましょう。Once the macro has been defined, you may run it via single, simple command:

envoy run deploy

タスク実行Running Tasks

Envoy.blade.phpファイルのタスクを実行するには実行したいタスクかマクロの名前を指定し、Envoyのrunコマンドを実行します。To run a task from your Envoy.blade.php file, execute Envoy's run command, passing the command the name of the task or macro you would like to execute. Envoy will run the task and display the output from the servers as the task is running:

envoy run task

通知Notifications

HipChatHipChat

タスク実行後、チームのHipChatルームへ通知するには@hipchatディレクティブを使います。ディレクティブにはAPIトークン、ルームの名前、メッセージの送信者名として表示されるユーザ名を指定します。After running a task, you may send a notification to your team's HipChat room using Envoy's @hipchat directive. The directive accepts an API token, the name of the room, and the username to be displayed as the sender of the message:

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

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

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

HipChatルームにカスタムメッセージを送信することもできます。メッセージを構築するためにEnvoyタスクのどんな変数でも使用できます。If you wish, you may also pass a custom message to send to the HipChat room. Any variables available to your Envoy tasks will also be available when constructing the message:

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

SlackSlack

HipChatに加え、EnvoyはSlackへの通知もサポートしています。@slackディレクティブでSlackフックURL、チャンネル名、そのチャンネルに送信したいメッセージを指定します。In addition to HipChat, Envoy also supports sending notifications to Slack[https://slack.com]. The @slack directive accepts a Slack hook URL, a channel name, and the message you wish to send to the channel:

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

WebフックURLはSlackのWebサイトでIncoming WebHooksインテグレーションを作成することで、取得できます。hook引数はIncoming Webhooks Slackインテグレーションにより指定されるWebhook URL全体を指定します。You may retrieve your webhook URL by creating an Incoming WebHooks integration on Slack's website. The hook argument should be the entire webhook URL provided by the Incoming Webhooks Slack Integration. For example:

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

チャンネル引数には以下のどちらかを指定します。You may provide one of the following as the channel argument:

• チャンネルに通知するには： #channelTo send the notification to a channel: #channel
• ユーザに通知するには： @userTo send the notification to a user: @user