Envoy

Introduzione

Laravel Envoy è uno strumento per eseguire task comuni su server remoti. Con la stessa sintassi di Blade, definisci facilmente task come deploy o esecuzione di comandi Artisan.

Al momento Envoy supporta solo macOS e Linux. Su Windows va usato tramite WSL2.

Installazione

Installa Envoy nel progetto tramite Composer.

composer require laravel/envoy --dev

Dopo l’installazione, l’eseguibile di Envoy è disponibile in vendor/bin.

php vendor/bin/envoy

Creare task

Definire un task

I task sono il mattone di base di Envoy. Un task definisce i comandi shell da eseguire sul server remoto quando lo si esegue. Ad esempio puoi definire un task che esegue php artisan queue:restart su tutti i server dei worker della coda. Tutti i task di Envoy si definiscono nel file Envoy.blade.php nella root dell’applicazione.

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

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

Come mostrato, definisci l’array @servers all’inizio del file e nei task fai riferimento a questi server tramite l’opzione on. La dichiarazione @servers va scritta obbligatoriamente su una sola riga. Dentro @task scrivi i comandi shell da eseguire sul server quando il task viene lanciato.

Task locali

Specificando come indirizzo IP 127.0.0.1 puoi forzare l’esecuzione dello script sul computer locale.

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

Importare task Envoy

Con la direttiva @import puoi importare altri file Envoy e aggiungere le loro story e i loro task al tuo file. Dopo l’import puoi eseguire i task come se fossero definiti nel tuo Envoy file.

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

Più server

Con Envoy puoi eseguire facilmente un task su più server. Aggiungi i server nella dichiarazione @servers assegnando un nome univoco a ciascuno, poi elencali 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 default il task viene eseguito in serie: dopo che è terminato sul primo server passa al secondo. Per eseguire il task in parallelo su più server, 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

Setup

Se devi eseguire del codice PHP prima di lanciare i task Envoy, usa la direttiva @setup.

@setup
    $now = new DateTime;
@endsetup

Se devi caricare altri file PHP prima dell’esecuzione dei task, usa la direttiva @include all’inizio di Envoy.blade.php.

@include('vendor/autoload.php')

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

Variabili

Quando esegui un task Envoy puoi passare argomenti da riga di comando.

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

All’interno del task, con la sintassi “echo” di Blade accedi alle opzioni. Puoi usare anche if e cicli di Blade. Ad esempio, per verificare che la variabile $branch esista prima di eseguire 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

Story

Una story raggruppa una sequenza di task sotto un unico nome comodo. Ad esempio la story deploy esegue insieme i task update-code e 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

Una story si esegue come un normale task.

php vendor/bin/envoy run deploy

Hook di completamento

Durante l’esecuzione di task e story vengono lanciati diversi hook. Envoy supporta @before, @after, @error, @success e @finished. Il codice dentro questi hook è interpretato come PHP e viene eseguito in locale, non sui server remoti su cui opera il task. Puoi definire tutti gli hook che vuoi; vengono eseguiti nell’ordine in cui compaiono nello script Envoy.

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

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

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

@success
    // ...
@endsuccess

@finished
    if ($exitCode > 0) {
        // uno dei task ha avuto un errore...
    }
@endfinished

L’hook @finished riceve lo status code del task completato. Lo status code è null oppure un intero >= 0.

Eseguire i task

Per eseguire un task o una story definiti in Envoy.blade.php, esegui il comando run di Envoy passandone il nome. Envoy esegue il task e mostra in tempo reale l’output dai server remoti.

php vendor/bin/envoy run deploy

Conferma dell’esecuzione

Se vuoi chiedere conferma prima di eseguire un task, aggiungi la direttiva confirm alla dichiarazione. È utile soprattutto 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 può inviare una notifica a Slack dopo ogni esecuzione. La direttiva @slack accetta l’URL del webhook Slack e il nome del canale (o utente). L’URL del webhook si ottiene creando un’integrazione “Incoming WebHooks” dal pannello di Slack. Come primo argomento passi l’intero URL del webhook; come secondo, un canale (#channel) o un utente (@user).

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

Di default viene inviato un messaggio che descrive il task eseguito. Passando un terzo argomento a @slack puoi sovrascriverlo con un messaggio personalizzato.

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

Discord

Envoy supporta anche l’invio di notifiche a Discord dopo ogni esecuzione. La direttiva @discord accetta URL del webhook Discord e messaggio. Il webhook si crea nelle impostazioni del server scegliendo “Webhook” e il canale di destinazione.

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

Envoy supporta anche notifiche a Telegram dopo ogni esecuzione. La direttiva @telegram accetta Bot ID e Chat ID Telegram. Il Bot ID si ottiene creando un nuovo bot con BotFather; il Chat ID si ricava con @username_to_id_bot.

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

Microsoft Teams

Envoy supporta anche notifiche a Microsoft Teams dopo ogni esecuzione. La direttiva @teams accetta il webhook Teams (obbligatorio), un messaggio, il colore del tema (success, info, warning, error) e un array di configurazione opzionale. Il webhook Teams si ottiene creando un Incoming Webhook. L’API Teams ha molte altre opzioni con cui puoi comporre le tue message card. Per i dettagli consulta la documentazione di Microsoft Teams.

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

Envoy presuppone una connessione SSH ai server remoti. In base all’ambiente devi predisporre autenticazione a chiave e controlli di accesso. Per un’automazione di deploy più avanzata, valuta anche la guida Deployment o l’integrazione con GitHub Actions.

Architettura

Database

Eloquent

Sicurezza

Eventi

Mail e notifiche

Pagamenti

Elaborazione asincrona

Comunicazione in tempo reale

Scheduling

Cache e ottimizzazione

Internazionalizzazione

File e storage

Debug e monitoraggio

Console e CLI

Performance

Frontend

Sviluppo con AI

Ambiente di sviluppo

Introduzione

Installazione

Creare task

Definire un task

Task locali

Importare task Envoy

Più server

Esecuzione in parallelo

Setup

Variabili

Story

Hook di completamento

Eseguire i task

Conferma dell’esecuzione

Notifiche

Slack

Discord

Telegram

Microsoft Teams

​Introduzione

​Installazione

​Creare task

​Definire un task

​Task locali

​Importare task Envoy

​Più server

​Esecuzione in parallelo

​Setup

​Variabili

​Story

​Hook di completamento

​Eseguire i task

​Conferma dell’esecuzione

​Notifiche

​Slack

​Discord

​Telegram

​Microsoft Teams

Introduzione

Installazione

Creare task

Definire un task

Task locali

Importare task Envoy

Più server

Esecuzione in parallelo

Setup

Variabili

Story

Hook di completamento

Eseguire i task

Conferma dell’esecuzione

Notifiche

Slack

Discord

Telegram

Microsoft Teams