Laravel Envoy jest narzędziem do wykonywania typowych zadań, które uruchamiasz na swoich zdalnych serwerach. Używając składni w stylu Blade, możesz łatwo skonfigurować zadania do wdrażania, poleceń Artisan i więcej. Obecnie Envoy obsługuje tylko systemy operacyjne Mac i Linux. Jednak obsługa Windows jest możliwa przy użyciu WSL2.
Najpierw zainstaluj Envoy w swoim projekcie używając menedżera pakietów Composer:
composer require laravel/envoy --devPo zainstalowaniu Envoy, plik binarny Envoy będzie dostępny w katalogu vendor/bin Twojej aplikacji:
php vendor/bin/envoyZadania są podstawowym elementem składowym Envoy. Zadania definiują polecenia powłoki, które powinny zostać wykonane na Twoich zdalnych serwerach, gdy zadanie jest wywoływane. Na przykład, możesz zdefiniować zadanie, które wykonuje polecenie php artisan queue:restart na wszystkich serwerach procesów kolejki Twojej aplikacji.
Wszystkie Twoje zadania Envoy powinny być zdefiniowane w pliku Envoy.blade.php w katalogu głównym Twojej aplikacji. Oto przykład dla Ciebie na początek:
@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
@endtaskJak widać, tablica @servers jest zdefiniowana na górze pliku, umożliwiając Ci odniesienie się do tych serwerów za pomocą opcji on w deklaracjach zadań. Deklaracja @servers powinna zawsze być umieszczona w jednej linii. Wewnątrz deklaracji @task powinieneś umieścić polecenia powłoki, które powinny zostać wykonane na Twoich serwerach, gdy zadanie jest wywoływane.
Możesz wymusić uruchomienie skryptu na swoim lokalnym komputerze, określając adres IP serwera jako 127.0.0.1:
@servers(['localhost' => '127.0.0.1'])Używając dyrektywy @import, możesz zaimportować inne pliki Envoy, tak aby ich historie i zadania zostały dodane do Twoich. Po zaimportowaniu plików możesz wykonywać zawarte w nich zadania tak, jakby były zdefiniowane w Twoim własnym pliku Envoy:
@import('vendor/package/Envoy.blade.php')Envoy pozwala łatwo uruchomić zadanie na wielu serwerach. Najpierw dodaj dodatkowe serwery do swojej deklaracji @servers. Każdemu serwerowi powinna być przypisana unikalna nazwa. Po zdefiniowaniu dodatkowych serwerów możesz wymienić każdy z serwerów w tablicy on zadania:
@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
@endtaskDomyślnie zadania będą wykonywane na każdym serwerze szeregowo. Innymi słowy, zadanie zakończy działanie na pierwszym serwerze przed przejściem do wykonania na drugim serwerze. Jeśli chcesz uruchomić zadanie na wielu serwerach równolegle, dodaj opcję parallel do deklaracji zadania:
@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
@endtaskCzasami możesz potrzebować wykonać dowolny kod PHP przed uruchomieniem swoich zadań Envoy. Możesz użyć dyrektywy @setup, aby zdefiniować blok kodu PHP, który powinien zostać wykonany przed Twoimi zadaniami:
@setup
$now = new DateTime;
@endsetupJeśli potrzebujesz dołączyć inne pliki PHP przed wykonaniem zadania, możesz użyć dyrektywy @include na górze swojego pliku Envoy.blade.php:
@include('vendor/autoload.php')
@task('restart-queues')
# ...
@endtaskJeśli to konieczne, możesz przekazywać argumenty do zadań Envoy, określając je w wierszu poleceń podczas wywoływania Envoy:
php vendor/bin/envoy run deploy --branch=masterMożesz uzyskać dostęp do opcji w swoich zadaniach używając składni "echo" Blade. Możesz również definiować instrukcje if Blade i pętle wewnątrz swoich zadań. Na przykład, zweryfikujmy obecność zmiennej $branch przed wykonaniem polecenia 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
@endtaskHistorie grupują zestaw zadań pod jedną, wygodną nazwą. Na przykład historia deploy może uruchamiać zadania update-code i install-dependencies, wymieniając nazwy zadań w swojej definicji:
@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
@endtaskPo napisaniu historii możesz ją wywołać w taki sam sposób, jak wywołałbyś zadanie:
php vendor/bin/envoy run deployGdy zadania i historie są uruchamiane, wykonywanych jest wiele hooków. Typy hooków obsługiwane przez Envoy to @before, @after, @error, @success i @finished. Cały kod w tych hookach jest interpretowany jako PHP i wykonywany lokalnie, a nie na zdalnych serwerach, z którymi wchodzą w interakcję Twoje zadania.
Możesz zdefiniować tyle każdego z tych hooków, ile chcesz. Będą one wykonywane w kolejności, w jakiej pojawiają się w Twoim skrypcie Envoy.
Przed każdym wykonaniem zadania, wszystkie hooki @before zarejestrowane w Twoim skrypcie Envoy zostaną wykonane. Hooki @before otrzymują nazwę zadania, które zostanie wykonane:
@before
if ($task === 'deploy') {
// ...
}
@endbeforePo każdym wykonaniu zadania, wszystkie hooki @after zarejestrowane w Twoim skrypcie Envoy zostaną wykonane. Hooki @after otrzymują nazwę zadania, które zostało wykonane:
@after
if ($task === 'deploy') {
// ...
}
@endafterPo każdym niepowodzeniu zadania (kończy się z kodem statusu większym niż 0), wszystkie hooki @error zarejestrowane w Twoim skrypcie Envoy zostaną wykonane. Hooki @error otrzymują nazwę zadania, które zostało wykonane:
@error
if ($task === 'deploy') {
// ...
}
@enderrorJeśli wszystkie zadania zostały wykonane bez błędów, wszystkie hooki @success zarejestrowane w Twoim skrypcie Envoy zostaną wykonane:
@success
// ...
@endsuccessPo wykonaniu wszystkich zadań (niezależnie od statusu wyjścia), wszystkie hooki @finished zostaną wykonane. Hooki @finished otrzymują kod statusu ukończonego zadania, który może być null lub integer większym lub równym 0:
@finished
if ($exitCode > 0) {
// Wystąpiły błędy w jednym z zadań...
}
@endfinishedAby uruchomić zadanie lub historię zdefiniowaną w pliku Envoy.blade.php Twojej aplikacji, wykonaj polecenie run Envoy, przekazując nazwę zadania lub historii, którą chcesz wykonać. Envoy wykona zadanie i wyświetli wyjście z Twoich zdalnych serwerów w trakcie działania zadania:
php vendor/bin/envoy run deployJeśli chcesz zostać poproszony o potwierdzenie przed uruchomieniem danego zadania na Twoich serwerach, powinieneś dodać dyrektywę confirm do deklaracji zadania. Ta opcja jest szczególnie przydatna dla operacji destrukcyjnych:
@task('deploy', ['on' => 'web', 'confirm' => true])
cd /home/user/example.com
git pull origin {{ $branch }}
php artisan migrate
@endtaskEnvoy obsługuje wysyłanie powiadomień do Slack po wykonaniu każdego zadania. Dyrektywa @slack przyjmuje URL hooka Slack i nazwę kanału / użytkownika. Możesz pobrać swój URL webhooka tworząc integrację "Incoming WebHooks" w swoim panelu sterowania Slack.
Powinieneś przekazać cały URL webhooka jako pierwszy argument podany do dyrektywy @slack. Drugi argument podany do dyrektywy @slack powinien być nazwą kanału (#channel) lub nazwą użytkownika (@user):
@finished
@slack('webhook-url', '#bots')
@endfinishedDomyślnie powiadomienia Envoy będą wysyłać wiadomość do kanału powiadomień opisującą zadanie, które zostało wykonane. Jednak możesz nadpisać tę wiadomość własną niestandardową wiadomością, przekazując trzeci argument do dyrektywy @slack:
@finished
@slack('webhook-url', '#bots', 'Hello, Slack.')
@endfinishedEnvoy obsługuje również wysyłanie powiadomień do Discord po wykonaniu każdego zadania. Dyrektywa @discord przyjmuje URL hooka Discord i wiadomość. Możesz pobrać swój URL webhooka tworząc "Webhook" w ustawieniach serwera i wybierając kanał, na który webhook powinien publikować. Powinieneś przekazać cały URL webhooka do dyrektywy @discord:
@finished
@discord('discord-webhook-url')
@endfinishedEnvoy obsługuje również wysyłanie powiadomień do Telegram po wykonaniu każdego zadania. Dyrektywa @telegram przyjmuje ID bota Telegram i ID czatu. Możesz pobrać swój ID bota tworząc nowego bota za pomocą BotFather. Możesz pobrać prawidłowy ID czatu używając @username_to_id_bot. Powinieneś przekazać cały ID bota i ID czatu do dyrektywy @telegram:
@finished
@telegram('bot-id','chat-id')
@endfinishedEnvoy obsługuje również wysyłanie powiadomień do Microsoft Teams po wykonaniu każdego zadania. Dyrektywa @microsoftTeams przyjmuje webhook Teams (wymagany), wiadomość, kolor motywu (success, info, warning, error) i tablicę opcji. Możesz pobrać swój webhook Teams tworząc nowy incoming webhook. API Teams ma wiele innych atrybutów do dostosowania skrzynki wiadomości, takich jak tytuł, podsumowanie i sekcje. Więcej informacji znajdziesz w dokumentacji Microsoft Teams. Powinieneś przekazać cały URL webhooka do dyrektywy @microsoftTeams:
@finished
@microsoftTeams('webhook-url')
@endfinished