Using Umbraco CMS with Multiple Environments on Azure App service

Why use multiple environments? Working directly on your production site is a recipe for disaster you may regress issues or create new issues/bug with your production site breaking critical or non-critical functionality. Once you have a broken production site, rolling out a fix could take from minutes to hours or days during which period your site is down.

More and more developers are using CMS based solutions for developing their websites. Umbraco CMS is one of the popular .NET CMS solutions used by many developers. In this blog post I will share with you how to setup multiple environments for a staging and production sites for Umbraco CMS on Azure Web Apps.

What you will learn

  1. Setup local development site
  2. Setup a staging environment
  3. Setup Courier2 deployment module
  4. Deploy from staging to production site

Setup a local development site

You can easily create an Umbraco CMS website using Visual studio or Web Matrix. To create an Umbraco site with Visual Studio, click here .To create an Umbraco site with Web Matrix, click here . Always remember to remove the install folder under your application and never upload it to stage or production sites. For this tutorial, I will be using Web Matrix

Setup a staging environment

Assuming you already have an Umbraco CMS site running on Azure Web Apps. If not you can create one from the marketplace. To learn more, click here.

Before moving ahead , check if your web app’s pricing tier is STANDARD (S1,S2,S3) or above.Deployment slot are supported for STANDARD, PREMIUM tiers only. For more information on pricing tier and features supported per tier, click here.

  • Login to Azure Management portal and go to your Umbraco CMS web app .
  • Click on Settings -> Deployment slots -> Add to create a deployment slot with the name stage .Note that a deployment slot is another web application sharing the same resources as the primary site created above.umb_createslot
  • Add another SQL Azure database , say umbraco-stage-db to your resource group umbracositecms-1 groupumb_addstagedb
  • Update the Connection strings for your stage deployment slot to point to newly created database, umbraco-stage-db. Note that your production site (umbraositecms-1) and staging site ( umbracositecms-1-stage) must point to different databases.umb_addstagedb
  • Click on Get Publish settings for the deployment slot stage . This will download a publish settings file that store all the information required by Visual Studio or Web Matrix to publish your application from local development site to Azure website.umb_getpublishsettings
  • Open your local development site in WebMatrix or Visual Studio . In this tutorial I am using Web Matrix and first you need to import the publish settings file for your staging website umb_webamtrix_import
  • Review changes in the dialog box and deploy your local site to your Azure web app , umbracositecms-1-stage. umb_publishpreview
  • After successfully publishing the Umbraco local site to staging website , browse your staging site and run a few tests to rule out any issues

Setup Courier2 deployment module

Umbraco offers a deployment module, Courier2 . With courier2 module you can push content, stylesheets, development modules and more with a simple right-click from a staging site to production site for a more hassel free deployments and reducing risk of breaking your production site when deploying an update.

Purchase a license for Courier2 for the domain * and your custom domain (say Once you have purchased the license, copy this license in the bin folder.


Download the Courier2 package from here . Log on to your stage site and click on Developer-> Packages -> Install local packageumb_install_package

Upload the courier2 package using the installer .


To configure you need to update courier.config file under Config folder of your web app.

  <!-- Repository connection settings -->
  <!-- For each site, a custom repository must be configured, so Courier knows how to connect and authenticate-->
        <!-- If a custom Umbraco Membership provider is used, specify login & password + set the passwordEncoding to clear:  -->
        <repository name="prod site" alias="stage" type="CourierWebserviceRepositoryProvider" visible="true">
            <!--<login></login> -->
            <!-- <password>user_password</password>-->            
           <!-- <passwordEncoding>Clear</passwordEncoding>-->

Under <repositories>, enter the production site URL and user information. If you are using default Umbraco Membership provider, then add the ID for the Administration user in <user> section . If you are using a custom Umbraco membership provider, use <login>, <password> to Courier2 module know how to connect to the production site. For more details, review the documentation for Courier module.

Similarly, install Courier module on your production site and configure it point to stage website in its respective courier.config file as shown here

  <!-- Repository connection settings -->
  <!-- For each site, a custom repository must be configured, so Courier knows how to connect and authenticate-->
        <!-- If a custom Umbraco Membership provider is used, specify login & password + set the passwordEncoding to clear:  -->
        <repository name="Stage site" alias="stage" type="CourierWebserviceRepositoryProvider" visible="true">

Click on Courier2 tab in Umbraco site dashboard and select locations. You should see the repository name as mentioned in courier.config


Now lets deploy some content from staging site to production site. Go to Content and select an existing page or create a new page. I will select an existing page from my website where I will change the title to “Getting Started –new” and now click on “Save and publish”.


Now select the modified page and right click to view all the options. Click on Courier and to view Deployment dialog . Click on Deploy to initiate deployment


Review the changes and click on Continue.


Deployment log shows if the deployment was successful.


Browse your production site to see if the changes are reflected .


To learn more about how to use Courier , review the documentation .

How to upgrade Umbraco CMS version

Courier will not deploy help with upgrading from one version of Umbraco CMS to another. When upgrading Umbraco CMS version, you must check for incompatibilities with your custom modules or third party modules and the Umbraco Core libraries. As a best practice

  • ALWAYS backup your website and database before doing an upgrade. On Azure Web App, you can set up automatic backups for your websites using the backup feature and restore your site if needed using restore feature. For more details, see How to back up your website and How to restore your website.
  • Check if the third party packages you’re using are compatible with the version you’re upgrading to. On the package’s download page, in the Project compatibility area, click View details to check version-specific compatibilities.

For more details on how to upgrade your web app locally, follow the guidelines as mentioned here.

Once your local development site is upgraded, publish the changes to staging web app. Test your application and if all looks good, use SWAP button to SWAP your staging site to production site. When performing the SWAP operation , you can view the changes that will be impacted in your web app’s configuration. With this SWAP operation, we are swapping the websites and databases. This means, after the SWAP the production site will now point to umbraco-stage-db database and staging site will point to umbraco-prod-db database.


The advantage of swapping both the site and database:

  • Gives you the ability to roll back to the previous version of your website with another SWAP if there are any application issues.
  • For an upgrade you need to deploy files and database from staging site to production site and database. There are many things that can go wrong when deploying files and database. By using SWAP feature of slots , we can reduces downtime during an upgrade and reduce the risk of failures that can occur when deploying changes.
  • Gives you the ability to do A/B testing using Testing in production feature






One thought on “Using Umbraco CMS with Multiple Environments on Azure App service

  1. Great post @Sunitha, thanks!

    One thing to note is that, in general, when you deploy files to your staging site you will omit any files in the ~/app_data/TEMP/ folder as these will be regenerated when the stage site is first started. You should also omit the ~/app_data/umbraco.config file as this, too, we be regenerated.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s