Recently, I was looking for a way to deploy a Laravel application with ease and no headache. After some time, I wrote a very basic Bash script to automate the common deployment tasks: pulling changes from Git, installing Composer dependencies, building NPM scripts, running migrations and so on. But it was still feeling primitive. There had to be a better way.

After some research, I found Laravel Envoyer. This service offers everything I needed but I was not ready to pay the costs associated. After further research, I found Laravel Envoy. Even though their names are similar, they do not provide the same services: while Envoyer is a full featured product ready to use, Laravel Envoy provides a template for deployment tasks.

The main benefit of using Envoy over a Bash script is its integration with PHP: that makes it possible to use credentials stored in the .env file used by Laravel. It is also possible to specify several environments to deploy the application, and send notifications at the end of the deployments. The documentation is very detailed.

With Envoy, we will be writing tasks that are integrated into stories. For example, the “deploy” story will contain the composer task, NPM task and so on.

On top of that, we want to be able to deploy the application with no downtime. The structure we will have is the following:

/current symbolic link pointing to /releases/latestdate

/releases folder containing the releases like 20190602000000, 20190602000001 and so on

/storage the storage folder used by our application. This one stays between releases, so each releases’ storage folder is actually a symbolic link to this on

.env the environment file used by our application and linked to by each release like the storage folder



Thus, the server will point to the /current/public folder.

The /current symbolic link we be updated once we have finished to build the application in a separate folder, ie /releases/20190602000000 for example.



Moving on to the actual Envoy script: we will write a script that:

fetches the latest code from our Git repository

install latest composer dependencies

run NPM install and NPM run

update the symlinks as explained above

update the application cache for maximum performance

run the MySQL migration

clean the releases folder so we only keep the latest five

The script I will detail below is a compilation of three great scripts I found online at:

First, install Envoy globally as explained in the documentation:

composer global require laravel/envoy

Add composer’s bin directory to your PATH variable:

export PATH=~/.composer/vendor/bin:$PATH

Add the following entries to our .env file:

DEPLOY_USER=SSH user DEPLOY_SERVER=SSH host DEPLOY_BASE_DIR=directory where the folder structure explained above will reside DEPLOY_REPO=Git repository to clone

For it to work on your computer, you should use a SSH keyfile to connect to your server and add it to your SSH local configuration so that a “ssh [email protected]” command connects you in the server. This is a great tutorial to achieve this purpose. Long story short:

nano ~/.ssh/config

Host your-host.com User your-user HostName your-host.com IdentityFile /path-to-your-identity-file

chmod 600 ~/.ssh/config

Then, you can create a new file named Envoy.blade.php at the root of your Laravel application.

The first time you run the script, you can initialize it with

envoy init --branch=YOUR_GIT_BRANCH

Now, you can deploy your application with

envoy deploy --branch=YOUR_GIT_BRANCH

You can also specify the directory with –baseDir, otherwise it will default to the one specified in the .env.

If something goes wrong during a deployment, you can rollback to the previous version with:

envoy rollback --branch=YOUR_GIT_BRANCH

This will update the /current symlink to the previous release.

Then, you can integrate this with your Git repository to run the deploy command after each commit for example. Happy deployments!