Introducción
Laravel Envoy proporciona una sintaxis limpia y mínima para definir las tareas comunes que ejecutas en tus servidores remotos. Utilizando el estilo de sintaxis de Blade, puedes configurar fácilmente tareas para deploy, comandos de Artisan y más. Envoy solamente es compatible con sistemas operativos Mac y Linux.
Instalación
Primero, instala Envoy utilizando el comando de Composer global require:
composer global require laravel/envoy
Dado que las librerías globales de Composer ocasionalmente pueden causar conflictos en la versión del paquete, puedes considerar utilizar cgr, el cual es un reemplazo directo para el comando composer global require. Las instrucciones de instalación de la librería cgr pueden ser encontradas en GitHub.
Asegúrate de colocar el directorio ~/.composer/vendor/bin en tu PATH para que el ejecutable envoy pueda ser localizado cuando se ejecute el comando envoy en tu terminal.
Actualizar envoy
También puedes usar Composer para mantener tu instalación de Envoy actualizada. Ejecutar el comando composer global update actualizará todos tus paquetes de Composer instalados globalmente:
composer global update
Escribir tareas
Todas tus tareas de Envoy deberán definirse en un archivo Envoy.blade.php en la raíz de tu proyecto. Aquí un ejemplo para comenzar:
@servers(['web' => ['[email protected]']]) @task('foo', ['on' => 'web']) ls -la @endtask
Como puedes ver, un arreglo @servers es definido al inicio del archivo, permitiéndote hacer referencia a estos servidores en la opción on en la declaración de tus tareas. Dentro de tus declaraciones @task, deberás colocar el código Bash que se deberá ejecutar en tu servidor una vez que la tarea sea ejecutada.
Puedes forzar que un script se ejecute localmente especificando la dirección IP del servidor como 127.0.0.1:
@servers(['localhost' => '127.0.0.1'])
Setup
En ocasiones, puede que necesites ejecutar algún código PHP antes de tus tareas de Envoy. Puedes hacer uso de la directiva @setup para declarar variables y hacer uso de PHP en general antes de que tus otras tareas sean ejecutadas:
@setup
$now = new DateTime();
$environment = isset($env) ? $env : "testing";
@endsetup
Si necesitas de otros archivos PHP antes de ejecutar tus tareas, puedes utilizar la directiva @include al principio de tu archivo Envoy.blade.php:
@include('vendor/autoload.php')
@task('foo')
# ...
@endtask
También puedes importar otros archivos de Envoy para que así sus historias y tareas sean agregadas a los tuyos. Luego de que han sido importados, puedes ejecutar las tareas en dichos archivos como si estuvieran definidas en los tuyos. Debes usar la directiva @import al principio de tu archivo Envoy.blade.php:
@import('package/Envoy.blade.php')
Variables
Si es necesario, puedes pasar valores de opciones a las tareas de Envoy usando la línea de comandos:
envoy run deploy --branch=master
Puedes acceder a las opciones en tus tareas por medio de la sintaxis «echo» de Blade. También puedes usar declaraciones if y bucles dentro de tus tareas. Por ejemplo, para verificar la presencia de la variable $branch antes de ejecutar el comando git pull:
@servers(['web' => '192.168.1.1'])
@task('deploy', ['on' => 'web'])
cd site
@if ($branch)
git pull origin {{ $branch }}
@endif
php artisan migrate
@endtask
Historias
Las historias agrupan un conjunto de tareas con un nombre único y conveniente, permitiendo agrupar tareas pequeñas enfocándose en tareas más grandes. Por ejemplo, una historia deploy puede ejecutar las tareas git y composer al listar los nombres de las tareas en tu definición:
@servers(['web' => '192.168.1.1'])
@story('deploy')
git
composer
@endstory
@task('git')
git pull origin master
@endtask
@task('composer')
composer install
@endtask
Una vez que hayas finalizado de escribir tu historia, puedes ejecutarla como una tarea típica:
envoy run deploy
Múltiples servidores
Envoy te permite fácilmente ejecutar tareas a través de múltiples servidores. Primero, agrega servidores adicionales a tu declaración @servers. A cada servidor se le debe asignar un nombre único. Una vez definidos los servidores adicionales, deberás indicar en cuáles servidores se van a ejecutar las tareas, esto puede hacerse en el arreglo on de cada tarea:
@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])
@task('deploy', ['on' => ['web-1', 'web-2']])
cd site
git pull origin {{ $branch }}
php artisan migrate
@endtask
Ejecución paralela
Por defecto, las tareas serán ejecutadas en cada servidor de forma secuencial. En otras palabras, una tarea finaliza su ejecución en el primer servidor antes de proceder a ejecutarse en el segundo servidor. Si deseas ejecutar una tarea a través de múltiples 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 site
git pull origin {{ $branch }}
php artisan migrate
@endtask
Ejecutar tareas
Para ejecutar una tarea o historia que esté definida en tu archivo Envoy.blade.php, ejecuta el comando de Envoy run, pasando el nombre de la tarea o historia que deseas ejecutar. Envoy va a ejecutar la tarea y mostrará el resultado de los servidores mientras se ejecuta la tarea:
envoy run deploy
Confirmar ejecución de tarea
Si deseas que se solicite confirmación antes de ejecutar una tarea en tus servidores, deberás añadir la directiva confirm a la declaración de tu tarea. Esta opción es particularmente útil para operaciones destructivas:
@task('deploy', ['on' => 'web', 'confirm' => true])
cd site
git pull origin {{ $branch }}
php artisan migrate
@endtask
Notificaciones
Slack
Envoy también permite enviar notificaciones a Slack después de ejecutar cada tarea. La directiva @slack acepta una URL de webhook a Slack y un nombre de canal. Puedes recuperar tu URL de webhook creando una integración «Incoming WebHooks» en el panel de control de Slack. Debes pasar la URL de webhook completa en la directiva @slack:
@finished
@slack('webhook-url', '#bots')
@endfinished
Puedes proporcionar uno de los siguientes como el argumento del canal:
- Para enviar notificaciones a un canal:
#channel - Para enviar notificaciones a un usuario:
@user
Discord
Envoy también soporta el envío de notificaciones a Discord después de que cada tarea es ejecutada. La directiva @discord acepta una URL de WebHook y un mensaje de Discord. Puedes recuperar tu URL de webhook creando una «Webhook» en los ajustes de tu servidor y seleccionando en cuál canal publicar la webhook. También deberías pasar la URL de Webhook completa en la directiva @discord:
@finished
@discord('discord-webhook-url')
@endfinished
Regístrate hoy en Styde y obtén acceso a todo nuestro contenido.
Lección anterior Laravel Cashier - Documentación de Laravel 6 Lección siguiente Laravel Horizon - Documentación de Laravel 6