Seamless user experience during Upsun deployment

As speed is critical to success, it’s essential to deploy as often as needed—even on Fridays. But what exactly happens during a deployment? In particular, what happens during deployment with the Upsun PaaS? A clearer picture of the deployment process, and more control over it, can significantly improve the developer experience—and allow them to move through it faster.

During a deployment—when a new commit is pushed—Upsun triggers a new build of your application. Once the build phase is done, the container is deployed and the deploy script is executed. Any pending requests are withheld during that phase and replayed when the application is available. However, downtime inevitably creeps in any migration or any other action that takes too long, causing significant frustration among editors and customers.

Fortunately, the Upsun cache mechanism still serves read requests, facilitating zero downtime for your front end. However, write requests will still result in the dreaded 5xx errors if the deployment exceeds the 30 seconds HTTP timeout.

These are the key questions:

• How to prevent/pause your final user executing write requests during this deployment timeframe and avoid them being frustrated with HTTP 5xx errors?
• On the application side, how to get automatic notifications when a deployment is in progress?
• Who needs to listen to these deploy events?

Upsun provides infrastructure events that can be automatically sent to an external application — referred to as a status-holder application — using a webhook integration. This feature is gold but is hugely under-used and it’s time to change that.

Upsun’s versatile webhook integration empowers a status-holder application to monitor the status of your applications seamlessly. For all of you multi-application managers, you may have encountered this problem: a dedicated application for managing your main application’s status flag faltering in a multi-application architecture where each application undergoes redeployment.

This article explores a workaround that allows your application to listen to deployment signals and prevent write requests from occurring at the wrong time—let’s dive in!

🚨 Please note: This article is not meant to explain, as a dev, how to get notified and dig into your deployment failure logs nor how to get notifications if Upsun is performing routine maintenance on a region.
For such cases, please refer to the corresponding doc page or please subscribe to https://status.upsun.com

The most effective infrastructure event workflow

A webhook integration is a way to create an infrastructure event listener (kind of) that will send requested infrastructure events to an endpoint of your choice (parameter --type; URL, script, slack channel, etc.).

By using a webhook integration, Upsun can send infrastructure events that occur along the way on your main application directly to the status-holder application.

The status-holder application, responsible for storing the status of your main application, cannot be on the same infrastructure (a.k.a. multiple applications in the same project). This is because the deploy process will redeploy each of the applications within your environment, so, the status-holder application won’t be available, just like your main application during any deployment. That’s why this status-holder application needs to be hosted outside of your main project—on another Upsun project, perhaps.

On the frontend of your main application, as HTML interfaces are already loaded in the browser, you can use a Javascript banner (a.k.a. a Website Banner on the workflow diagram) that will be able to request the actual infrastructure status of your main application every so many seconds.

As soon as the main status changes, the status-holder application will receive the event and store the main application status. On the next count, the website banner will receive the new status and display a message to your visitors, asking them to hold on for a few, until your application is back. When deployment is complete, the website banner will automatically disappear.

🚨 Please note: of course, displaying a website banner is an effective way to utilize this helpful infrastructure events feature but we always encourage our customers to devise their own mitigation strategy tailored to their needs.

How to set up an infrastructure events workflow

Create a status-holder project

This upsun-status-project GitHub repository contains a basic Laravel application designed to receive infrastructure notifications, cache them (using Redis), and has an /api root to request specific environment status (format /api/<projectId>/<environment>).

🚨 Please note: for this tutorial, we use a Laravel application for the status-holder app but feel free to reuse the business logic and come up with a solution using any other framework you like.

The source code in this GitHub repository is already Upsun-ready, so you can fork it in your own GitHub organization and start using it as is. Then, you just need to create an empty Upsun project and add a source integration to sync your Upsun project with your new GitHub repository. Use the 4 following command lines from the root of your status-holder source code to do so:

git clone git@github.com:<OWNER/REPOSITORY>
cd <REPOSITORY>
upsun project:create
upsun integration:add --project <PROJECT_ID> --type github --repository <OWNER/REPOSITORY> --token <GITHUB_ACCESS_TOKEN> 

• <PROJECT_ID> is the ID of your new status-holder Upsun project that you get after executing the upsun project:create command line.
• <OWNER/REPOSITORY> is your forked repository in GitHub.
• <GITHUB_ACCESS_TOKEN> is your generated GitHub API Token.

For more information, please refer to the enable integration documentation page.

🚨 Please note: as soon as your status-holder project is deployed, pull the corresponding environment URL aside, <STATUS_HOLDER_URL>, for later steps. To get this corresponding URL outside of the deployment logs, use the following command from the root of your status-holder project:

upsun environment:url --primary --pipe

How to integrate the status-holder project with your main project

These steps will explain how to connect your main project infrastructure events with the status-holder project, and then display the website banner when a deployment is triggered.

🚨 Please note: if you don’t have an existing Upsun main project, take a look at this simple tutorial on how to host a Symfony Demo application on Upsun and then use this Symfony application for testing.

1. Add a webhook integration

Your main application needs to send any infrastructure events that are triggered to the status-holder project. To do so, please execute the following CLI command, from the root of your main project, to create a webhook integration:

upsun integration:add --type=webhook --url=<STATUS_HOLDER_URL>/api/ --states=in_progress,complete --environments main --events \*

🚨 Please note: <STATUS_HOLDER_URL> is the URL of your status-holder project, created during the create a status-holder project step above. You can also use <STATUS_HOLDER_URL> and /api/ as a suffix to use the status-holder API route that will store the current status of your main application.

2. Integrate the built-in JavaScript banner

Good news, we already designed a JavaScript banner script using Notiflix so you don’t have to. This website-banner.js script displays a JavaScript banner to your visitors as soon as something is happening on the infrastructure side and informs them to hold on for a moment until the application is back up and running.

You need to display this banner where critical actions may happen on your website, like on the edit interface (admin) of an article or on your basket interface (ecommerce websites) where customers may approve their baskets (=writing into the database) or on the registration page.

🚨 Please note: This script is not needed on static pages as Upsun will continue serving cached pages during the process.

You can download this JavaScript banner file for your Symfony project, using the following:

curl -L https://raw.githubusercontent.com/upsun/snippets/main/src/website-banner.js > assets/js/website-banner.js
git add assets/js/website-banner.js && git commit -m "Add website-banner.js"

🚨 Please note: at the beginning of this website-banner.js script, you need to customize projectId, environment, statusHolderEndpoint and interval variables with your own information, and please also customize the default message on line 33.

Then, you need to import this script into your application. In your Symfony Demo application, you just need to add this Javascript command at the beginning of the import section of your assets/admin.js file:

import …
import './js/website-banner.js';

🚨 Please note: If you’re not using a Symfony application, please refer to the corresponding official stack guide on how to include a Javascript file into your application.

3. Include Notiflix assets in your HTML layout

The Notiflix JS library needs some assets, so you need to include the following instruction in your HTML layout, within the HTML <head> section:

<script src="https://cdn.jsdelivr.net/npm/notiflix@3.2.7/dist/notiflix-aio-3.2.7.min.js"></script>
<link href="https://cdn.jsdelivr.net/npm/notiflix@3.2.7/src/notiflix.min.css" rel="stylesheet">

🚨 Please note: I randomly chose the Notiflix JS library to display the message. This JavaScript banner is displayed on top of everything, preventing the end user from doing anything until the application is back. Feel free to customize this message in whatever way you want.

4. Commit and deploy

You then need to commit your files and deploy your application, using the following command:

git add . && git commit -m "Adding notification banner"
upsun push

5. Test it

As soon as the notification banner script is deployed on your main application, you can test it by going to your admin website and using the following command lines:

upsun project:clear-build-cache
upsun redeploy

This will redeploy your application (shorter than a deployment with source modification) and display the banner. You should see something like this on top of all interfaces that include this notification banner script.

Et voilà, you’re all set and will now automatically inform your visitors on production to wait a few moments while maintenance of your application is happening and prevent displaying those annoying 5xx HTTP errors.