Skip to content

Commit

Permalink
envoy docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@taylorotwell
taylorotwell committed Aug 3, 2016
1 parent 98ebcc3 commit 0a8292b
Showing 1 changed file with 48 additions and 62 deletions.
110 changes: 48 additions & 62 deletions envoy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,31 +2,34 @@

- [Introduction](#introduction)
- [Writing Tasks](#writing-tasks)
- [Task Setup](#task-setup)
- [Task Variables](#task-variables)
- [Multiple Servers](#envoy-multiple-servers)
- [Task Macros](#envoy-task-macros)
- [Task Stories](#envoy-task-stories)
- [Running Tasks](#envoy-running-tasks)
- [Confirming Task Execution](#confirming-task-execution)
- [Notifications](#envoy-notifications)
- [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. Currently, Envoy only supports the Mac and 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 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

First, install Envoy using the Composer `global` command:
First, install Envoy using the Composer `global require` 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.
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).

> {tip} Make sure to place the `~/.composer/vendor/bin` directory in your PATH so the `envoy` executable is found when running the `envoy` command in your terminal.
#### Updating Envoy

You may also use Composer to keep your Envoy installation up to date:
You may also use Composer to keep your Envoy installation up to date. Issuing the the `composer global update` command will update all of your globally installed Composer packages:

composer global update

Expand All @@ -35,65 +38,62 @@ You may also use Composer to keep your Envoy installation up to date:

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'])
@servers(['web' => ['user@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, 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
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 should run on your server when the task is executed.

You can define a script to run locally by defining a server reference to the local host:
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'])

#### Bootstrapping
<a name="task-setup"></a>
### Task Setup

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:
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

You may also use ```@include``` to include any outside PHP files:
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')

#### Confirming Tasks

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
@task('foo')
# ...
@endtask

<a name="task-variables"></a>
### Task Variables

If needed, you may pass variables into the Envoy file using command line switches, allowing you to customize your tasks:
If needed, you may pass option values into Envoy tasks using the command line:

envoy run deploy --branch=master

You may use the options in your tasks via Blade's "echo" syntax:
You may use access the options in your tasks via Blade's "echo" syntax. Of course, 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
git pull origin {{ $branch }}

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

php artisan migrate
@endtask

<a name="envoy-multiple-servers"></a>
### Multiple Servers

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:
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'])

Expand All @@ -103,11 +103,9 @@ You may easily run a task across multiple servers. First, add additional servers
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

If you would like to run a task across multiple servers in parallel, add the `parallel` option to your task declaration:
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'])

Expand All @@ -117,17 +115,17 @@ If you would like to run a task across multiple servers in parallel, add the `pa
php artisan migrate
@endtask

<a name="envoy-task-macros"></a>
### Task Macros
<a name="envoy-task-stories"></a>
### Task Stories

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:
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'])

@macro('deploy')
@story('deploy')
git
composer
@endmacro
@endstory

@task('git')
git pull origin master
Expand All @@ -137,57 +135,45 @@ Macros allow you to define a set of tasks to be run in sequence using a single c
composer install
@endtask

Once the macro has been defined, you may run it via single, simple command:
Once the story has been written, you may run it just like a typical task:

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:
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 task

<a name="envoy-notifications"></a>
<a name="envoy-hipchat-notifications"></a>
## Notifications

<a name="hipchat"></a>
### HipChat
<a name="confirming-task-execution"></a>
### Confirming Task Execution

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'])
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('foo', ['on' => 'web'])
ls -la
@task('deploy', ['on' => 'web', 'confirm' => true])
cd site
git pull origin {{ $branch }}
php artisan migrate
@endtask

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

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
<a name="envoy-notifications"></a>
<a name="envoy-hipchat-notifications"></a>
## Notifications

<a name="slack"></a>
### Slack

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:
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:

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

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:

<div class="content-list" markdown="1">
- To send the notification to a channel: `#channel`
- To send the notification to a user: `@user`
</div>

0 comments on commit 0a8292b

Please sign in to comment.