Laravel Envoy
소개
Laravel Envoy는 원격 서버에서 실행하는 일반적인 작업을 실행하기 위한 도구입니다. Blade 스타일 구문을 사용하여 배포, Artisan 명령어 등을 위한 작업을 쉽게 설정할 수 있습니다. 현재 Envoy는 Mac 및 Linux 운영 체제만 지원합니다. 하지만 WSL2를 사용하여 Windows 지원이 가능합니다.
설치
먼저 Composer 패키지 관리자를 사용하여 Envoy를 프로젝트에 설치합니다.
composer require laravel/envoy --devEnvoy가 설치되면 Envoy 바이너리가 애플리케이션의 vendor/bin 디렉터리에서 사용할 수 있습니다.
php vendor/bin/envoy작업 작성
작업 정의
작업은 Envoy의 기본 구성 요소입니다. 작업은 작업을 호출할 때 원격 서버에서 실행해야 하는 셸 명령을 정의합니다. 예를 들어, 애플리케이션의 모든 큐 작업자 서버에서 php artisan queue:restart 명령을 실행하는 작업을 정의할 수 있습니다.
모든 Envoy 작업은 애플리케이션 루트에 있는 Envoy.blade.php 파일에 정의해야 합니다. 시작하는 데 도움이 되는 예제가 있습니다.
@task('restart-queues', ['on' => 'workers']) cd /home/user/example.com php artisan queue:restart@endtask보시다시피, 파일 상단에 @servers 배열이 정의되어 있으며, 이를 통해 작업 선언의 on 옵션을 통해 이러한 서버들을 참조할 수 있습니다. @servers 선언은 항상 한 줄에 배치해야 합니다. @task 선언 내에는 작업이 호출될 때 서버에서 실행되어야 하는 쉘 명령어를 배치해야 합니다.
로컬 작업
서버의 IP 주소를 127.0.0.1로 지정하여 로컬 컴퓨터에서 스크립트를 강제로 실행할 수 있습니다.
@servers(['localhost' => '127.0.0.1'])Envoy 작업 가져오기
@import 지시문을 사용하여 다른 Envoy 파일을 가져와서 해당 스토리와 작업을 사용자의 파일에 추가할 수 있습니다. 파일이 가져온 후에는 마치 자신의 Envoy 파일에 정의된 것처럼 해당 파일에 포함된 작업을 실행할 수 있습니다.
@import('vendor/package/Envoy.blade.php')다중 서버
Envoy를 사용하면 여러 서버에서 작업을 쉽게 실행할 수 있습니다. 먼저, @servers 선언에 추가 서버를 추가합니다. 각 서버에는 고유한 이름이 할당되어야 합니다. 추가 서버를 정의한 후에는 작업의 on 배열에 각 서버를 나열할 수 있습니다.
@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병렬 실행
기본적으로, 작업은 각 서버에서 순차적으로 실행됩니다. 다시 말해, 작업은 첫 번째 서버에서 실행을 마친 후에 두 번째 서버에서 실행을 진행합니다. 여러 서버에서 작업을 병렬로 실행하고 싶다면, 작업 선언에 parallel 옵션을 추가하십시오:
@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설정
때로는 Envoy 작업을 실행하기 전에 임의의 PHP 코드를 실행해야 할 수 있습니다. @setup 지시어를 사용하여 작업 전에 실행해야 하는 PHP 코드 블록을 정의할 수 있습니다:
@setup $now = new DateTime;@endsetup작업이 실행되기 전에 다른 PHP 파일을 포함해야 하는 경우, Envoy.blade.php 파일의 맨 위에 @include 지시어를 사용할 수 있습니다:
@include('vendor/autoload.php') @task('restart-queues') # ...@endtask변수
필요한 경우, Envoy를 호출할 때 명령줄에서 Envoy 작업에 인수를 전달할 수 있습니다:
php vendor/bin/envoy run deploy --branch=masterBlade의 "echo" 구문을 사용하여 작업 내에서 옵션에 접근할 수 있습니다. 또한 작업 내에서 Blade if 문과 루프를 정의할 수도 있습니다. 예를 들어, git pull 명령을 실행하기 전에 $branch 변수의 존재를 확인해 보겠습니다:
@task('deploy', ['on' => 'web']) cd /home/user/example.com @if ($branch) git pull origin {{ $branch }} @endif php artisan migrate --force@endtask스토리
스토리는 편리한 하나의 이름으로 작업들을 묶습니다. 예를 들어, deploy 스토리는 정의 내에 작업 이름을 나열하여 update-code와 install-dependencies 작업을 실행할 수 있습니다:
@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스토리가 작성되면 작업을 호출하는 것과 같은 방식으로 호출할 수 있습니다:
php vendor/bin/envoy run deploy후크
작업 및 스토리가 실행될 때 여러 개의 후크가 실행됩니다. Envoy에서 지원하는 후크 유형은 @before, @after, @error, @success, 및 @finished입니다. 이러한 후크의 모든 코드는 PHP로 해석되며, 작업이 상호 작용하는 원격 서버가 아닌 로컬에서 실행됩니다.
이러한 후크를 원하는 만큼 많이 정의할 수 있습니다. 스크립트 내에 나타나는 순서대로 실행됩니다.
@before
각 작업 실행 전에 Envoy 스크립트에 등록된 모든 @before 후크가 실행됩니다. @before 후크는 실행될 작업의 이름을 받습니다:
@before if ($task === 'deploy') { // ... }@endbefore@after
각 작업 실행 후, Envoy 스크립트에 등록된 모든 @after 후크가 실행됩니다. @after 후크는 실행된 작업의 이름을 받습니다:
@after if ($task === 'deploy') { // ... }@endafter@error
모든 작업 실패(상태 코드가 0보다 큰 값으로 종료) 후, Envoy 스크립트에 등록된 모든 @error 훅이 실행됩니다. @error 훅은 실행된 작업의 이름을 받습니다.
@error if ($task === 'deploy') { // ... }@enderror@success
오류 없이 모든 작업이 실행된 경우, Envoy 스크립트에 등록된 모든 @success 훅이 실행됩니다.
@success // ...@endsuccess@finished
모든 작업이 실행된 후(종료 상태에 관계없이), 모든 @finished 훅이 실행됩니다. @finished 훅은 완료된 작업의 상태 코드를 받으며, 이는 null이거나 0 이상의 정수일 수 있습니다.
@finished if ($exitCode > 0) { // 작업 중 하나에 오류가 있었습니다... }@endfinished작업 실행
애플리케이션의 Envoy.blade.php 파일에 정의된 작업 또는 스토리를 실행하려면 Envoy의 run 명령을 실행하고 실행하려는 작업 또는 스토리의 이름을 전달합니다. Envoy는 작업을 실행하고 작업이 실행되는 동안 원격 서버의 출력을 표시합니다.
php vendor/bin/envoy run deploy작업 실행 확인
서버에서 특정 작업을 실행하기 전에 확인 메시지를 표시하려면 작업 선언에 confirm 지시어를 추가해야 합니다. 이 옵션은 파괴적인 작업에 특히 유용합니다.
@task('deploy', ['on' => 'web', 'confirm' => true]) cd /home/user/example.com git pull origin {{ $branch }} php artisan migrate@endtask알림
Slack
Envoy는 각 작업이 실행된 후 Slack으로 알림을 보내는 것을 지원합니다. @slack 지시어는 Slack 후크 URL과 채널/사용자 이름을 받습니다. Slack 제어판에서 "Incoming WebHooks" 통합을 생성하여 웹훅 URL을 가져올 수 있습니다.
전체 웹훅 URL을 @slack 지시어에 주어진 첫 번째 인수로 전달해야 합니다. @slack 지시어에 주어진 두 번째 인수는 채널 이름 (#channel) 또는 사용자 이름 (@user)이어야 합니다.
@finished @slack('webhook-url', '#bots')@endfinished기본적으로 Envoy 알림은 실행된 작업을 설명하는 메시지를 알림 채널로 보냅니다. 그러나 @slack 지시어에 세 번째 인수를 전달하여 이 메시지를 사용자 정의 메시지로 덮어쓸 수 있습니다.
@finished @slack('webhook-url', '#bots', 'Hello, Slack.')@endfinishedDiscord
Envoy는 각 작업이 실행된 후 Discord로 알림을 보내는 것도 지원합니다. @discord 지시어는 Discord 후크 URL과 메시지를 받습니다. 서버 설정에서 "Webhook"을 생성하고 웹훅이 게시될 채널을 선택하여 웹훅 URL을 가져올 수 있습니다. 전체 웹훅 URL을 @discord 지시어에 전달해야 합니다.
@finished @discord('discord-webhook-url')@endfinishedTelegram
Envoy는 각 작업이 실행된 후 Telegram으로 알림을 보내는 것도 지원합니다. @telegram 지시어는 Telegram 봇 ID와 채팅 ID를 받습니다. BotFather를 사용하여 새 봇을 생성하여 봇 ID를 가져올 수 있습니다. @username_to_id_bot을 사용하여 유효한 채팅 ID를 가져올 수 있습니다. 전체 봇 ID와 채팅 ID를 @telegram 지시어에 전달해야 합니다.
@finished @telegram('bot-id','chat-id')@endfinishedMicrosoft Teams
Envoy는 각 작업이 실행된 후 Microsoft Teams로 알림을 보내는 기능도 지원합니다. @microsoftTeams 지시어는 Teams Webhook(필수), 메시지, 테마 색상(성공, 정보, 경고, 오류) 및 옵션 배열을 허용합니다. 새로운 수신 웹후크를 생성하여 Teams Webhook을 가져올 수 있습니다. Teams API에는 제목, 요약 및 섹션과 같이 메시지 상자를 사용자 지정할 수 있는 다른 많은 속성이 있습니다. Microsoft Teams 문서에서 더 많은 정보를 찾을 수 있습니다. 전체 Webhook URL을 @microsoftTeams 지시어에 전달해야 합니다.
@finished @microsoftTeams('webhook-url')@endfinished