Envoy

Einführung

Laravel Envoy ist ein Tool zum Ausführen häufig benötigter Aufgaben auf entfernten Servern. Mit derselben Syntax wie Blade können Sie Deployment-Aufgaben, Artisan-Befehle und andere Tasks einfach definieren.

Envoy unterstützt derzeit nur macOS und Linux. Unter Windows ist die Nutzung über WSL2 erforderlich.

Installation

Installieren Sie Envoy mithilfe des Composer-Paketmanagers in Ihrem Projekt.

composer require laravel/envoy --dev

Nach der Installation steht die Envoy-Ausführungsdatei im Verzeichnis vendor/bin zur Verfügung.

php vendor/bin/envoy

Tasks erstellen

Tasks definieren

Tasks sind die grundlegenden Bausteine von Envoy. Ein Task definiert die Shell-Befehle, die bei seiner Ausführung auf dem entfernten Server ausgeführt werden. Sie könnten beispielsweise einen Task definieren, der php artisan queue:restart auf allen Queue-Worker-Servern ausführt. Alle Envoy-Tasks werden in der Datei Envoy.blade.php im Stammverzeichnis Ihrer Anwendung definiert.

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

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

Wie oben zu sehen, wird zu Beginn der Datei ein @servers-Array definiert. In der on-Option jeder Task-Deklaration wird auf diese Server verwiesen. Die @servers-Deklaration muss in einer einzigen Zeile geschrieben werden. Innerhalb der @task-Deklaration werden die Shell-Befehle notiert, die bei der Ausführung auf dem Server ablaufen sollen.

Lokale Tasks

Indem Sie die IP-Adresse des Servers auf 127.0.0.1 setzen, können Sie ein Skript zwingen, auf Ihrem lokalen Rechner ausgeführt zu werden.

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

Envoy-Tasks importieren

Mit der @import-Direktive können Sie andere Envoy-Dateien importieren und deren Stories und Tasks zu Ihrer eigenen Datei hinzufügen. Nach dem Import können Sie die Tasks so ausführen, als wären sie in Ihrer eigenen Envoy-Datei definiert.

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

Mehrere Server

Envoy erlaubt es, einen einzelnen Task problemlos auf mehreren Servern auszuführen. Registrieren Sie dazu zunächst weitere Server in der @servers-Deklaration und geben Sie jedem einen eindeutigen Namen. Sobald die Server hinzugefügt sind, listen Sie sie im on-Array des Tasks auf.

@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

Parallele Ausführung

Standardmäßig werden Tasks auf den einzelnen Servern seriell ausgeführt. Das heißt, ein Task wird zuerst auf dem ersten Server abgeschlossen, bevor die Ausführung auf dem zweiten Server beginnt. Wenn Sie einen Task parallel auf mehreren Servern ausführen möchten, fügen Sie der Task-Deklaration die Option parallel hinzu.

@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

Wenn Sie vor der Ausführung von Envoy-Tasks beliebigen PHP-Code ausführen müssen, verwenden Sie die @setup-Direktive.

@setup
    $now = new DateTime;
@endsetup

Falls Sie vor der Task-Ausführung weitere PHP-Dateien laden müssen, verwenden Sie am Anfang der Datei Envoy.blade.php die @include-Direktive.

@include('vendor/autoload.php')

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

Variablen

Beim Aufruf eines Envoy-Tasks können Sie Argumente auf der Kommandozeile angeben, die an den Task übergeben werden.

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

Innerhalb eines Tasks greifen Sie mit der Blade-„echo”-Syntax auf die Optionen zu. Auch Blade-if-Anweisungen und -Schleifen können definiert werden. Um beispielsweise vor dem Ausführen von git pull das Vorhandensein der Variablen $branch zu prüfen:

@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 gruppieren eine Reihe von Tasks unter einem einzigen praktischen Namen. Zum Beispiel kann eine deploy-Story die Tasks update-code und install-dependencies gemeinsam ausführen.

@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

Sobald die Story geschrieben ist, können Sie sie auf die gleiche Weise wie Tasks aufrufen.

php vendor/bin/envoy run deploy

Completion-Hooks

Bei der Ausführung von Tasks und Stories werden verschiedene Hooks ausgeführt. Envoy unterstützt die Hook-Typen @before, @after, @error, @success und @finished. Der gesamte Code innerhalb dieser Hooks wird als PHP interpretiert und lokal ausgeführt – nicht auf den entfernten Servern, mit denen der Task interagiert. Sie können beliebig viele Hooks jedes Typs definieren; sie werden in der Reihenfolge ausgeführt, in der sie im Envoy-Skript notiert sind.

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

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

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

@success
    // ...
@endsuccess

@finished
    if ($exitCode > 0) {
        // Bei irgendeinem der Tasks trat ein Fehler auf...
    }
@endfinished

Der @finished-Hook erhält den Statuscode des abgeschlossenen Tasks. Der Statuscode ist entweder null oder eine Ganzzahl größer oder gleich 0.

Tasks ausführen

Um in Ihrer Anwendungsdatei Envoy.blade.php definierte Tasks oder Stories auszuführen, verwenden Sie den Envoy-Befehl run und übergeben Sie den Namen des gewünschten Tasks oder der Story. Envoy führt den Task aus und zeigt während der Ausführung die Ausgabe der entfernten Server an.

php vendor/bin/envoy run deploy

Task-Ausführung bestätigen

Wenn Sie vor der Ausführung eines bestimmten Tasks auf dem Server eine Bestätigung anfordern möchten, fügen Sie der Task-Deklaration die Direktive confirm hinzu. Dies ist besonders nützlich bei destruktiven Operationen.

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

Benachrichtigungen

Slack

Envoy kann nach jeder Task-Ausführung Benachrichtigungen an Slack senden. Die @slack-Direktive erwartet eine Slack-Webhook-URL und einen Channel-Namen (oder Benutzernamen). Die Webhook-URL erhalten Sie durch das Anlegen einer „Incoming WebHooks”-Integration in der Slack-Steuerkonsole. Als erstes Argument übergeben Sie der @slack-Direktive die vollständige Webhook-URL. Als zweites Argument geben Sie den Channel-Namen (#channel) oder Benutzernamen (@user) an.

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

Standardmäßig wird eine Nachricht, die die ausgeführten Tasks beschreibt, in den Benachrichtigungs-Channel gesendet. Übergeben Sie der @slack-Direktive ein drittes Argument, um sie durch eine eigene Nachricht zu überschreiben.

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

Discord

Envoy unterstützt auch das Senden von Benachrichtigungen an Discord nach jeder Task-Ausführung. Die @discord-Direktive erwartet eine Discord-Webhook-URL und eine Nachricht. Die Webhook-URL erhalten Sie, indem Sie in den Servereinstellungen einen „Webhook” anlegen und den Ziel-Channel auswählen.

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

Envoy unterstützt auch das Senden von Benachrichtigungen an Telegram nach jeder Task-Ausführung. Die @telegram-Direktive erwartet eine Telegram-Bot-ID und eine Chat-ID. Die Bot-ID erhalten Sie, indem Sie über den BotFather einen neuen Bot anlegen. Die Chat-ID lässt sich mit @username_to_id_bot ermitteln.

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

Microsoft Teams

Envoy unterstützt auch das Senden von Benachrichtigungen an Microsoft Teams nach jeder Task-Ausführung. Die @teams-Direktive erwartet einen Teams-Webhook (erforderlich), eine Nachricht, eine Themenfarbe (success, info, warning, error) sowie ein optionales Options-Array. Den Teams-Webhook erhalten Sie durch das Anlegen eines Incoming Webhook. Die Teams-API bietet viele weitere Einstellungen, mit denen Sie eigene Nachrichten-Cards frei gestalten können. Details finden Sie in der Microsoft Teams-Dokumentation.

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

Envoy setzt eine SSH-Verbindung zu den entfernten Servern voraus. Je nach Umgebung müssen Schlüssel-Authentifizierung und Zugriffskontrolle vorab eingerichtet werden. Für fortgeschrittenere Deployment-Automatisierung sollten Sie auch die Deployment-Anleitung sowie die Kombination mit GitHub Actions in Betracht ziehen.

Architektur

Datenbank

Eloquent

Sicherheit

Ereignisse

E-Mail und Benachrichtigungen

Zahlungen

Asynchrone Verarbeitung

Echtzeitkommunikation

Zeitplanung

Caching und Optimierung

Internationalisierung

Dateien und Speicher

Debugging und Monitoring

Konsole und CLI

Performance

Frontend

KI-Entwicklung

Entwicklungsumgebung

Einführung

Installation

Tasks erstellen

Tasks definieren

Lokale Tasks

Envoy-Tasks importieren

Mehrere Server

Parallele Ausführung

Setup

Variablen

Stories

Completion-Hooks

Tasks ausführen

Task-Ausführung bestätigen

Benachrichtigungen

Slack

Discord

Telegram

Microsoft Teams

​Einführung

​Installation

​Tasks erstellen

​Tasks definieren

​Lokale Tasks

​Envoy-Tasks importieren

​Mehrere Server

​Parallele Ausführung

​Setup

​Variablen

​Stories

​Completion-Hooks

​Tasks ausführen

​Task-Ausführung bestätigen

​Benachrichtigungen

​Slack

​Discord

​Telegram

​Microsoft Teams

Einführung

Installation

Tasks erstellen

Tasks definieren

Lokale Tasks

Envoy-Tasks importieren

Mehrere Server

Parallele Ausführung

Setup

Variablen

Stories

Completion-Hooks

Tasks ausführen

Task-Ausführung bestätigen

Benachrichtigungen

Slack

Discord

Telegram

Microsoft Teams