> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Envoy

> Erfahren Sie, wie Sie mit Laravel Envoy Deployment-Tasks und Artisan-Befehle auf entfernten Servern mithilfe der Blade-Syntax definieren und ausführen.

## Einführung

[Laravel Envoy](https://github.com/laravel/envoy) ist ein Tool zum Ausführen häufig benötigter Aufgaben auf entfernten Servern. Mit derselben Syntax wie [Blade](/de/blade) können Sie Deployment-Aufgaben, Artisan-Befehle und andere Tasks einfach definieren.

<Info>
  Envoy unterstützt derzeit nur macOS und Linux. Unter Windows ist die Nutzung über [WSL2](https://docs.microsoft.com/de-de/windows/wsl/install-win10) erforderlich.
</Info>

## Installation

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

```shell theme={null}
composer require laravel/envoy --dev
```

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

```shell theme={null}
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.

```blade theme={null}
@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
```

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.

```blade theme={null}
@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.

```blade theme={null}
@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.

```blade theme={null}
@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.

```blade theme={null}
@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.

```php theme={null}
@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.

```blade theme={null}
@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.

```shell theme={null}
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:

```blade theme={null}
@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

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.

```blade theme={null}
@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
```

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

```shell theme={null}
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.

```blade theme={null}
@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.

```shell theme={null}
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.

```blade theme={null}
@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](https://slack.com) 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.

```blade theme={null}
@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.

```blade theme={null}
@finished
    @slack('webhook-url', '#bots', 'Hello, Slack.')
@endfinished
```

### Discord

Envoy unterstützt auch das Senden von Benachrichtigungen an [Discord](https://discord.com) 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.

```blade theme={null}
@finished
    @discord('discord-webhook-url')
@endfinished
```

### Telegram

Envoy unterstützt auch das Senden von Benachrichtigungen an [Telegram](https://telegram.org) 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](https://t.me/botfather) einen neuen Bot anlegen. Die Chat-ID lässt sich mit [@username\_to\_id\_bot](https://t.me/username_to_id_bot) ermitteln.

```blade theme={null}
@finished
    @telegram('bot-id','chat-id')
@endfinished
```

### Microsoft Teams

Envoy unterstützt auch das Senden von Benachrichtigungen an [Microsoft Teams](https://www.microsoft.com/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](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-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](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using).

```blade theme={null}
@finished
    @teams('webhook-url')
@endfinished
```

<Warning>
  Envoy setzt eine [SSH](https://de.wikipedia.org/wiki/Secure_Shell)-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](/de/deployment)-Anleitung sowie die Kombination mit [GitHub Actions](/de/advanced/github-actions-pinning) in Betracht ziehen.
</Warning>