# Why Envoy

Envoy is a task runner put together by the Laravel team. When I can I like to use hosts like Pantheon and Platform.sh that give me a wealth of tools, containers in production, and a lot less DevOps headaches when something like Heartbleed happens 😱.

That said not all clients can afford the hosting costs of these providers 💸. And then Linode, Digital Ocean, or AWS become good choices starting at as little as $5/mo. So when working on your family member or friends website with affordable hosting we can use envoy to automate our deploy steps and get some of that deploy consistency that we know and love from the big hosting providers.

This post will show you how to add envoy as tooling to Lando. The particular app in this example is Backdrop CMS, but any PHP app can take advantage of Envoy, really any app (but non PHP devs prolly not looking for ways to add PHP to the mix 😈). Apps like WordPress, Symfony, Backdrop, Drupal, and of course Laravel are a perfect fit.

# Install Envoy

To add envoy tooling to your .lando.yml file add the following run step:

services:
  appserver:
    run:
      - cd $LANDO_MOUNT && composer install
      - composer global require laravel/envoy

And a corresponding tooling entry:

# See: https://docs.lndo.io/config/tooling.html
tooling:
  envoy:
    service: appserver

Now we are ready to start using Envoy, but first let's configure it.

# Configure Envoy

To use Envoy you will set up a file in the root of your project called: Envoy.blade.php. Here is mine:

@servers(['web' => ['USER@SERVER_IP']])

@task('ll', ['on' => 'web'])
  cd /var/www/serundeputy
  ls -alh
@endtask

@task('deploy', ['on' => 'web'])
  cd /var/www/serundeputy
  @if ($branch)
    git pull origin {{ $branch }}
  @endif
  composer install
  cd /var/www/serundeputy/www
  drush updb -y
  drush bcim -y
  drush cc all
@endtask

The Envoy.blade.php file uses Laravel blade syntax and in it we define servers array and some tasks. In this example you'll want to replace USER with a user that has ssh access to the server in question and SERVER_IP with the ip address of the server you are deploying to.

In the deploy task we simply write the shell commands that we want to happen for our app. In this case move to the app directory, run composer install, and some drush commands. That is it, so simple!

You don't have to worry about different people doing different steps, forgetting steps, or typing something incorrectly. Consistency and peace of mind ☮️.

You can define as many or few tasks as you need. For example you could break out the deploy task to separate deploy-staging and deploy-production tasks.

# Run an Envoy Deploy

Now that we have our tasks set up in our Envoy.blade.php file we can run them. For example to deploy run:

lando envoy run deploy --branch=master

Running this one command runs all the tasks in the deploy task!

# Conclusion

Consistency. No need to ssh into the server. No danger of running unwanted commands on the server. No leaving the shell open on a production server session for your cat to walk across your keyboard 🐈. Just the things you want and need to happen for your app.

Tools and Resources:

  • Envoy ~ Run tasks on your remote servers.
  • Lando ~ A flexible local dev environment based on docker.

This post originally appeared on serundeputy.io