Envoy

Introducción

Laravel Envoy es una herramienta para ejecutar tareas habituales en servidores remotos. Con la misma sintaxis de Blade puedes definir fácilmente tareas como despliegues o la ejecución de comandos Artisan.

Envoy solo soporta actualmente macOS y Linux. Para usarlo en Windows necesitas hacerlo a través de WSL2.

Instalación

Instala Envoy en el proyecto con el gestor de paquetes Composer.

composer require laravel/envoy --dev

Tras la instalación, el ejecutable de Envoy quedará disponible en el directorio vendor/bin.

php vendor/bin/envoy

Creación de tareas

Definir una tarea

Las tareas son la unidad básica de Envoy. Una tarea define los comandos de shell que deben ejecutarse en el servidor remoto al lanzarla. Por ejemplo, puedes definir una tarea que ejecute php artisan queue:restart en todos los servidores de workers de cola. Todas las tareas de Envoy se definen en el archivo Envoy.blade.php que está en la raíz de la aplicación.

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

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

Como se ve arriba, al principio del archivo defines el array @servers y en la opción on de cada declaración de tarea haces referencia a esos servidores. La declaración @servers debe escribirse siempre en una sola línea. Dentro de la declaración @task describes los comandos de shell que se ejecutarán en el servidor al lanzar la tarea.

Tareas locales

Si indicas 127.0.0.1 como IP del servidor, forzarás la ejecución del script en tu equipo local.

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

Importar tareas de Envoy

Con la directiva @import puedes importar otros archivos de Envoy y añadir sus stories y tareas a tu propio archivo. Tras la importación, puedes ejecutar las tareas igual que si las hubieras definido en tu archivo Envoy.

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

Múltiples servidores

Con Envoy puedes ejecutar fácilmente una misma tarea en varios servidores. Primero añade servidores adicionales a la declaración @servers asignándoles un nombre único. Una vez añadidos, enuméralos en el array on de la tarea.

@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

Ejecución en paralelo

Por defecto, las tareas se ejecutan de forma serial en cada servidor. Es decir, cuando una tarea finaliza en el primer servidor, pasa al segundo. Para ejecutar la tarea en paralelo en varios servidores, añade la opción parallel a la declaración.

@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

Si necesitas ejecutar código PHP arbitrario antes de que se lancen las tareas de Envoy, usa la directiva @setup.

@setup
    $now = new DateTime;
@endsetup

Si necesitas incluir otros archivos PHP antes de ejecutar las tareas, utiliza @include al principio del archivo Envoy.blade.php.

@include('vendor/autoload.php')

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

Variables

Al invocar una tarea de Envoy, puedes pasar argumentos desde la línea de comandos.

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

Dentro de la tarea puedes acceder a las opciones con la sintaxis «echo» de Blade. También puedes usar los if y bucles de Blade. Por ejemplo, para comprobar si existe la variable $branch antes de ejecutar git pull:

@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

Una story agrupa un conjunto de tareas bajo un nombre cómodo. Por ejemplo, una story deploy puede ejecutar juntas las tareas update-code e install-dependencies.

@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

Una vez escrita la story, puedes invocarla igual que una tarea.

php vendor/bin/envoy run deploy

Hooks de finalización

Al ejecutar tareas o stories se ejecutan varios hooks. Los tipos que soporta Envoy son @before, @after, @error, @success y @finished. Todo el código dentro de estos hooks se interpreta como PHP y se ejecuta en local, no en los servidores remotos sobre los que opera la tarea. Puedes definir tantos hooks como quieras, y se ejecutarán en el orden en que aparezcan en el script de Envoy.

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

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

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

@success
    // ...
@endsuccess

@finished
    if ($exitCode > 0) {
        // Alguna de las tareas ha fallado...
    }
@endfinished

El hook @finished recibe el código de estado de la ejecución de las tareas. Es null o un entero mayor o igual que 0.

Ejecutar tareas

Para ejecutar una tarea o story definida en el archivo Envoy.blade.php de la aplicación, ejecuta el comando run de Envoy y pásale el nombre de la tarea o story. Envoy ejecutará la tarea y mostrará la salida del servidor remoto durante la ejecución.

php vendor/bin/envoy run deploy

Confirmar la ejecución de la tarea

Si quieres solicitar confirmación antes de ejecutar una tarea concreta en el servidor, añade la directiva confirm a la declaración de la tarea. Es especialmente útil para operaciones destructivas.

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

Notificaciones

Slack

Envoy puede enviar notificaciones a Slack tras la ejecución de cada tarea. La directiva @slack recibe la URL del webhook de Slack y el nombre del canal (o del usuario). La URL del webhook se obtiene creando una integración «Incoming WebHooks» en el panel de control de Slack. En el primer argumento de @slack pasa la URL completa del webhook. En el segundo indica el nombre del canal (#channel) o del usuario (@user).

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

Por defecto, se envía al canal un mensaje que describe la tarea ejecutada. Puedes sobrescribirlo con tu propio mensaje pasando un tercer argumento a @slack.

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

Discord

Envoy también permite enviar notificaciones a Discord tras cada ejecución. La directiva @discord recibe la URL del webhook de Discord y un mensaje. La URL se obtiene creando un «Webhook» en la configuración del servidor y seleccionando el canal de destino.

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

Envoy también admite enviar notificaciones a Telegram tras cada ejecución. La directiva @telegram recibe el ID del bot de Telegram y el Chat ID. El ID del bot se obtiene creando un nuevo bot en BotFather. El Chat ID puede obtenerse con @username_to_id_bot.

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

Microsoft Teams

Envoy también admite enviar notificaciones a Microsoft Teams tras cada ejecución. La directiva @teams recibe el webhook de Teams (obligatorio), el mensaje, un color de tema (success, info, warning, error) y, opcionalmente, un array de configuración. El webhook de Teams se obtiene creando un Incoming Webhook. La API de Teams tiene muchos más ajustes que te permiten crear tus propias tarjetas de mensaje. Para más detalles consulta la documentación de Microsoft Teams.

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

Envoy asume conexiones SSH con los servidores remotos. Según tu entorno de ejecución, deberás preparar de antemano la configuración de la autenticación por clave y el control de acceso al servidor. Si necesitas una automatización de despliegue más avanzada, valora la guía de despliegue o la combinación con GitHub Actions.

Arquitectura

Base de datos

Eloquent

Seguridad

Eventos

Correo y notificaciones

Pagos

Procesamiento asíncrono

Comunicación en tiempo real

Programación de tareas

Caché y optimización

Internacionalización

Archivos y almacenamiento

Depuración y monitoreo

Consola y CLI

Rendimiento

Frontend

Desarrollo con IA

Entorno de desarrollo

Introducción

Instalación

Creación de tareas

Definir una tarea

Tareas locales

Importar tareas de Envoy

Múltiples servidores

Ejecución en paralelo

Setup

Variables

Stories

Hooks de finalización

Ejecutar tareas

Confirmar la ejecución de la tarea

Notificaciones

Slack

Discord

Telegram

Microsoft Teams

​Introducción

​Instalación

​Creación de tareas

​Definir una tarea

​Tareas locales

​Importar tareas de Envoy

​Múltiples servidores

​Ejecución en paralelo

​Setup

​Variables

​Stories

​Hooks de finalización

​Ejecutar tareas

​Confirmar la ejecución de la tarea

​Notificaciones

​Slack

​Discord

​Telegram

​Microsoft Teams

Introducción

Instalación

Creación de tareas

Definir una tarea

Tareas locales

Importar tareas de Envoy

Múltiples servidores

Ejecución en paralelo

Setup

Variables

Stories

Hooks de finalización

Ejecutar tareas

Confirmar la ejecución de la tarea

Notificaciones

Slack

Discord

Telegram

Microsoft Teams