Laravel Envoy en 10.x: Automatización de Despliegue

Introducción
Instalación
Escribir Tareas
Ejecución de Tareas
- Confirmar Ejecución de Tarea
Notificaciones

Introducción

Laravel Envoy es una herramienta para ejecutar tareas comunes en servidores remotos. Utilizando la sintaxis de estilo Blade, puede configurar fácilmente tareas para implementación, comandos Artisan y más. Actualmente, Envoy solo es compatible con los sistemas operativos Mac y Linux. Sin embargo, el soporte de Windows es posible mediante WSL2.

Instalación

Primero, instale Envoy en su proyecto utilizando el administrador de paquetes Composer:

composer require laravel/envoy --dev

Una vez instalado Envoy, el ejecutable de Envoy estará disponible en el directorio vendor/bin de su aplicación:

php vendor/bin/envoy

Escribir Tareas

Definir Tareas

Las tareas son el bloque de construcción básico de Envoy. Las tareas definen los comandos de shell que deben ejecutarse en sus servidores remotos cuando se invoca la tarea. Por ejemplo, podría definir una tarea que ejecute el comando php artisan queue:restart en todos los servidores de trabajadores de cola de su aplicación.

Todas sus tareas de Envoy deben definirse en un archivo Envoy.blade.php en la raíz de su aplicación. Aquí tienes un ejemplo para empezar:

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

Como puedes ver, se define un array de @servers en la parte superior del archivo, lo que te permite hacer referencia a estos servidores a través de la opción on de tus declaraciones de tarea. La declaración @servers siempre debe colocarse en una sola línea. Dentro de tus declaraciones @task, debes colocar los comandos de shell que se deben ejecutar en tus servidores cuando se invoque la tarea.

Tareas Locales

Puedes forzar la ejecución de un script en tu computadora local especificando la dirección IP del servidor como 127.0.0.1:

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

Importar Tareas de Envoy

Usando la directiva @import, puedes importar otros archivos de Envoy para que sus historias y tareas se agreguen a las tuyas. Después de importar los archivos, puedes ejecutar las tareas que contienen como si estuvieran definidas en tu propio archivo de Envoy:

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

Múltiples Servidores

Envoy te permite ejecutar fácilmente una tarea en varios servidores. Primero, agrega servidores adicionales a tu declaración @servers. A cada servidor se le debe asignar un nombre único. Una vez que hayas definido tus servidores adicionales, puedes enumerar cada uno de los servidores 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 Paralela

Por defecto, las tareas se ejecutarán en cada servidor de forma serial. En otras palabras, una tarea terminará de ejecutarse en el primer servidor antes de proceder a ejecutarse en el segundo servidor. Si deseas ejecutar una tarea en varios servidores en paralelo, agrega la opción parallel a la declaración de tu tarea:

@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

Configuración

A veces, es posible que necesite ejecutar código PHP arbitrario antes de ejecutar sus tareas de Envoy. Puede utilizar la directiva @setup para definir un bloque de código PHP que se debe ejecutar antes de sus tareas:

@setup
    $now = new DateTime;
@endsetup

Si necesita requerir otros archivos PHP antes de que se ejecute su tarea, puede utilizar la directiva @include en la parte superior de su archivo Envoy.blade.php:

@include('vendor/autoload.php')
 
@task('restart-queues')
    # ...
@endtask

Variables

Si es necesario, puede pasar argumentos a las tareas de Envoy especificándolos en la línea de comandos al invocar Envoy:

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

Puede acceder a las opciones dentro de sus tareas mediante la sintaxis de "echo" de Blade. También puede definir declaraciones if y bucles Blade dentro de sus tareas. Por ejemplo, verifiquemos la presencia de la variable $branch antes de ejecutar el comando 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

Historias

Las historias agrupan un conjunto de tareas bajo un nombre único y conveniente. Por ejemplo, una historia de deploy puede ejecutar las tareas update-code e install-dependencies enumerando los nombres de las tareas dentro de su definición:

@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 que se ha escrito la historia, puede invocarla de la misma manera que invocaría una tarea:

php vendor/bin/envoy run deploy

Ganchos

Cuando se ejecutan tareas e historias, se ejecutan varios ganchos. Los tipos de ganchos admitidos por Envoy son @before, @after, @error, @success y @finished. Todo el código en estos ganchos se interpreta como PHP y se ejecuta localmente, no en los servidores remotos con los que interactúan sus tareas.

Puede definir tantos de cada uno de estos ganchos como desee. Se ejecutarán en el orden en que aparecen en su script de Envoy.

`@before`

Antes de cada ejecución de tarea, se ejecutarán todos los ganchos @before registrados en su script de Envoy. Los ganchos @before reciben el nombre de la tarea que se ejecutará:

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

`@after`

Después de cada ejecución de tarea, se ejecutarán todos los ganchos @after registrados en su script de Envoy. Los ganchos @after reciben el nombre de la tarea que se ejecutó:

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

`@error`

Después de cada falla de tarea (sale con un código de estado mayor que 0), se ejecutarán todos los ganchos @error registrados en su script de Envoy. Los ganchos @error reciben el nombre de la tarea que se ejecutó:

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

`@success`

Si todas las tareas se han ejecutado sin errores, se ejecutarán todos los ganchos @success registrados en su script de Envoy:

@success
    // ...
@endsuccess

`@finished`

Después de que se hayan ejecutado todas las tareas (independientemente del estado de salida), se ejecutarán todos los ganchos @finished. Los ganchos @finished reciben el código de estado de la tarea completada, que puede ser null o un entero mayor o igual a 0:

@finished
    if ($exitCode > 0) {
       // Hubo errores en una de las tareas...
    }
@endfinished

Ejecución de Tareas

Para ejecutar una tarea o historia que está definida en el archivo Envoy.blade.php de su aplicación, ejecute el comando run de Envoy, pasando el nombre de la tarea o historia que le gustaría ejecutar. Envoy ejecutará la tarea y mostrará la salida de sus servidores remotos a medida que se ejecuta la tarea:

php vendor/bin/envoy run deploy

Confirmar Ejecución de Tarea

Si desea que se le pida confirmación antes de ejecutar una tarea determinada en sus servidores, debe agregar la directiva confirm a su declaración de tarea. Esta opción 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 admite el envío de notificaciones a Slack después de cada tarea ejecutada. La directiva @slack acepta una URL de gancho de Slack y un canal / nombre de usuario. Puede obtener su URL de gancho recuperando su URL de gancho creando una integración de "Incoming WebHooks" en su panel de control de Slack.

Debe pasar la URL completa del gancho como primer argumento dado a la directiva @slack. El segundo argumento dado a la directiva @slack debe ser un nombre de canal (#channel) o un nombre de usuario (@user):

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

Por defecto, las notificaciones de Envoy enviarán un mensaje al canal de notificación describiendo la tarea que se ejecutó. Sin embargo, puede sobrescribir este mensaje con su propio mensaje personalizado pasando un tercer argumento a la directiva @slack:

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

Discord

Envoy también admite el envío de notificaciones a Discord después de cada tarea ejecutada. La directiva @discord acepta una URL de gancho de Discord y un mensaje. Puede obtener su URL de gancho creando un "Webhook" en la configuración de su servidor y eligiendo a qué canal debe enviar el gancho. Debe pasar la URL completa del gancho en la directiva @discord:

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

Envoy también admite el envío de notificaciones a Telegram después de cada tarea ejecutada. La directiva @telegram acepta un ID de bot de Telegram y un ID de chat. Puede obtener su ID de bot creando un nuevo bot usando BotFather. Puede obtener un ID de chat válido usando @username_to_id_bot. Debe pasar el ID completo del bot y el ID del chat en la directiva @telegram:

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

Microsoft Teams

Envoy también admite el envío de notificaciones a Microsoft Teams después de cada tarea ejecutada. La directiva @microsoftTeams acepta un Webhook de Teams (obligatorio), un mensaje, un color de tema (success, info, warning, error) y una matriz de opciones. Puede obtener su Webhook de Teams creando un nuevo incoming webhook. La API de Teams tiene muchas otras atributos para personalizar su cuadro de mensaje como título, resumen y secciones. Puede encontrar más información en la documentación de Microsoft Teams. Debe pasar la URL completa del gancho en la directiva @microsoftTeams:

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