How to gradually roll out new versions of your backend

Rolling Releases allow for safe, incremental rollouts of new deployments, with no custom routing configuration or code required. This helps you to minimize the impact of mistakes when they happen and, combined with Instant Rollbacks, recover quickly. Incrementally rolling out updates goes by many names, including “Blue/Green Deployments”, “Canary Deployments”, “Phased Rollouts”, “Rolling Updates”, and more.

In this guide, you'll learn how to:

• Setup a manual Rolling Release or automatic rolling release
• Test the Rolling Release
• Release a new version
• Control rolling releases programmatically

First, we need a demo project to work with. Click here to deploy a simple Express backend using a template. Visit the deployment URL to receive a response from an Express app running on Vercel.

Set up a manual rolling release so you can move through the rest of this guide at your own pace. The Rolling Release will have two stages for production deployments:

1. Serve 50% of requests with the new deployment
2. Serve 100% of requests with the new deployment

To configure this, you can use the Vercel dashboard or Vercel CLI.

To set up a manual rolling release, visit the Rolling Releases section of the Build and Deployment settings of your project. Select “Manual” and create a two-stage rollout with the first stage set to 50% and the second stage set to 100%. Be sure to click the Save button when finished.

In your project’s directory, run this command in your terminal:

1
vercel rolling-release configure --cfg='{"enabled":true, "advancementType":"manual-approval", "stages":[{"targetPercentage":50},{"targetPercentage":100}]}'

Edit the Express application’s HTML string to have a new payload in its response, so you can see how changes to a deployment are gradually released over time.

Deploy the application to production with your changes. Either push your code to your Git repository’s main branch, or deploy it with Vercel CLI:

1
vercel deploy --prod

Your Rolling Release is now serving 50% of requests using the Current deployment and 50% of requests using the Canary deployment.

To see this in action, you can now cURL your backend:

1
# Random responses based on the 50/50 split
2
curl your-deployment-url.vercel.app
3

4
# Force responses from the Current deployment
5
curl your-deployment-url.vercel.app?vcrrForceStable=true
6

7
# Force responses from the Current deployment
8
curl your-deployment-url.vercel.app?vcrrForceCanary=true

Now that you’ve verified the changes on your Canary deployment you can promote it to serve 100% of requests.

Complete the Rolling Release by visiting the “Rolling Release” page for your project and clicking the “Complete Rollout” button.

In your project’s directory, run this command in your terminal:

1
vercel rolling-release complete --dpl=your-canary-deployment-url.vercel.app

• Learn more about Rolling Releases
• Learn more about backends on Vercel