Envoy

Introduction

Laravel Envoy is a tool for executing common tasks you run on your remote servers. Using Blade style syntax, you can easily set up tasks for deployment, Artisan commands, and more.

Currently, Envoy only supports the Mac and Linux operating systems. However, Windows support is achievable using WSL2.

Installation

First, install Envoy into your project using the Composer package manager:

composer require laravel/envoy --dev

Once Envoy has been installed, the Envoy binary will be available in your application’s vendor/bin directory:

php vendor/bin/envoy

Writing Tasks

Defining Tasks

Tasks are the basic building block of Envoy. Tasks define the shell commands that should execute on your remote servers when the task is invoked. All of your Envoy tasks should be defined in an Envoy.blade.php file at the root of your application.

@servers(['web' => ['[email protected]'], 'workers' => ['[email protected]']])

@task('restart-queues', ['on' => 'workers'])
    cd /home/user/example.com
    php artisan queue:restart
@endtask

As you can see, an array of @servers is defined at the top of the file, allowing you to reference these servers via the on option of your task declarations. The @servers declaration should always be placed on a single line.

Local Tasks

You can force a script to run on your local computer by specifying the server’s IP address as 127.0.0.1:

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

Importing Envoy Tasks

Using the @import directive, you may import other Envoy files so their stories and tasks are added to yours.

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

Multiple Servers

Envoy allows you to easily run a task across multiple servers. First, add additional servers to your @servers declaration. Once you have defined your additional servers you may list each of them 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 /home/user/example.com
    git pull origin {{ $branch }}
    php artisan migrate --force
@endtask

Parallel Execution

By default, tasks will be executed on each server serially. 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 /home/user/example.com
    git pull origin {{ $branch }}
    php artisan migrate --force
@endtask

Setup

Sometimes, you may need to execute arbitrary PHP code before running your Envoy tasks. You may use the @setup directive:

@setup
    $now = new DateTime;
@endsetup

If you need to require other PHP files before your task is executed, use the @include directive at the top of your Envoy.blade.php file:

@include('vendor/autoload.php')

@task('restart-queues')
    # ...
@endtask

Variables

If needed, you may pass arguments to Envoy tasks by specifying them on the command line when invoking Envoy:

php vendor/bin/envoy run deploy --branch=master

You may access the options within your tasks using Blade’s “echo” syntax and define if statements and loops:

@servers(['web' => ['[email protected]']])

@task('deploy', ['on' => 'web'])
    cd /home/user/example.com

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

    php artisan migrate --force
@endtask

Stories

Stories group a set of tasks under a single, convenient name.

@servers(['web' => ['[email protected]']])

@story('deploy')
    update-code
    install-dependencies
@endstory

@task('update-code')
    cd /home/user/example.com
    git pull origin master
@endtask

@task('install-dependencies')
    cd /home/user/example.com
    composer install
@endtask

Once the story has been written, you may invoke it in the same way you would invoke a task:

php vendor/bin/envoy run deploy

Hooks

When tasks and stories run, a number of hooks are executed. The hook types supported by Envoy are @before, @after, @error, @success, and @finished. All of the code in these hooks is interpreted as PHP and executed locally, not on the remote servers your tasks interact with.

@before
    if ($task === 'deploy') {
        // ...
    }
@endbefore

@after
    if ($task === 'deploy') {
        // ...
    }
@endafter

@error
    if ($task === 'deploy') {
        // ...
    }
@enderror

@success
    // ...
@endsuccess

@finished
    if ($exitCode > 0) {
        // There were errors in one of the tasks...
    }
@endfinished

The @finished hooks receive the status code of the completed task, which may be null or an integer greater than or equal to 0.

Running Tasks

To run a task or story that is defined in your application’s Envoy.blade.php file, execute Envoy’s run command:

php vendor/bin/envoy run deploy

Confirming Task Execution

If you would like to be prompted for confirmation before running a given task on your servers, add the confirm directive to your task declaration. This option is particularly useful for destructive operations:

@task('deploy', ['on' => 'web', 'confirm' => true])
    cd /home/user/example.com
    git pull origin {{ $branch }}
    php artisan migrate
@endtask

Notifications

Slack

Envoy supports sending notifications to Slack after each task is executed. The @slack directive accepts a Slack hook URL and a channel / user name.

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

You may overwrite the default message by passing a third argument to the @slack directive:

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

Discord

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

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

Microsoft Teams

The @teams directive accepts a Teams webhook (required), a message, a theme color (success, info, warning, error), and an optional array of options.

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

Envoy relies on SSH connections to your remote servers. Make sure key-based authentication and server access are configured before running tasks. For more advanced deployment automation, consider combining Envoy with the deployment guide or GitHub Actions.

Architecture

Database

Eloquent

Security

Events

Mail and Notifications

Payments

Asynchronous Processing

Real-time Communication

Scheduling

Cache and Optimization

Internationalization

Files and Storage

Debugging and Monitoring

Console and CLI

Performance

Frontend

AI Development

Development Environment

Introduction

Installation

Writing Tasks

Defining Tasks

Local Tasks

Importing Envoy Tasks

Multiple Servers

Parallel Execution

Setup

Variables

Stories

Hooks

Running Tasks

Confirming Task Execution

Notifications

Slack

Discord

Telegram

Microsoft Teams

​Introduction

​Installation

​Writing Tasks

​Defining Tasks

​Local Tasks

​Importing Envoy Tasks

​Multiple Servers

​Parallel Execution

​Setup

​Variables

​Stories

​Hooks

​Running Tasks

​Confirming Task Execution

​Notifications

​Slack

​Discord

​Telegram

​Microsoft Teams

Introduction

Installation

Writing Tasks

Defining Tasks

Local Tasks

Importing Envoy Tasks

Multiple Servers

Parallel Execution

Setup

Variables

Stories

Hooks

Running Tasks

Confirming Task Execution

Notifications

Slack

Discord

Telegram

Microsoft Teams