Envoy

Introduction

Laravel Envoy est un outil qui permet d’exécuter des tâches courantes sur des serveurs distants. Grâce à la même syntaxe que Blade, vous pouvez définir facilement des tâches de déploiement ou d’exécution de commandes Artisan.

Envoy ne prend actuellement en charge que macOS et Linux. Sous Windows, vous devrez l’utiliser via WSL2.

Installation

Installez Envoy dans votre projet via le gestionnaire de packages Composer.

composer require laravel/envoy --dev

Une fois installé, l’exécutable d’Envoy est disponible dans le répertoire vendor/bin.

php vendor/bin/envoy

Création de tâches

Définir une tâche

Les tâches sont l’élément de base d’Envoy. Une tâche définit les commandes shell à exécuter sur un serveur distant lorsque la tâche est lancée. Vous pouvez par exemple définir une tâche qui exécute php artisan queue:restart sur tous les serveurs de workers de queue. Toutes les tâches Envoy se déclarent dans le fichier Envoy.blade.php à la racine de votre application.

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

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

Comme ci-dessus, on définit d’abord un tableau @servers en haut du fichier, puis on référence ces serveurs via l’option on de chaque déclaration de tâche. La déclaration @servers doit tenir sur une seule ligne. À l’intérieur d’un @task, vous décrivez les commandes shell à exécuter sur le serveur lors de l’exécution.

Tâches locales

En précisant l’adresse IP 127.0.0.1 du serveur, vous forcez l’exécution du script sur votre machine locale.

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

Importer un fichier Envoy

La directive @import permet d’importer d’autres fichiers Envoy afin d’ajouter leurs stories et leurs tâches au fichier courant. Une fois importées, vous exécutez ces tâches exactement comme celles définies dans votre propre fichier Envoy.

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

Plusieurs serveurs

Envoy permet d’exécuter facilement une même tâche sur plusieurs serveurs. Enregistrez d’abord les serveurs supplémentaires dans la déclaration @servers en leur donnant à chacun un nom unique. Ensuite, listez ces serveurs dans le tableau on de la tâche.

@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

Exécution en parallèle

Par défaut, la tâche s’exécute en série sur chaque serveur : l’exécution sur le second serveur ne démarre qu’une fois terminée sur le premier. Pour exécuter la tâche en parallèle, ajoutez l’option parallel à la déclaration de la tâche.

@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

Utilisez la directive @setup pour exécuter du code PHP quelconque avant d’exécuter les tâches Envoy.

@setup
    $now = new DateTime;
@endsetup

Si vous devez charger d’autres fichiers PHP avant les tâches, utilisez @include en haut de votre Envoy.blade.php.

@include('vendor/autoload.php')

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

Variables

Lors du lancement d’une tâche Envoy, vous pouvez lui passer des arguments depuis la ligne de commande.

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

À l’intérieur de la tâche, ces options sont accessibles via la syntaxe « echo » de Blade. Les instructions if et les boucles Blade sont également disponibles. Par exemple, pour vérifier l’existence de la variable $branch avant d’exécuter 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

Une story regroupe plusieurs tâches sous un nom pratique. Par exemple, une story deploy peut lancer à la suite les tâches update-code et 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

Une fois écrite, la story s’appelle comme n’importe quelle tâche.

php vendor/bin/envoy run deploy

Hooks d’exécution

Plusieurs hooks sont déclenchés lors de l’exécution d’une tâche ou d’une story. Envoy prend en charge @before, @after, @error, @success et @finished. Le code de ces hooks est interprété comme du PHP et s’exécute en local, pas sur les serveurs distants ciblés par la tâche. Vous pouvez définir autant de hooks que vous voulez ; ils s’exécutent dans l’ordre où ils apparaissent dans votre script Envoy.

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

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

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

@success
    // ...
@endsuccess

@finished
    if ($exitCode > 0) {
        // Une des tâches a échoué...
    }
@endfinished

Le hook @finished reçoit le code de sortie de la tâche terminée. Ce code peut être null ou un entier positif ou nul.

Exécuter les tâches

Pour exécuter une tâche ou une story définie dans Envoy.blade.php, lancez la commande run d’Envoy en lui passant le nom de la tâche ou de la story. Envoy exécute la tâche et affiche en direct la sortie des serveurs distants.

php vendor/bin/envoy run deploy

Confirmation avant exécution

Pour demander une confirmation avant d’exécuter une tâche donnée sur les serveurs, ajoutez la directive confirm à la déclaration de la tâche. C’est particulièrement utile pour les opérations destructrices.

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

Notifications

Slack

Envoy peut envoyer une notification vers Slack à la fin de chaque tâche. La directive @slack accepte une URL de webhook Slack ainsi qu’un nom de canal (ou d’utilisateur). L’URL de webhook s’obtient en créant une intégration « Incoming WebHooks » dans le panneau de contrôle Slack. Passez l’URL complète du webhook comme premier argument de @slack. Le deuxième argument est un nom de canal (#channel) ou d’utilisateur (@user).

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

Par défaut, un message décrivant la tâche exécutée est envoyé sur le canal. Vous pouvez le surcharger en passant un troisième argument à @slack.

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

Discord

Envoy peut également notifier Discord après chaque tâche. La directive @discord accepte l’URL de webhook Discord et un message. L’URL de webhook s’obtient en créant un « Webhook » dans les paramètres du serveur, en choisissant le canal cible.

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

Envoy peut aussi notifier Telegram après chaque tâche. La directive @telegram prend un Bot ID Telegram et un Chat ID. Le Bot ID s’obtient en créant un bot avec BotFather. Pour le Chat ID, vous pouvez utiliser @username_to_id_bot.

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

Microsoft Teams

Envoy peut également notifier Microsoft Teams après chaque tâche. La directive @teams prend un webhook Teams (obligatoire), un message, une couleur de thème (success, info, warning, error) et, en option, un tableau de configuration. Vous obtenez le webhook Teams en créant un Incoming Webhook. L’API Teams offre de nombreuses options pour composer vos propres cartes de message : consultez la documentation Microsoft Teams pour plus de détails.

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

Envoy s’appuie sur des connexions SSH vers les serveurs distants. Selon votre environnement, vous devrez configurer préalablement l’authentification par clé et le contrôle d’accès. Pour une automatisation de déploiement plus poussée, consultez également le guide Déploiement ou l’utilisation combinée avec GitHub Actions.

Architecture

Base de données

Eloquent

Sécurité

Événements

E-mails et notifications

Paiements

Traitement asynchrone

Communication temps réel

Planification

Cache et optimisation

Internationalisation

Fichiers et stockage

Débogage et supervision

Console et CLI

Performance

Frontend

Développement IA

Environnement de développement

Introduction

Installation

Création de tâches

Définir une tâche

Tâches locales

Importer un fichier Envoy

Plusieurs serveurs

Exécution en parallèle

Setup

Variables

Stories

Hooks d’exécution

Exécuter les tâches

Confirmation avant exécution

Notifications

Slack

Discord

Telegram

Microsoft Teams

​Introduction

​Installation

​Création de tâches

​Définir une tâche

​Tâches locales

​Importer un fichier Envoy

​Plusieurs serveurs

​Exécution en parallèle

​Setup

​Variables

​Stories

​Hooks d’exécution

​Exécuter les tâches

​Confirmation avant exécution

​Notifications

​Slack

​Discord

​Telegram

​Microsoft Teams

Introduction

Installation

Création de tâches

Définir une tâche

Tâches locales

Importer un fichier Envoy

Plusieurs serveurs

Exécution en parallèle

Setup

Variables

Stories

Hooks d’exécution

Exécuter les tâches

Confirmation avant exécution

Notifications

Slack

Discord

Telegram

Microsoft Teams