Envoy

시작하기

Laravel Envoy는 원격 서버에서 자주 사용하는 작업을 실행하기 위한 도구입니다. Blade와 같은 문법을 사용하여 배포나 Artisan 명령 실행 등의 작업을 간단히 정의할 수 있습니다.

Envoy는 현재 macOS와 Linux만 지원합니다. Windows에서 사용할 경우 WSL2 경유의 이용이 필요합니다.

설치

Composer 패키지 매니저를 사용하여 프로젝트에 Envoy를 설치합니다.

composer require laravel/envoy --dev

설치 후, vendor/bin 디렉터리에 Envoy 실행 파일이 이용 가능해집니다.

php vendor/bin/envoy

작업 만들기

작업 정의

작업은 Envoy의 기본 구성 요소입니다. 작업은 작업 실행 시 원격 서버상에서 실행해야 할 셸 명령을 정의합니다. 예를 들어 모든 큐 워커 서버에서 php artisan queue:restart 명령을 실행하는 작업을 정의할 수 있습니다. Envoy 작업은 모두 애플리케이션 루트에 있는 Envoy.blade.php 파일에 정의합니다.

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

@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 디렉티브를 사용합니다.

@setup
    $now = new DateTime;
@endsetup

작업 실행 전에 다른 PHP 파일을 로드해야 할 경우, Envoy.blade.php 파일 맨 앞에서 @include 디렉티브를 사용합니다.

@include('vendor/autoload.php')

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

변수

Envoy 작업을 호출할 때 커맨드 라인에서 인수를 지정하여 작업에 전달할 수 있습니다.

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

작업 내에서는 Blade의 “echo” 문법으로 옵션에 접근할 수 있습니다. Blade의 if 문이나 반복문도 정의할 수 있습니다. 예를 들어 git pull 명령을 실행하기 전에 $branch 변수의 존재를 확인하는 경우 다음과 같이 합니다.

@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

스토리

스토리는 일련의 작업을 하나의 편리한 이름으로 그룹화합니다. 예를 들어 deploy 스토리에서 update-code 작업과 install-dependencies 작업을 함께 실행할 수 있습니다.

@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

스토리를 작성했다면, 작업과 동일한 방법으로 호출할 수 있습니다.

php vendor/bin/envoy run deploy

완료 훅

작업이나 스토리를 실행할 때 여러 훅이 실행됩니다. Envoy가 지원하는 훅의 종류는 @before, @after, @error, @success, @finished입니다. 이 훅 내의 코드는 모두 PHP로 해석되어, 작업이 조작하는 원격 서버가 아니라 로컬에서 실행됩니다. 각 훅은 얼마든지 정의할 수 있으며, Envoy 스크립트에 작성된 순서대로 실행됩니다.

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

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

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

@success
    // ...
@endsuccess

@finished
    if ($exitCode > 0) {
        // 어느 작업에서 오류가 발생함...
    }
@endfinished

@finished 훅은 실행이 완료된 작업의 상태 코드를 받습니다. 상태 코드는 null 또는 0 이상의 정수입니다.

작업 실행

애플리케이션의 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의 Webhook URL과 채널명(또는 사용자명)을 받습니다. Webhook URL은 Slack 컨트롤 패널에서 “Incoming WebHooks” 인테그레이션을 만들면 얻을 수 있습니다. @slack 디렉티브의 첫 번째 인수에는 Webhook URL 전체를 전달합니다. 두 번째 인수에는 채널명(#channel) 또는 사용자명(@user)을 지정합니다.

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

기본적으로는 실행된 작업을 설명하는 메시지가 알림 채널에 전송됩니다. @slack 디렉티브에 세 번째 인수를 전달하여 자체 메시지로 덮어쓸 수 있습니다.

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

Discord

Envoy는 각 작업 실행 후 Discord에 알림을 보내는 것도 지원합니다. @discord 디렉티브는 Discord의 Webhook URL과 메시지를 받습니다. Webhook URL은 서버 설정 내에서 “Webhook”을 만들고 게시할 채널을 선택함으로써 얻을 수 있습니다.

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

Envoy는 각 작업 실행 후 Telegram에 알림을 보내는 것도 지원합니다. @telegram 디렉티브는 Telegram Bot ID와 Chat ID를 받습니다. Bot ID는 BotFather에서 새로운 봇을 만들면 얻을 수 있습니다. Chat ID는 @username_to_id_bot을 사용하여 얻을 수 있습니다.

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

Microsoft Teams

Envoy는 각 작업 실행 후 Microsoft Teams에 알림을 보내는 것도 지원합니다. @teams 디렉티브는 Teams의 webhook(필수), 메시지, 테마 색상(success, info, warning, error), 그리고 옵셔널 설정 배열을 받습니다. Teams의 webhook은 Incoming Webhook을 만들어 얻을 수 있습니다. Teams API에는 그 외에도 많은 설정 항목이 있어 자체 메시지 카드를 자유롭게 만들 수 있습니다. 자세한 내용은 Microsoft Teams 문서를 참조하세요.

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

Envoy는 원격 서버로의 SSH 연결을 전제로 합니다. 실행 환경에 따라 키 인증 설정이나 서버에 대한 접근 제어를 사전에 마쳐 두어야 합니다. 보다 고도의 배포 자동화가 필요한 경우, 디플로이먼트 가이드나 GitHub Actions와의 조합도 검토하세요.

아키텍처

데이터베이스

Eloquent

보안

이벤트

메일과 알림

결제

비동기 처리

실시간 통신

스케줄링

캐시와 최적화

국제화

파일과 스토리지

디버깅과 모니터링

콘솔과 CLI

성능

프런트엔드

AI 개발

개발 환경

시작하기

설치

작업 만들기

작업 정의

로컬 작업

Envoy 작업 임포트

여러 서버

병렬 실행

셋업

변수

스토리

완료 훅

작업 실행

작업 실행 확인

알림

Slack

Discord

Telegram

Microsoft Teams

​시작하기

​설치

​작업 만들기

​작업 정의

​로컬 작업

​Envoy 작업 임포트

​여러 서버

​병렬 실행

​셋업

​변수

​스토리

​완료 훅

​작업 실행

​작업 실행 확인

​알림

​Slack

​Discord

​Telegram

​Microsoft Teams

시작하기

설치

작업 만들기

작업 정의

로컬 작업

Envoy 작업 임포트

여러 서버

병렬 실행

셋업

변수

스토리

완료 훅

작업 실행

작업 실행 확인

알림

Slack

Discord

Telegram

Microsoft Teams