Envoy

Aan de slag

Laravel Envoy is een tool om veelgebruikte taken op remote servers uit te voeren. Met dezelfde syntaxis als Blade kun je eenvoudig taken definiëren zoals deploys en het uitvoeren van Artisan-commando’s.

Envoy ondersteunt momenteel alleen macOS en Linux. Wil je het op Windows gebruiken, dan moet dat via WSL2.

Installatie

Installeer Envoy in je project met de Composer-pakketmanager.

composer require laravel/envoy --dev

Na de installatie is het uitvoerbare bestand van Envoy beschikbaar in de map vendor/bin.

php vendor/bin/envoy

Taken schrijven

Taken definiëren

Taken zijn de fundamentele bouwsteen van Envoy. Een taak definieert de shellcommando’s die op de remote server moeten worden uitgevoerd wanneer de taak wordt uitgevoerd. Je kunt bijvoorbeeld een taak definiëren die het commando php artisan queue:restart op alle queue-workerservers uitvoert. Alle Envoy-taken definieer je in het bestand Envoy.blade.php in de root van je applicatie.

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

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

Zoals hierboven te zien is, definieer je bovenaan het bestand een @servers-array en verwijs je met de on-optie van elke taakdeclaratie naar deze servers. Schrijf de @servers-declaratie altijd op één regel. Binnen een @task-declaratie schrijf je de shellcommando’s die bij het uitvoeren van de taak op de server worden uitgevoerd.

Lokale taken

Door het IP-adres van de server op te geven als 127.0.0.1, kun je een script geforceerd op je lokale computer laten draaien.

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

Envoy-taken importeren

Met de @import-directive kun je andere Envoy-bestanden importeren en hun stories en taken aan je eigen bestand toevoegen. Na het importeren kun je die taken uitvoeren alsof je ze in je eigen Envoy-bestand hebt gedefinieerd.

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

Meerdere servers

Met Envoy kun je één taak gemakkelijk op meerdere servers uitvoeren. Registreer eerst extra servers in de @servers-declaratie en geef elke server een unieke naam. Zodra je servers hebt toegevoegd, som je ze op in de on-array van de taak.

@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

Parallelle uitvoering

Standaard wordt een taak serieel op elke server uitgevoerd. Dat wil zeggen: pas nadat een taak op de eerste server is voltooid, gaat de uitvoering verder op de tweede server. Wil je een taak parallel op meerdere servers uitvoeren, voeg dan de optie parallel toe aan de taakdeclaratie.

@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

Moet je willekeurige PHP-code uitvoeren voordat een Envoy-taak wordt uitgevoerd, gebruik dan de @setup-directive.

@setup
    $now = new DateTime;
@endsetup

Moet je vóór de taakuitvoering andere PHP-bestanden inladen, gebruik dan de @include-directive bovenaan je Envoy.blade.php-bestand.

@include('vendor/autoload.php')

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

Variabelen

Bij het aanroepen van een Envoy-taak kun je argumenten opgeven op de commandoregel en aan de taak doorgeven.

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

Binnen een taak heb je via de “echo”-syntaxis van Blade toegang tot de opties. Je kunt ook Blade-if-statements en lussen definiëren. Wil je bijvoorbeeld het bestaan van de variabele $branch controleren voordat je het git pull-commando uitvoert, dan doe je dat zo:

@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

Stories groeperen een reeks taken onder één handige naam. Zo kun je bijvoorbeeld met een deploy-story de taken update-code en install-dependencies gebundeld uitvoeren.

@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

Zodra je de story hebt geschreven, roep je die op dezelfde manier aan als een taak.

php vendor/bin/envoy run deploy

Voltooiingshooks

Bij het uitvoeren van taken en stories worden meerdere hooks uitgevoerd. De hooktypen die Envoy ondersteunt zijn @before, @after, @error, @success en @finished. Alle code binnen deze hooks wordt geïnterpreteerd als PHP en lokaal uitgevoerd, niet op de remote servers waar je taken op werken. Je kunt van elke hook zoveel definiëren als je wilt; ze worden uitgevoerd in de volgorde waarin ze in je Envoy-script staan.

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

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

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

@success
    // ...
@endsuccess

@finished
    if ($exitCode > 0) {
        // Er is in een van de taken een fout opgetreden...
    }
@endfinished

De @finished-hook ontvangt de statuscode van de voltooide taak. De statuscode is null of een geheel getal van 0 of hoger.

Taken uitvoeren

Om taken of stories uit te voeren die je in het Envoy.blade.php-bestand van je applicatie hebt gedefinieerd, voer je het run-commando van Envoy uit met de naam van de taak of story die je wilt uitvoeren. Envoy voert de taak uit en toont tijdens de uitvoering de uitvoer van de remote servers.

php vendor/bin/envoy run deploy

Bevestiging van taakuitvoering

Wil je om bevestiging vragen voordat een bepaalde taak op je servers wordt uitgevoerd, voeg dan de confirm-directive toe aan de taakdeclaratie. Deze functie is vooral handig bij destructieve operaties.

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

Notificaties

Slack

Envoy kan na elke taakuitvoering een notificatie naar Slack sturen. De @slack-directive ontvangt een Slack-webhook-URL en een kanaalnaam (of gebruikersnaam). De webhook-URL verkrijg je door in het Slack-configuratiescherm een “Incoming WebHooks”-integratie aan te maken. Als eerste argument van de @slack-directive geef je de volledige webhook-URL door. Als tweede argument geef je een kanaalnaam (#channel) of gebruikersnaam (@user) op.

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

Standaard wordt een bericht dat de uitgevoerde taak beschrijft naar het notificatiekanaal gestuurd. Door een derde argument aan de @slack-directive door te geven, kun je dit overschrijven met je eigen bericht.

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

Discord

Envoy ondersteunt ook het sturen van notificaties naar Discord na elke taakuitvoering. De @discord-directive ontvangt een Discord-webhook-URL en een bericht. De webhook-URL verkrijg je door in de serverinstellingen een “Webhook” aan te maken en het kanaal te kiezen waarin gepost moet worden.

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

Envoy ondersteunt ook het sturen van notificaties naar Telegram na elke taakuitvoering. De @telegram-directive ontvangt een Telegram-bot-ID en een chat-ID. De bot-ID verkrijg je door een nieuwe bot aan te maken via BotFather. De chat-ID kun je verkrijgen met @username_to_id_bot.

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

Microsoft Teams

Envoy ondersteunt ook het sturen van notificaties naar Microsoft Teams na elke taakuitvoering. De @teams-directive ontvangt een Teams-webhook (vereist), een bericht, een themakleur (success, info, warning, error) en een optionele configuratie-array. De Teams-webhook verkrijg je door een Incoming Webhook aan te maken. De Teams-API heeft nog veel meer configuratieopties waarmee je vrij je eigen berichtkaarten kunt samenstellen. Zie de Microsoft Teams-documentatie voor details.

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

Envoy gaat uit van een SSH-verbinding naar de remote server. Afhankelijk van je omgeving moet je vooraf sleutelauthenticatie configureren en de toegangscontrole tot je servers regelen. Heb je geavanceerdere deploy-automatisering nodig, overweeg dan ook de deployment-gids of een combinatie met GitHub Actions.

Architectuur

Database

Eloquent

Beveiliging

Events

E-mail en notificaties

Betalingen

Asynchrone verwerking

Realtime communicatie

Taakplanning

Caching en optimalisatie

Internationalisatie

Bestanden en opslag

Debugging en monitoring

Console en CLI

Performance

Frontend

AI-ontwikkeling

Ontwikkelomgeving

Aan de slag

Installatie

Taken schrijven

Taken definiëren

Lokale taken

Envoy-taken importeren

Meerdere servers

Parallelle uitvoering

Setup

Variabelen

Stories

Voltooiingshooks

Taken uitvoeren

Bevestiging van taakuitvoering

Notificaties

Slack

Discord

Telegram

Microsoft Teams

​Aan de slag

​Installatie

​Taken schrijven

​Taken definiëren

​Lokale taken

​Envoy-taken importeren

​Meerdere servers

​Parallelle uitvoering

​Setup

​Variabelen

​Stories

​Voltooiingshooks

​Taken uitvoeren

​Bevestiging van taakuitvoering

​Notificaties

​Slack

​Discord

​Telegram

​Microsoft Teams

Aan de slag

Installatie

Taken schrijven

Taken definiëren

Lokale taken

Envoy-taken importeren

Meerdere servers

Parallelle uitvoering

Setup

Variabelen

Stories

Voltooiingshooks

Taken uitvoeren

Bevestiging van taakuitvoering

Notificaties

Slack

Discord

Telegram

Microsoft Teams