How to do Zero Downtime deploys for a Laravel app with Envoy

Photo by Robert V. Ruggiero on Unsplash

TL;DR

1. Configure SSH key into your VPS
2. Copy the generated public key to GitLab or GitHub
3. Access to your VPS from your computer using a SSH key
4. Add the Envoy.blade.php file to your project
5. Set initial project structure into your VPS
6. Do a deploy from your computer

Requirement

• Install Laravel Envoy inside your computer

1. Configure Server with SSH for GitLab

For reference you can check the SSH GitLab docs.

In your server, generate new SSH key with name id_gitlab wihtout password

ssh-keygen -t rsa -b 4096 -C "youremail@example.com" -f ~/.ssh/id_gitlab

And also add the following SSH configuration in ~/.ssh/config

Host gitlab.com
    Hostname gitlab.com
    PreferredAuthentications publickey
    IdentityFile ~/.ssh/id_gitlab

And now add the GitLab identity

eval $(ssh-agent -s)
ssh-add ~/.ssh/id_gitlab

2. Copy the generated public key to GitLab or GitHub

Copy the generated public key add it (id_gitlab.pub) to your SSH Keys in your GitLab account

SSH keys section inside your GitLab account

You can now test connection with GitLab inside your server running:

ssh -T git@gitlab.com

3. Access to your VPS from your computer using a SSH key

Having your own ssh key from your computer to your server, ensure that you can connect to it without problems. Also you can use a simple user and password configuration, but I don’t recommend it.

4. Add the Envoy.blade.php file to your project

For use zero downtime deploys, you need to structure project folder in this way:

* -- /path/project
  |---------- current --> /path/project/releases/latestrelease
  |---------- .env
  |---------- releases
  |---------- storage

Also you need to update the virtual host configuration to point to /path/project/current/public

To achieve this structure, first of all, you must add a new Envoy.blade.php file in the root of your project and use this configurations:

Also, add the following variables into your .env file in your local project

DEPLOY_USER=deployeruser
DEPLOY_SERVER=11.22.33.44
DEPLOY_BASE_DIR=/path/project
DEPLOY_REPO=urlofyourrepo

It’s important to note that the DEPLOY_BASE_DIR value must be an existing path in your server, inside it we’ill generate the structure seen above.

5. Set initial project structure into your VPS

Having an empty project folder in the server, for example/path/project you can run into your computer, inside your project path:

envoy run init

This command will generate the initial scaffolding of your project into your server, now connect via ssh into the server, go to your project path and fill .env file with you needed settings.

Note: in case you get errors, maybe you will modify the Envoy init script.

6. Do a deploy from your computer

Finally, you can run the following command and see the magic:

envoy run deploy

envoy deploy task

If you need to do a rollback task, you can use this command:

envoy run rollback

More settings and info can be founded in my personal repository :)