Laravel Envoy Task Runner

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.

Laravel Envoy Installation

To install Laravel Envoy simply run:

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

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:

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:

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:

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:

Running Tasks

To run Envoy tasks you simply use  run  command:

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

Laravel Envoy  Run CommandBasic 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  script in the project root folder:

And my  Envoy.blade.php  looks like:

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

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

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.


Follow me

Mirza Pasic

Full Stack Developer at OLX
Web Developer. Geek. Systematic. Dreamer
Follow me

Published by

Mirza Pasic

Web Developer. Geek. Systematic. Dreamer

  • Thx for the article. Envoy is very powerful feature, that makes deploy really easy

  • fideloper

    I’m curious about the purpose of the SSH agent items you’re doing in the deploy function of your bash script?

    The items under “# Start SSH agent & add identity to the agent”

    • Hi fideloper,

      without that I had problem pulling the repository and that key is used only for that git repo. I had limited access to the client server and this is the (only!) way that I found to work. Whatever else I tried I got the error that ssh agent is not running. I see you have much more experience, any suggestion?

      • fideloper

        That’s interesting! I’m not sure what might have caused that unfortunately.

        Based on what I can google about it, it *might* be something to do with your setup (where you are deploying to) specifically.

        Ssh-agent is a way to store/cache ssh keys so you don’t need to re-enter a ssh key password every time you use it.

        Check this out as a potential solution for your case:

        (I’ve never run into this — I’m curious about why it popped up for you as an issue! What kind of server are you deploying to?)

  • Tamer Fares

    I have a problem please help
    when I run the command “envoy run MyTaskName” nothing happens!!
    what I’m missing?

  • Celso Andrade

    @setup is not working for me. I can’t use any variable set inside @setup @endsetup

  • Spas

    I’m intersted in programicly push ip’s into @server variable. Is there any way ?

    • Mattias

      Me too. I haven’t tested this code, but it should work.

  • Mattias

    Really cool service. I wonder how it works with servers where you don’t keep sshkeys, but auth using username and password. Is this achievable?