A Brief Introduction to Laravel Envoy

Laravel Envoy provides you a simple and elegant way to run common tasks on your remote servers. If you have ever used Fabric, Capistrano or other tools for managing remote tasks, you already have an idea how Envoy tasks will look like.

Contents

• 1 Laravel Envoy Installation
• 2 How Envoy Works
• 3 Running Tasks
• 4 Basic deployment

Laravel Envoy Installation

To install Laravel Envoy simply run:

composer global require "laravel/envoy=~1.0"

after that, make sure ~/.composer/vendor/bin/envoy is flagged as executable:

chmod +x ~/.composer/vendor/bin/envoy

Note: Laravel Envoy requires PHP version 5.4 or greater, and only runs on Mac and GNU/Linux operating systems.

For easier access to the envoy command, you should create symbolic link to the ~/.composer/vendor/bin/envoy. On GNU/Linux operating systems, symbolic links are created with ln command:

mirzap@bosnadev:~$ sudo ln -s ~/.composer/vendor/bin/envoy /usr/bin/envoy

Alternatively, you can create an alias for the ~/.composer/vendor/bin/envoy command. Depending on which shell you are using, in your ~/.bashrc or ~/.zshrc file put this:

alias envoy="~/.composer/vendor/bin/envoy"

How Envoy Works

Note: Envoy is not Laravel dependent, which means you can use it on any PHP project you want.

To create tasks you use Blade style syntax. Laravel Envoy doesn’t require Blade template engine, it just uses Blade syntax to define tasks. To start, create an Envoy.blade.php in the root folder of your project. Next, create a simple task:

@servers(['homestead' => '[email protected]'])@task('list', ['on' => 'homestead'])    ls -lah@endtask

As you might suppose, in the @servers declaration we configure our server list. Here you can put your staging, testing or production servers. Then within our @task directive we can tell Envoy on what server we want to execute that task. If you want to execute only on one server, you pass only name you defined in the @servers declaration. If you want to execute task across multiple servers, you simply list them in the @task declaration:

-removed: @servers(['homestead' => '[email protected]'])+added: @servers(['homestead' => '[email protected]', 'staging' => '[email protected]'])-removed: @task('list', ['on' => 'homestead'])+added: @task('list', ['on' => ['homestead', 'staging']])    ls -lah@endtask

Running Tasks

To run Envoy tasks you simply use run command:

envoy run list

which will execute the task we defined above. Result is:

Basic deployment

I tend to have very simple script when doing deployment, less code – less chance for something to go wrong. With that in mind let’s create our deployment.sh script in the project root folder:

#!/bin/bashfunction deploy() {    # make sure we pull master branch for production environment    BRANCH=$([ $1 == "production" ] && echo "master" || echo "staging")    echo "Starting deployment on s <$1> environment"    composer dump-autoload -o    # Start SSH agent & add identity to the agent    killall ssh-agent; eval `ssh-agent`    ssh-add ~/.ssh/private_key    echo "Pulling $BRANCH branch..."    git pull gitlab ${BRANCH}    php artisan migrate --env=$1    php artisan migrate --bench=bosnadev/some_component --env=$1    composer dump-autoload -o}function help() {    echo ""    echo "   Please specify on what environment you want to deploy: "    echo "   ./deployment.sh env"    echo ""}## If no argument suppliedif [ -z "$1" ]; then    echo "No arguments supplied"fi## If wrong number of argument has been suppliedif [ ! $# == 1 ]; then    help $#else    # We can deploy only on staging and production    if [ $1 == 'staging' ] || [ $1 == 'production' ]; then        deploy $1    fifi

And my Envoy.blade.php looks like:

@servers(['homestead' => '[email protected] -p 2222','staging' => '[email protected] -p 22', 'production' => '[email protected] -p 22' ])@setup    $param = isset($param) ? $param : null@endsetup@task('artisan', ['on' => 'homestead'])    cd www/someapp    php artisan {{ $param }}@endtask@task('composer', ['on' => 'homestead'])    cd www/someapp    composer {{ $param }}@endtask@task('deploy-staging', ['on' => 'staging'])    cd someapp    ./deployment.sh staging@endtask@task('deploy-production', ['on' => 'production'])    cd someapp    ./deployment.sh production@endtask

Now, when you want to deploy to the staging just run:

envoy run deploy-staging

Or if you deploying to the production, run deploy-production task:

envoy run deploy-production

As you can see, it’s pretty straight forward. Of course, you can create much more complex deployment tasks, it’s entirely up to you. Feel free to share your knowledge and experience with Laravel Envoy, or share your best practices when dealing with remote tasks.