Zero-Downtime Deployment with Envoyer

Our client was happy with the deployment, but they were not happy that the website was down for a while, during the deployment. And that makes sense! We have our script set up to take our application down:

cd /home/forge/v2.linksletter.com
if [ -f artisan ]; then
    $FORGE_PHP artisan down
fi
 
git pull origin $FORGE_SITE_BRANCH
$FORGE_COMPOSER install --no-dev --no-interaction --prefer-dist --optimize-autoloader
 
npm install
npm run build
 
rm -rf /node_modules
 
if [ -f artisan ]; then
    $FORGE_PHP artisan cache:clear
    $FORGE_PHP artisan view:clear
    $FORGE_PHP artisan route:cache
    $FORGE_PHP artisan config:cache
    $FORGE_PHP artisan view:cache
fi
 
( flock -w 10 9 || exit 1
    echo 'Restarting FPM...'; sudo -S service $FORGE_PHP_FPM reload ) 9>/tmp/fpmlock
 
if [ -f artisan ]; then
    $FORGE_PHP artisan migrate --force
    $FORGE_PHP artisan up
fi

Specifically, the artisan down and artisan up commands. They take our application into maintenance mode for a few minutes. Let's look at Forge's deployment history:

It takes 10-20 seconds; imagine if our application grew in complexity and size. This can grow exponentially!

So, what are our solutions? We can use a zero-downtime deployment tool like official Laravel Envoyer.

There are also other alternatives:

• Ploi
• Deployer
• Buddy
• Jenkins
• And probably many more!

But for this tutorial, we chose Envoyer because it's a first-party tool from Laravel team.

Let's set it up!

Configuring Envoyer

To set up Envoyer, we must go to the Envoyer website and sign up for an account. Once we have an account, we can start the import process:

1. Open Forge and visit My Account (top right - click on profile picture for dropdown).

2. Click on Envoyer in the sidebar:

3. On this page, find API Token and click on it. It will open a new Envoyer page:

4. Copy the token and return it to Forge. Paste the token in the API Token field and click Save.

5. Return to the Envoyer page and click Add Project. Fill out the form:

6. Click on Import from Forge in the window that opens:

7. Select the server you want to import and the site:

8. Click Import Server and wait for the process to finish.

9. Visit the Deployments tab and click Add Hook. Inside, fill out the form:

cd {{ release }}
 
npm install
npm run build
 
rm -rf /node_modules

10. Save it, and move it after Install Composer Dependencies:

11. Click on Add Hook again and fill out the form:

cd {{ release }}
 
if [ -f artisan ]; then
    php artisan cache:clear
    php artisan view:clear
    php artisan route:cache
    php artisan config:cache
    php artisan view:cache
 
    php artisan queue:restart
fi

12. Save it, and move it after NPM Compilation:

13. Click on Add Hook again and fill out the form:

cd {{ release }}
 
php artisan migrate --force

14. Save it and move it after Install Composer Dependencies:

15. Click on Deploy at the top of the page

16. Go into the Deployments tab and look for your deployment. Click the Right facing arrow to see the deployment log:

17. Once the deployment is done, you should see all the hooks being green:

18. Go back to Forge and visit your site.

19. Go into Settings and change the Web Directory to /current/public:

20. Visit your site and see if it's working.

That's it! Your website is now working with zero-downtime deployments!

Cleaning Up

After the Envoyer is set up, we have a mess to clean up. If we ssh into the server and do ls - we can see that there are a lot of folders:

In this case, we can follow what Official Migration Guide says:

You should now tidy your site directory by ensuring it only contains the .env file, along with the releases, current, and storage directories. After ensuring you have backed up anything you need, you may remove everything else, including any dotfiles and directories such as .git, .gitattributes, etc.

Of course, make sure to back up everything before you delete it! Once you do that, you should have a clean server:

If you followed along and cleaned up your server - open the website and see that it works. If it does - excellent!

Course Conclusion: We're LIVE - What's Next?

That's it for this course, where we tried to describe our version of proper process for creating a Laravel project from zero to going live.

Now, what should happen AFTER your project is deployed?

Maintenance.

But what does that word actually mean?

Here are a few recommendations for what you should do:

• Keep monitoring bugs with Sentry or your preferred tool. Don't forget to set up notifications so you'll be notified about issues via email, Slack, or the channels you're active on.
• Keep using the GitHub processes we described in this course to fix bugs and create new features. This will help you avoid conflicts and have peace of mind.
• Above all, communication is still the key. Both between the teammates and with the client. Whatever happens with the project currently or plans from the client, keep discussing them together and not separately. This is probably the most important general "project success" advice I can give.

You can access the complete repository here on GitHub.