Laravel 7.x Laravel 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 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 requireコマンドでインストールします。First, install Envoy using the Composer global require command:

composer global require laravel/envoy

グローバルComposerライブラリは、ときどきパッケージバージョンのコンフリクトを起こすため、composer global requireコマンドの代替として、cgrの使用を考慮してください。cgrライブラリのインストール方法は、GitHubで見つけられます。Since global Composer libraries can sometimes cause package version conflicts, you may wish to consider using cgr, which is a drop-in replacement for the composer global require command. The cgr library's installation instructions can be found on GitHub[https://github.com/consolidation-org/cgr].

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

Envoyの更新Updating Envoy

インストールしたEnvoyをアップデートするためにも、Composerを使用します。composer global updateコマンドの実行により、インストール済みのグローバルComposerパッケージがすべてアップデートされます。You may also use Composer to keep your Envoy installation up to date. Issuing the composer global update command will update all of your globally installed Composer packages:

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オプションでそれらのサーバを参照できるようにしています。@serversディレクティブは常に一行で指定してください。@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. The @servers declaration should always be placed on a single line. Within your @task declarations, you should place the Bash code that should run on your server when the task is executed.

サーバのIPアドレスを127.0.0.1にすることで、強制的にスクリプトをローカルで実行できます。You can force a script to run locally by specifying the server's IP address as 127.0.0.1:

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

準備Setup

タスクを実行する前に、PHPコードを評価する必要がある場合もあります。変数を宣言するために@setupディレクティブを使用し、他のタスクが実行される前に通常のPHPを動作させます。Sometimes, you may need to execute some PHP code before executing your Envoy tasks. You may use the @setup directive to declare variables and do other general PHP work before any of your other tasks are executed:

@setup
    $now = new DateTime();

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

タスク実行前に他のPHPライブラリを読み込む必要がある場合は、Envoy.blade.phpファイルの先頭で、@includeディレティブを使用してください。If you need to require other PHP files before your task is executed, you may use the @include directive at the top of your Envoy.blade.php file:

@include('vendor/autoload.php')

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

ストーリーやタスクを取り込むため、他のEnvoyファイルをインポートすることもできます。インポートすればそれらのファイルのタスクをこのファイルで定義しているかのように実行できます。@importディレクティブはEnvoy.blade.phpファイルの先頭で指定してください。You may also import other Envoy files so their stories and tasks are added to yours. After they have been imported, you may execute the tasks in those files as if they were defined in your own. You should use the @import directive at the top of your Envoy.blade.php file:

@import('package/Envoy.blade.php')

変数Variables

必要であれば、コマンドラインを使い、Envoyタスクへオプション値を渡すことができます。If needed, you may pass option values into Envoy tasks using the command line:

envoy run deploy --branch=master

オプションへはBladeの"echo"記法により、タスク中からアクセスできます。if文も使用できますし、タスク内で繰り返しも可能です。例としてgit pullコマンドを実行する前に、$branchの存在を確認してみましょう。You may access the options in your tasks via Blade's "echo" syntax. You may also use if statements and loops within your tasks. For example, let's verify the presence of the $branch variable before executing the git pull command:

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

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

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

    php artisan migrate
@endtask

ストーリーStories

ストーリーにより、選択した小さなタスクを大きなタスクにまとめることができます。名前を付け、一連のタスクを一つにまとめます。一例としてタスク名をリストすることにより、deployストーリーを定義し、gitとcomposerタスクを実行してみます。Stories group a set of tasks under a single, convenient name, allowing you to group small, focused tasks into large tasks. For instance, a deploy story may run the git and composer tasks by listing the task names within its definition:

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

@story('deploy')
    git
    composer
@endstory

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

@task('composer')
    composer install
@endtask

ストーリーを書き上げたら、通常のタスクと同じように実行します。Once the story has been written, you may run it just like a typical task:

envoy run deploy

複数サーバMultiple Servers

Envoyでは、複数のサーバに渡りタスクを実行するのも簡単です。最初に追加のサーバを@serversディレクティブで指定してください。各サーバには一意な名前を割り当ててください。追加サーバを定義したら、タスクのon配列にサーバをリストするだけです。Envoy allows you to 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, list each of the servers in the task'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

並列実行Parallel Execution

デフォルトでタスクは各サーバで順番に実行されます。つまり最初のサーバで実行を終えたら、次のサーバで実行されます。タスクを複数サーバで並列実行したい場合は、タスク宣言にparallelオプションを追加してください。By default, tasks will be executed on each server serially. In other words, a task will finish running on the first server before proceeding to execute on the second server. 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

タスク実行Running Tasks

Envoy.blade.phpファイルのタスクやストーリーを実行するには、実行したいタスクかストーリーの名前を指定し、Envoyのrunコマンドを実行します。Envoyはタスクを実行し、タスク実行中にサーバからの出力を表示します。To run a task or story that is defined in your Envoy.blade.php file, execute Envoy's run command, passing the name of the task or story you would like to execute. Envoy will run the task and display the output from the servers as the task is running:

envoy run deploy

タスク実行の確認Confirming Task Execution

サーバ上の特定タスク実行前に、確認のプロンプトを出したい場合は、タスク宣言でconfirmディレクティブを追加してください。このオプションは、破壊的な操作を行う場合にとくに便利です。If you would like to be prompted for confirmation before running a given task on your servers, you should add the confirm directive to your task declaration. This option is particularly useful for destructive operations:

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

通知Notifications

SlackSlack

Envoyは各タスク実行後の、Slackへの通知もサポートしています。@slackディレクティブは、SlackフックURLとチャンネル名を引数に取ります。WebフックURLは、Slackコントロールパネルで"Incoming WebHooks"統合を作成することにより、作成されます。WebフックURL全体を@slackディレクティブへ渡してください。Envoy also supports sending notifications to Slack[https://slack.com] after each task is executed. The @slack directive accepts a Slack hook URL and a channel name. You may retrieve your webhook URL by creating an "Incoming WebHooks" integration in your Slack control panel. You should pass the entire webhook URL into the @slack directive:

@finished
    @slack('webhook-url', '#bots')
@endfinished

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

DiscordDiscord

Envoyは各タスク実行後の、Discordへの通知もサポートしています。@discordディレクティブは、DiscordフックURLとメッセージを引数に取ります。Server Settingで"Webhook"を作成し、どのチャンネルにポストするのかを選べば、WebフックURLが取得できます。WebフックURL全体を@discodeディレクティブへ渡してください。Envoy also supports sending notifications to Discord[https://discord.com] after each task is executed. The @discord directive accepts a Discord hook URL and a message. You may retrieve your webhook URL by creating a "Webhook" in your Server Settings and choosing which channel the webhook should post to. You should pass the entire Webhook URL into the @discord directive:

@finished
    @discord('discord-webhook-url')
@endfinished

TelegramTelegram

Envoyは各タスク終了後にTelegramへの通知送信もサポートしています。@telegramディレクティブはTelegram Bot IDとチャットIDを引数に取ります。BotFatherを使用して新しいBotを作成し、Bot IDを取得できます。@username_to_id_botを使用し、有効なチャットIDを取得できます。Bot IDとチャットID全体を@telegramディレクティブへ渡してください。Envoy also supports sending notifications to Telegram[https://telegram.org] after each task is executed. The @telegram directive accepts a Telegram Bot ID and a Chat ID. You may retrieve your Bot ID by creating a new bot using BotFather[https://t.me/botfather]. You can retrieve a valid Chat ID using @username_to_id_bot[https://t.me/username_to_id_bot]. You should pass the entire Bot ID and Chat ID into the @telegram directive:

@finished
    @telegram('<bot-id>','<chat-id>')
@endfinished