#Introducción
Laravel Envoy es una herramienta para ejecutar tareas comunes en sus servidores remotos. Usando la sintaxis estilo Blade, puede configurar fácilmente tareas para despliegues, comandos Artisan y más. Actualmente, Envoy solo soporta los sistemas operativos Mac y Linux. Sin embargo, el soporte para Windows es posible usando WSL2.
#Instalación
Primero, instale Envoy en su proyecto usando el gestor de paquetes Composer:
composer require laravel/envoy --dev
Una vez que Envoy esté instalado, el binario de Envoy estará disponible en el directorio vendor/bin de su aplicación:
php vendor/bin/envoy
#Escribiendo Tareas
#Definiendo Tareas
Las tareas son el bloque básico de Envoy. Las tareas definen los comandos 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 colas 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í tiene un ejemplo para comenzar:
@servers(['web' => ['user@192.168.1.1'], 'workers' => ['user@192.168.1.2']])
@task('restart-queues', ['on' => 'workers'])
cd /home/user/example.com
php artisan queue:restart
@endtask
Como puede ver, se define un arreglo de @servers al inicio del archivo, lo que le permite referenciar estos servidores mediante la opción on en la declaración de sus tareas. La declaración @servers siempre debe estar en una sola línea. Dentro de sus declaraciones @task, debe colocar los comandos shell que se ejecutarán en sus servidores cuando se invoque la tarea.
#Tareas Locales
Puede forzar que un script se ejecute en su computadora local especificando la dirección IP del servidor como 127.0.0.1:
@servers(['localhost' => '127.0.0.1'])
#Importando Tareas de Envoy
Usando la directiva @import, puede importar otros archivos Envoy para que sus historias y tareas se agreguen a las suyas. Después de importar los archivos, puede ejecutar las tareas que contienen como si estuvieran definidas en su propio archivo Envoy:
@import('vendor/package/Envoy.blade.php')
#Múltiples Servidores
Envoy le permite ejecutar fácilmente una tarea en múltiples servidores. Primero, agregue servidores adicionales a su declaración @servers. Cada servidor debe tener un nombre único. Una vez definidos los servidores adicionales, puede listar cada uno en el arreglo 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 ejecutan en cada servidor de forma secuencial. En otras palabras, una tarea termina en el primer servidor antes de continuar en el segundo servidor. Si desea ejecutar una tarea en múltiples servidores en paralelo, agregue la opción parallel a la declaración de su 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, puede necesitar ejecutar código PHP arbitrario antes de ejecutar sus tareas Envoy. Puede usar la directiva @setup para definir un bloque de código PHP que se ejecutará antes de sus tareas:
@setup
$now = new DateTime;
@endsetup
Si necesita requerir otros archivos PHP antes de que se ejecute su tarea, puede usar la directiva @include al inicio de su archivo Envoy.blade.php:
@include('vendor/autoload.php')
@task('restart-queues')
# ...
@endtask
#Variables
Si es necesario, puede pasar argumentos a las tareas 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 usando la sintaxis "echo" de Blade. También puede definir sentencias 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' => ['user@192.168.1.1']])
@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 deploy puede ejecutar las tareas update-code e install-dependencies listando los nombres de las tareas dentro de su definición:
@servers(['web' => ['user@192.168.1.1']])
@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 historia, puede invocarla de la misma forma que invoca una tarea:
php vendor/bin/envoy run deploy
#Hooks
Cuando se ejecutan tareas e historias, se ejecutan varios hooks. Los tipos de hooks soportados por Envoy son @before, @after, @error, @success y @finished. Todo el código en estos hooks se interpreta como PHP y se ejecuta localmente, no en los servidores remotos con los que interactúan sus tareas.
Puede definir tantos hooks de cada tipo como desee. Se ejecutarán en el orden en que aparecen en su script Envoy.
#@before
Antes de la ejecución de cada tarea, se ejecutarán todos los hooks @before registrados en su script Envoy. Los hooks @before reciben el nombre de la tarea que se ejecutará:
@before
if ($task === 'deploy') {
// ...
}
@endbefore
#@after
Después de la ejecución de cada tarea, se ejecutarán todos los hooks @after registrados en su script Envoy. Los hooks @after reciben el nombre de la tarea que se ejecutó:
@after
if ($task === 'deploy') {
// ...
}
@endafter
#@error
Después de cada fallo en una tarea (salida con un código de estado mayor que 0), se ejecutarán todos los hooks @error registrados en su script Envoy. Los hooks @error reciben el nombre de la tarea que se ejecutó:
@error
if ($task === 'deploy') {
// ...
}
@enderror
#@success
Si todas las tareas se ejecutaron sin errores, se ejecutarán todos los hooks @success registrados en su script Envoy:
@success
// ...
@endsuccess
#@finished
Después de que todas las tareas hayan sido ejecutadas (independientemente del código de salida), se ejecutarán todos los hooks @finished. Los hooks @finished reciben el código de estado de la tarea completada, que puede ser null o un integer mayor o igual a 0:
@finished
if ($exitCode > 0) {
// Hubo errores en una de las tareas...
}
@endfinished
#Ejecutando Tareas
Para ejecutar una tarea o historia 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 desea ejecutar. Envoy ejecutará la tarea y mostrará la salida de sus servidores remotos mientras la tarea se está ejecutando:
php vendor/bin/envoy run deploy
#Confirmando la Ejecución de Tareas
Si desea que se le solicite confirmación antes de ejecutar una tarea en sus servidores, debe agregar la directiva confirm a la declaración de su 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 soporta el envío de notificaciones a Slack después de que cada tarea se ejecuta. La directiva @slack acepta una URL de hook de Slack y un nombre de canal o usuario. Puede obtener su URL de webhook creando una integración de "Incoming WebHooks" en el panel de control de Slack.
Debe pasar la URL completa del webhook como primer argumento a la directiva @slack. El segundo argumento de 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 uno personalizado pasando un tercer argumento a la directiva @slack:
@finished
@slack('webhook-url', '#bots', 'Hello, Slack.')
@endfinished
#Discord
Envoy también soporta el envío de notificaciones a Discord después de que cada tarea se ejecuta. La directiva @discord acepta una URL de hook de Discord y un mensaje. Puede obtener su URL de webhook creando un "Webhook" en la configuración de su servidor y eligiendo a qué canal debe publicar el webhook. Debe pasar la URL completa del webhook a la directiva @discord:
@finished
@discord('discord-webhook-url')
@endfinished
#Telegram
Envoy también soporta el envío de notificaciones a Telegram después de que cada tarea se ejecuta. 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 de Chat a la directiva @telegram:
@finished
@telegram('bot-id','chat-id')
@endfinished
#Microsoft Teams
Envoy también soporta el envío de notificaciones a Microsoft Teams después de que cada tarea se ejecuta. La directiva @microsoftTeams acepta un Webhook de Teams (requerido), un mensaje, color de tema (success, info, warning, error) y un arreglo de opciones. Puede obtener su Webhook de Teams creando un nuevo incoming webhook. La API de Teams tiene muchos otros 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 webhook a la directiva @microsoftTeams:
@finished
@microsoftTeams('webhook-url')
@endfinished