Envoy

• Introduzione
• Installazione
• Scrittura di Task
• Esecuzione dei Task
• Notifiche

Introduzione

Laravel Envoy è uno strumento per eseguire attività comuni sui tuoi server remoti. Usando la sintassi in stile Blade, puoi facilmente configurare attività per il deployment, comandi Artisan e altro ancora. Attualmente, Envoy supporta solo i sistemi operativi Mac e Linux. Tuttavia, il supporto per Windows è possibile utilizzando WSL2.

Installazione

Per prima cosa, installa Envoy nel tuo progetto usando il gestore di pacchetti Composer:

composer require laravel/envoy --dev

Una volta installato Envoy, il binario di Envoy sarà disponibile nella directory vendor/bin della tua applicazione:

php vendor/bin/envoy

Scrittura di Task

Definiamo i Task

I Task sono gli elementi base di Envoy. I Task definiscono i comandi shell che devono essere eseguiti sui tuoi server remoti quando il task viene invocato. Per esempio, potresti definire un task che esegue il comando php artisan queue:restart su tutti i server dei lavoratori della coda della tua applicazione.

Tutti i tuoi task di Envoy dovrebbero essere definiti in un file Envoy.blade.php nella radice della tua applicazione. Ecco un esempio per iniziare:

@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

Come puoi vedere, un array di @servers è definito all’inizio del file, permettendoti di riferire a questi server tramite l’opzione on nelle tue dichiarazioni di task. La dichiarazione @servers dovrebbe sempre essere posizionata su un’unica riga. All’interno delle tue dichiarazioni @task, dovresti inserire i comandi shell che devono essere eseguiti sui tuoi server quando il task viene invocato.

Task Locali

Puoi forzare l’esecuzione di uno script sul tuo computer locale specificando l’indirizzo IP del server come 127.0.0.1:

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

Importazione dei Task di Envoy

Con la direttiva @import, puoi importare altri file Envoy così che le loro storie e i loro task vengano aggiunti ai tuoi. Dopo aver importato i file, puoi eseguire i task che contengono come se fossero definiti nel tuo file Envoy:

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

Server Multipli

Envoy ti permette di eseguire facilmente un task su più server. Per prima cosa, aggiungi server aggiuntivi alla tua dichiarazione @servers. Ogni server deve avere un nome unico. Una volta definiti i server aggiuntivi, puoi elencarli nell’array on del task:

@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

Esecuzione in parallelo

Per impostazione predefinita, i task vengono eseguiti su ogni server in modo seriale. In altre parole, un task terminerà su un primo server prima di iniziare ad eseguirsi sul secondo server. Se desideri eseguire un task su più server in parallelo, aggiungi l’opzione parallel alla dichiarazione del task:

@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

Configurazione

A volte potresti aver bisogno di eseguire codice PHP arbitrario prima di avviare i tuoi task di Envoy. Puoi usare la direttiva @setup per definire un blocco di codice PHP che verrà eseguito prima dei tuoi task:

@setup
    $now = new DateTime;
@endsetup

Se hai bisogno di includere altri file PHP prima che il tuo task venga eseguito, puoi usare la direttiva @include all’inizio del tuo file Envoy.blade.php:

@include('vendor/autoload.php')

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

Variabili

Se necessario, puoi passare argomenti ai task di Envoy specificandoli nella riga di comando quando invoci Envoy:

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

Puoi accedere alle opzioni all’interno dei tuoi task usando la sintassi "echo" di Blade. Puoi anche definire istruzioni if e cicli di Blade all’interno dei tuoi task. Ad esempio, verifichiamo la presenza della variabile $branch prima di eseguire il 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

Stories

Le Stories raggruppano un insieme di task sotto un unico nome comodo. Ad esempio, una story deploy può eseguire i task update-code e install-dependencies elencando i nomi dei task nella sua definizione:

@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 volta scritta la story, puoi invocarla nello stesso modo in cui invochi un task:

php vendor/bin/envoy run deploy

Hooks

Quando le task e le storie vengono eseguite, vengono attivati diversi hook. I tipi di hook supportati da Envoy sono @before, @after, @error, @success e @finished. Tutto il codice in questi hook viene interpretato come PHP ed eseguito localmente, non sui server remoti con cui interagiscono le tue task.

Puoi definire quanti hook di ciascun tipo desideri. Verranno eseguiti nell’ordine in cui appaiono nel tuo script Envoy.

@before

Prima dell’esecuzione di ogni task, tutti i hook @before registrati nel tuo script Envoy verranno eseguiti. I hook @before ricevono il nome del task che sarà eseguito:

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

@after

Dopo l’esecuzione di ogni task, tutti i hook @after registrati nel tuo script Envoy verranno eseguiti. I hook @after ricevono il nome del task che è stato eseguito:

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

@error

Dopo ogni fallimento di un task (esce con un codice di stato maggiore di 0), tutti i hook @error registrati nel tuo script Envoy verranno eseguiti. I hook @error ricevono il nome del task che è stato eseguito:

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

@success

Se tutte le attività sono state eseguite senza errori, tutti i hook @success registrati nel tuo script Envoy verranno eseguiti:

@success
    // ...
@endsuccess

@finished

Dopo che tutte le attività sono state eseguite (indipendentemente dallo stato di uscita), tutti gli hook @finished verranno eseguiti. Gli hook @finished ricevono il codice di stato dell’attività completata, che può essere null o un integer maggiore o uguale a 0:

@finished
    if ($exitCode > 0) {
        // Ci sono stati errori in una delle attività...
    }
@endfinished

Esecuzione dei Task

Per eseguire un task o una storia definita nel file Envoy.blade.php della tua applicazione, esegui il comando run di Envoy, passando il nome del task o della storia che vuoi eseguire. Envoy eseguirà il task e mostrerà l’output dai tuoi server remoti mentre il task è in esecuzione:

php vendor/bin/envoy run deploy

Confermare l’Esecuzione del Task

Se desideri essere richiesto di confermare prima di eseguire un task sui tuoi server, dovresti aggiungere la direttiva confirm alla dichiarazione del tuo task. Questa opzione è particolarmente utile per operazioni distruttive:

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

Notifiche

Slack

Envoy supporta l’invio di notifiche a Slack dopo l’esecuzione di ogni task. La direttiva @slack accetta un URL di webhook di Slack e un canale o nome utente. Puoi ottenere il tuo webhook URL creando un’integrazione "Incoming WebHooks" nel pannello di controllo di Slack.

Devi passare l’intero webhook URL come primo argomento alla direttiva @slack. Il secondo argomento deve essere un nome di canale (#channel) o un nome utente (@user):

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

Di default, le notifiche di Envoy invieranno un messaggio al canale di notifica descrivendo il task eseguito. Tuttavia, puoi sovrascrivere questo messaggio con un messaggio personalizzato passando un terzo argomento alla direttiva @slack:

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

Discord

Envoy supporta anche l’invio di notifiche a Discord dopo l’esecuzione di ogni task. La direttiva @discord accetta un URL del webhook di Discord e un messaggio. Puoi ottenere l’URL del tuo webhook creando un "Webhook" nelle Impostazioni del Server e scegliendo il canale su cui il webhook deve postare. Devi inserire l’intero URL del webhook nella direttiva @discord:

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

Telegram

Envoy supporta l’invio di notifiche a Telegram dopo l’esecuzione di ogni task. La direttiva @telegram accetta un Bot ID di Telegram e un Chat ID. Puoi ottenere il tuo Bot ID creando un nuovo bot tramite BotFather. Puoi recuperare un Chat ID valido usando @username_to_id_bot. Devi inserire l’intero Bot ID e Chat ID nella direttiva @telegram:

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

Microsoft Teams

Envoy supporta anche l’invio di notifiche a Microsoft Teams dopo l’esecuzione di ogni task. La direttiva @microsoftTeams accetta un Webhook di Teams (obbligatorio), un messaggio, un colore del tema (success, info, warning, error) e un array di opzioni. Puoi ottenere il tuo Webhook di Teams creando un nuovo incoming webhook. L’API di Teams offre molti altri attributi per personalizzare la casella del messaggio come titolo, sommario e sezioni. Puoi trovare maggiori informazioni nella documentazione di Microsoft Teams. Dovresti passare l’intero URL del Webhook nella direttiva @microsoftTeams:

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