Laravel Envoy

Elegant SSH tasks for PHP.

Installation
Running Tasks
Passing Variables
Macros
Multiple Servers
Parallel Execution
HipChat Notifications

What Is It?

Envoy is a simple SSH task runner for PHP 5.4 or greater. It is loosely inspired by Python Fabric. It supports:

Clean, minimal syntax for defining tasks.
Utilizes ~/.ssh/config settings.
Parallel execution across multiple servers.
Stops execution if any command fails.
Macros quickly group tasks into a single command.
HipChat notifications.

Envoy is perfect for automating common tasks you perform on your remote servers such as deployment, restarting queues, etc.

Installation

The simplest method of installation is to simply download the envoy.phar file from this repository.

To compile the envoy.phar file yourself, clone this repository and run the box build command. To run box commands, you must install kherge/Box.

Once the Phar has been compiled, move it to /usr/local/bin as envoy for easy access. You may need to grant the file execution privileges (chmod +x) before running tasks.

Updating Envoy

To update Envoy, you may use the envoy self-update command.

Running Tasks

Create an Envoy.blade.php file in any directory. Here is a sample file to get you started:

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

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

You may define multiple tasks in a given file. To run a task, use the run command:

envoy run foo

Note: For best results, your machine should have SSH key access to the target.

Passing Variables

envoy run foo --branch=master

@task('foo')
	cd site
	git pull origin {{ $branch }}
	php artisan migrate
@endtask

Macros

Macros allow you to define a set of tasks to run in sequence using a single command. For instance:

@macro('deploy')
	foo
	bar
@endmacro

@task('foo')
	echo "HELLO"
@endtask

@task('bar')
	echo "WORLD"
@endtask

envoy run deploy

Multiple Servers

@servers(['web' => 'root@192.168.1.1', 'db' => 'root@192.168.1.2'])

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

Note: Tasks on multiple servers will be run serially by default.

Parallel Execution

To run a task across multiple servers in parallel, use the parallel option on the task:

@servers(['web' => 'root@192.168.1.1', 'db' => 'root@192.168.1.2'])

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

HipChat Notifications

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

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

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

Note: HipChat notifications will only be sent if all tasks complete successfully.

duellsy / envoy