Optimizely DXP Deployment API – Smooth Deployment Public Release

In my previous posts, we went over the deployment process in the Optimizely/EpiServer DXP environment. The first and the second post of the Deployment API series went through the original methods that allow for deployment into the DXP environment. Smooth Deploy is a feature that I have been looking forward to for a long time now. It is a great tool to bridge the gap during deployments for the developers, content editors, as well as the users.

As of April 19th, 2021, this feature has been released for everyone to use!!

In this post, we’re going to very quickly take a look at the features of Smooth Deployment and what we gain from it!

In this post we will go over:

What is Smooth Deploy?

Smooth Deploy, or otherwise known as Zero Downtime Deployment (ZDD), is a feature that adds onto the publish process between environments Episerver DXP.

The idea behind Smooth Deploy is that when it is enabled, a deployment can be done without the website going offline, which can be especially helpful in a production environment.

This is officially supported between the following environments:
Integration → PreProduction
PreProduction → Production

What does it solve?

Currently, code promotions go directly into the environmental slot, which means the changes aren’t seen directly on production. This is great in almost all circumstances, until you have an update to the database, since the database is shared between the slot and the live environment.

Current Live/Slot setup
Current Live/Slot setup

The idea of a slot is so easy to do on the Web App because it is a built in feature by Microsoft, but unfortunately it is not so easy for just about every other Azure feature. Episerver came up with a set of logic within their deployment API called Smooth Deployment that would solve this issue.

When a deployment starts and the slot is created for the web app, the database, and a few other Azure components are also cloned and permissioned.

This creates a 100% segmented environment for testing that can also include any updates/upgrades/changes to the database (or any blocks/pages, etc) without any interference on the live environment.

Differences between Read Only and Read/Write Mode

Within the Smooth Deploy feature, there are two modes that have two different uses. The two modes are known as ReadOnly and ReadWrite.

  • ReadOnly – ReadOnly is the Recommended way to use Smooth Deploy. This simply means that when there is an active clone of the database in the slot, the live environment database is in a state where no data can be altered. This ensures that there is no data loss when a publish is finalized.
  • ReadWrite – ReadWrite mode allows data to be altered on the live environment. This does mean that there is a potential for data loss when the publish is finalized.
Login screen during ReadOnly Mode

Using Smooth Deploy

Episerver has implemented this functionality within their deployment API, which means it is available in a couple different places, which I will show you. Firstly is how to utilize it within the PAAS Portal, and then how to use it within my EpiVisuals Scripts.

PAAS Portal

The easiest way to utilize the Smooth Deploy feature is from within the PAAS Portal. Once you’re authenticated and you’re doing a code promotion (Integration to PreProduction or PreProduction to Production), a modal will prompt for deployment settings. This is where the dropdown will be located for if you want ReadOnly or ReadWrite.

EpiVisuals Deployment Scripts

As seen in my very first post about my deployment scripts, the two main scripts used for code deployments/promotions are DeployToEnvironment.ps1 and PromoteToEnvironment.ps1. They deploy via a nuget package to an environment directly to an environment and promote from one environment to another, respectively.

Both of these scripts have had simply one more parameter added to them in order to use Smooth Deploy. The switch is defined as follows:

[ValidateSet("ReadOnly", "ReadWrite")]

Notice that with the parameter, it does not have to be included in the command, but if it is included, it must be either “ReadOnly” or “ReadWrite”.

Deploy to Environment:

.DeployToEnvironment.ps1 -ClientKey "****"
                          -ClientSecret "****"
                          -ProjectId "****"
                          -ArtifactPath "C:FilePath"
                          -TargetEnvironment "PreProduction"
                          -UseMaintenancePage 0
                          -ZeroDowntimeMode "ReadOnly"

Promote to Environment:

.PromoteToEnvironment.ps1 -ClientKey "****"
                           -ClientSecret "****" 
                           -ProjectID "****"
                           -SourceEnvironment Integration
                           -TargetEnvironment Preproduction
                           -UseMaintenancePage 1
                           -IncludeBlobs $false
                           -IncludeDb 0
                           -SourceApp "cms"
                           -ZeroDowntimeMode "ReadOnly"


Personally, I love this feature, as it does indeed make deployments run a lot smoother, and I’m wishing I had this on previous projects.

On one of the projects that I previously worked on, the client wanted to follow an every two week update cadence, which meant frequent issues with database upgrade conflicts within the slot and the live environment. This would have been an amazing feature for that client.

Official Documentation is located here: https://world.episerver.com/documentation/developer-guides/digital-experience-platform/deploying/deployment-process/smooth-deploy/

Eric Markson
Eric Markson

Technical Architect @ Verndale | Optimizely MVP - Platinum | Optimizely Content Cloud SME - Platinum

Articles: 17


  1. Hi Eric, thanks for this nice article, i have one special question, with this this smooth deploy, are we also able to copy content from one environment to another, lets say from preproduction to production without a downtime somehow (in paas portal)? Or does this zero downtime only apply to the code deploy only?

    Many thanks

    • Hey @Dren,

      In the PAAS Portal you are limited with options for a content only deployment, in terms of using Smooth Deploy. I do not believe you can even deploy the database from Preprod to Prod using the PAAS Portal.

      So to answer your question, if the requirement is to only use the PAAS Portal, it is limited to only code deployments with Smooth Deploy.

      If you use the Deployment API, it may be possible to do content-only deployments, as there is the ability to not deploy code. I haven’t tried out that specific use-case, yet. Let me give it a shot and let you know my results!

      If you use the Deployment API, you still cant do content-only deployments, but you can include Content (Database/Assets) from environment to environment. You have to include code when doing any deployment with Smooth Deploy.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.