Laravel Envoy setup

Introduction

I'm sure that I'm not the only person like this but i often forget to run certain commands when pulling my blog live from GitHub. The two I'm terrible for are php artisan migrate and php artisan config:cache. I don't know what the reason is for this but its been a pain in the neck for me for a while, i shamefully spent 45 mins trying to figure out why my posts weren't going over to Dev.to and the only error i was getting was "connection refused". Turns out i had not run the config cache to make my .env changes live...

Introducing Envoy

Envoy isn't a new package and I've just put off setting it up for no good reason until today.... its time to get the automation of my pull's to live working and it couldn't be easier!.

Step One - Require the package

As with almost all packages worth mentioning with Laravel this has a simple command to install:

composer require laravel/envoy --dev

Ye that's really it for the installation...

Step 2 - Specify the server

Envoy uses code from a file in the root of your project (which you need to create) called Envoy.blade.php. In this file we will specify our Server and the jobs required.

so firs things first we need to specify the server to run the code one.

@servers(['localhost' => '127.0.0.1'])

I'm setting this up for my blog, so i don't have any replication as at this stage it would be overkill for my simple setup. if you wanted to add more than one server you would need to pass the server names and IP's to the Array like below:

@servers(['Raspada-web-1' => '192.168.1.68', 'Raspada-web-2' => '192.168.1.69'])

Step 3 - Lets tell a story!

Thing i like about the way Envoy works is i can set it up and "talk out" my process like i do to my "Coding Duck"... if your Unsure what a coding duck is, quite simply its a rubber duck that when i'm struggling with a problem i talk through my issue with the duck... Sounds mental but it bloody works, often talking through your issue out loud will help you solve it... anyway back to our story. What should i be doing each time i make changes and make them live....

Git pull: Well duh! Merge the branch your working on into the main/master and pull to live
Migrate: i want to run the migrate command just in case i have made some changes to tables.
install composer packages for production: i want to install the packages for the live environment... not dev ones.
Dump-Autoload: i want to clear out any auto-loaded classes that may have changed with my work completed.
config-cache: i want to ensure all changes i have made to files like .env or saved to cache.

And that's our story! so how do we define this? well we use the @story code and name our story... for this tutorial were going to use:

@story('code_update')
// story chapters here
@endstory

So my story so far is this:

@servers(['localhost' => '127.0.0.1'])

@story('code_update')
gitpull
migrate
composerinstall
dumpautoload
savenewconfig
@endstory

Step 4 - Create the Tasks

Now that we have our main story for envoy we need to make each individual task with the required code inside.

So first things first id suggest layout out each task accordingly like below:

@servers(['localhost' => '127.0.0.1'])

@story('code_update')
gitpull
migrate
composerinstall
dumpautoload
savenewconfig
@endstory


@task('gitpull')

@endtask

@task('migrate')

@endtask

@task('composerinstall')

@endtask

@task('dumpautoload')

@endtask

@task('savenewconfig')

@endtask

Starting to get the idea?

Step 5 - Add the commands

For this bit you just need to write the commands you would normally run (when you don't forget :S ) inside each of the tasks. when you're finished you should have something like mine below:

@task('gitpull')
    git pull
@endtask

@task('migrate')
    php artisan migrate --force
@endtask

@task('composerinstall')
    composer install --no-dev
@endtask

@task('dumpautoload')
    composer dump-autoload
@endtask

@task('savenewconfig')
    php artisan config:cache
@endtask

Step 6 - Finish the story

All good stories come to an end... and envoy isn't any different we need to set the @finished flag

You could leave this blank if you wanted to but seems a bit daft when Envoy makes it so easy to integrate with platforms like Slack, MS teams and Discord.

For this im going to be just using some text in the terminal for when i pull.

@finished
    if ($exitCode > 0) {
       <span class="hljs-regexp">// There were errors in one of the tasks...
    }
@endfinished
</span>

Run the Envoy command

So first of we will pull this to our live environment after out branch merge (unless you were naughty and working on main/master!).

we will then need to run composer install to just get Envoy working on live. and then you can run your full story by typing this:

php vendor/bin/envoy run code_update

The first time i ran this i got a bit scared because i seen a wall of red text.... don't worry its fine!... and that it, if you really want to be clever you could alias the command in your terminal to something like deploy-blog, deploy-saas so from anywhere on your server it will CD to the directory and run the command for you.

All done...

Now this will go live and just work and it will make my life easier. i haven't even scratched the surface yet with what i can do with envoy, I've not spoken about queue:restarts as i don't have any queues yet, I've not talked about running the envoy stories on multiple servers at the same time either. there is so much more this package can do!