forked from laravel/docs
-
Notifications
You must be signed in to change notification settings - Fork 124
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
65ae857
commit d5b701d
Showing
1 changed file
with
66 additions
and
71 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,93 +1,93 @@ | ||
| # Envoy Task Runner | ||
|
|
||
| - [Introduction](#introduction) | ||
| - [Installation](#envoy-installation) | ||
| - [Writing Tasks](#writing-tasks) | ||
| - [Task Variables](#task-variables) | ||
| - [Multiple Servers](#envoy-multiple-servers) | ||
| - [Task Macros](#envoy-task-macros) | ||
| - [Running Tasks](#envoy-running-tasks) | ||
| - [Multiple Servers](#envoy-multiple-servers) | ||
| - [Parallel Execution](#envoy-parallel-execution) | ||
| - [Task Macros](#envoy-task-macros) | ||
| - [Notifications](#envoy-notifications) | ||
| - [Updating Envoy](#envoy-updating-envoy) | ||
| - [HipChat](#hipchat) | ||
| - [Slack](#slack) | ||
|
|
||
| <a name="introduction"></a> | ||
| ## Introduction | ||
|
|
||
| [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. | ||
|
|
||
| > **Note:** Envoy requires PHP version 5.4 or greater, and only runs on Mac / Linux operating systems. | ||
| [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. | ||
|
|
||
| <a name="envoy-installation"></a> | ||
| ## Installation | ||
| ### Installation | ||
|
|
||
| First, install Envoy using the Composer `global` command: | ||
|
|
||
| composer global require "laravel/envoy=~1.0" | ||
|
|
||
| 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. | ||
|
|
||
| Next, create an `Envoy.blade.php` file in the root of your project. Here's an example to get you started: | ||
| #### Updating Envoy | ||
|
|
||
| You may also use Composer to keep your Envoy installation up to date: | ||
|
|
||
| composer global update | ||
|
|
||
| <a name="writing-tasks"></a> | ||
| ## Writing Tasks | ||
|
|
||
| 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' => '192.168.1.1']) | ||
|
|
||
| @task('foo', ['on' => 'web']) | ||
| ls -la | ||
| @endtask | ||
|
|
||
| As you can see, an array of `@servers` is defined at the top of the file. You can 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. | ||
| 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. | ||
|
|
||
| The `init` command may be used to easily create a stub Envoy file: | ||
| #### Bootstrapping | ||
|
|
||
| envoy init [email protected] | ||
| 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: | ||
|
|
||
| <a name="envoy-running-tasks"></a> | ||
| ## Running Tasks | ||
|
|
||
| To run a task, use the `run` command of your Envoy installation: | ||
| @setup | ||
| $now = new DateTime(); | ||
|
|
||
| envoy run foo | ||
| $environment = isset($env) ? $env : "testing"; | ||
| @endsetup | ||
|
|
||
| If needed, you may pass variables into the Envoy file using command line switches: | ||
| You may also use ```@include``` to include any outside PHP files: | ||
|
|
||
| envoy run deploy --branch=master | ||
| @include('vendor/autoload.php'); | ||
|
|
||
| You may use the options via the Blade syntax you are used to: | ||
| #### Confirming Tasks | ||
|
|
||
| @servers(['web' => '192.168.1.1']) | ||
| 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']) | ||
| @task('deploy', ['on' => 'web', 'confirm' => true]) | ||
| cd site | ||
| git pull origin {{ $branch }} | ||
| php artisan migrate | ||
| @endtask | ||
|
|
||
| #### Bootstrapping | ||
|
|
||
| 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 | ||
| <a name="task-variables"></a> | ||
| ### Task Variables | ||
|
|
||
| You may also use ```@include``` to include any PHP files: | ||
| If needed, you may pass variables into the Envoy file using command line switches, allowing you to customize your tasks: | ||
|
|
||
| @include('vendor/autoload.php'); | ||
| envoy run deploy --branch=master | ||
|
|
||
| #### Confirming Tasks Before Running | ||
| You may use the options in your tasks via Blade's "echo" syntax: | ||
|
|
||
| If you would like to be prompted for confirmation before running a given task on your servers, you may use the `confirm` directive: | ||
| @servers(['web' => '192.168.1.1']) | ||
|
|
||
| @task('deploy', ['on' => 'web', 'confirm' => true]) | ||
| @task('deploy', ['on' => 'web']) | ||
| cd site | ||
| git pull origin {{ $branch }} | ||
| php artisan migrate | ||
| @endtask | ||
|
|
||
| <a name="envoy-multiple-servers"></a> | ||
| ## Multiple Servers | ||
| ### Multiple Servers | ||
|
|
||
| You may easily run a task across multiple servers. Simply list the servers in the task declaration: | ||
| 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']) | ||
|
|
||
|
|
@@ -99,10 +99,9 @@ You may easily run a task across multiple servers. Simply list the servers in th | |
|
|
||
| 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. | ||
|
|
||
| <a name="envoy-parallel-execution"></a> | ||
| ## Parallel Execution | ||
| #### Parallel Execution | ||
|
|
||
| If you would like to run a task across multiple servers in parallel, simply add the `parallel` option to your task declaration: | ||
| 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']) | ||
|
|
||
|
|
@@ -113,36 +112,44 @@ If you would like to run a task across multiple servers in parallel, simply add | |
| @endtask | ||
|
|
||
| <a name="envoy-task-macros"></a> | ||
| ## Task Macros | ||
| ### Task Macros | ||
|
|
||
| Macros allow you to define a set of tasks to be run in sequence using a single command. For instance: | ||
| 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') | ||
| foo | ||
| bar | ||
| git | ||
| composer | ||
| @endmacro | ||
|
|
||
| @task('foo') | ||
| echo "HELLO" | ||
| @task('git') | ||
| git pull origin master | ||
| @endtask | ||
|
|
||
| @task('bar') | ||
| echo "WORLD" | ||
| @task('composer') | ||
| composer install | ||
| @endtask | ||
|
|
||
| The `deploy` macro can now be run via a single, simple command: | ||
| Once the macro has been defined, you may run it via single, simple command: | ||
|
|
||
| envoy run deploy | ||
|
|
||
| <a name="envoy-running-tasks"></a> | ||
| ## Running Tasks | ||
|
|
||
| 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 | ||
|
|
||
| <a name="envoy-notifications"></a> | ||
| <a name="envoy-hipchat-notifications"></a> | ||
| ## Notifications | ||
|
|
||
| #### HipChat | ||
| <a name="hipchat"></a> | ||
| ### HipChat | ||
|
|
||
| After running a task, you may send a notification to your team's HipChat room using the simple `@hipchat` directive: | ||
| 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']) | ||
|
|
||
|
|
@@ -154,17 +161,16 @@ After running a task, you may send a notification to your team's HipChat room us | |
| @hipchat('token', 'room', 'Envoy') | ||
| @endafter | ||
|
|
||
| You can also specify a custom message to the hipchat room. Any variables declared in ```@setup``` or included with ```@include``` will be available for use in the message: | ||
| If you wish, you may also pas 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 on [$environment]") | ||
| @hipchat('token', 'room', 'Envoy', "{$task} ran in the {$env} environment.") | ||
| @endafter | ||
|
|
||
| This is an amazingly simple way to keep your team notified of the tasks being run on the server. | ||
|
|
||
| #### Slack | ||
| <a name="slack"></a> | ||
| ### Slack | ||
|
|
||
| The following syntax may be used to send a notification to [Slack](https://slack.com): | ||
| 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') | ||
|
|
@@ -174,19 +180,8 @@ You may retrieve your webhook URL by creating an `Incoming WebHooks` integration | |
|
|
||
| https://hooks.slack.com/services/ZZZZZZZZZ/YYYYYYYYY/XXXXXXXXXXXXXXX | ||
|
|
||
| You may provide one of the following for the channel argument: | ||
| You may provide one of the following as the channel argument: | ||
|
|
||
| - To send the notification to a channel: `#channel` | ||
| - To send the notification to a user: `@user` | ||
|
|
||
| If no `channel` argument is provided the default channel will be used. | ||
|
|
||
| > Note: Slack notifications will only be sent if all tasks complete successfully. | ||
| <a name="envoy-updating-envoy"></a> | ||
| ## Updating Envoy | ||
|
|
||
| To update Envoy, simply use Composer: | ||
|
|
||
| composer global update | ||
|
|
||