Deploy a new Sitecore environment to the Azure App Service

Last updated Friday, September 8, 2017 in Sitecore Azure Toolkit for Administrator, Developer
Keywords: Azure, Cloud

With the Sitecore Azure Toolkit, you can deploy a new Sitecore environment to the Microsoft Azure App Service®.

This topic describes how to:

Plan your environment

The Sitecore Azure Toolkit supports the following four Sitecore configurations by default, to suit different needs:




The Sitecore Experience Platform, running as a single WebApp instance. Use this configuration for development and testing. For security and scalability reasons, it is best practice to use the XM1 or XP1 configuration in production environments.


The Sitecore Experience Management configuration running both the Content Delivery and Content Management roles. Use this environment when you are not planning to use the Analytics and Marketing features of the Sitecore Experience Platform (that is, in CMS-only mode).


The Sitecore Experience Platform configuration running four roles: Content Delivery, Content Management, Processing, and Reporting. Use this environment when you are planning a fully featured Sitecore Experience Platform installation.


The Sitecore Experience Database configuration running both the Processing and Reporting roles. Use this environment in combination with an on-premise Sitecore XM installation to provide the Experience Database features.

Prepare WebDeploy packages

The Azure Resource Manager (ARM) requires that WebDeploy packages (WDPs) containing the application code and resources are available for download over the Internet. One option to host WDPs is to create a Microsoft Azure® storage account.

To prepare the WDPs:

  1. Ensure you have access to a Microsoft Azure subscription to deploy a Sitecore environment.
  2. Create a Microsoft Azure storage account.
  3. Go to the Sitecore Experience Platform Download page and download the prebuilt WDPs.
  4. Use Azure Storage Explorer to connect to a Microsoft Azure storage account and upload Sitecore WDPs for your configuration. Ensure you use a blob type storage container.


    WDPs have the extension and contain the role name as part of the file name, for example, Sitecore 8.2 rev.

  5. In Azure Storage Explorer, copy the URLs for your WDPs.
  6. In Azure Storage Explorer, create a Shared Access Signature (SAS) token for the storage container, and then append the token to the WDP URLs. Make a note of the package URLs for later use in ARM templates.

Obtain MongoDB connection strings

To obtain the necessary connection strings when deploying XP0 and XP1 configurations, go to your MongoDB vendor.

When deploying Sitecore XP configurations, you must provide connection strings for the analytics database and for three tracking databases. You can choose to host MongoDB with a PaaS service such as MongoDB Atlas or mLab, or you can self-host on MongoDB using Azure Virtual Machines. When the MongoDB cluster is ready, note the connection strings for the databases as you will use them later in ARM templates.


If the MongoDB driver attempts to reuse connection strings that Azure has already closed, this may cause connection issues. To avoid this, set the maxIdleTimeMS parameter to 60000 for all MongoDB connection strings, for example: 

<add name="analytics" connectionString="mongodb://user:password@host/analytics?replicaSet=rs1&ssl=true&maxIdleTimeMS=60000" />

Download and configure an environment template

To download and configure the environment template for your selected Sitecore configuration:

  1. Go to the Github repository for your selected Sitecore configuration.
  2. Locate the environment template (azuredeploy.json) and download the corresponding parameters file (azuredeploy.parameters.json). Make a note of the URL of azuredeploy.json.

    Alternatively, you can download the azuredeploy.json template and related templates in addons and nested subfolders and upload to your Azure storage account.

  3. Open the azuredeploy.parameters.json file in the editor and fill in the following parameters

    Parameter name



    Value restrictions



    The unique ID of the deployment. This value prepends the names of all resources.

    It must contain only alphanumeric characters and hyphens. The maximum length is 60 characters.

    cmMsDeployPackageUrl cdMsDeployPackageUrl

    XM and XP

    Links to the WDPs for the roles.

    The URLs must be accessible from Microsoft Azure data centers. Use SAS tokens, or an equivalent, to provide secure access to the resources.

    prcMsDeployPackageUrl repMsDeployPackageUrl

    XP and XDB only

    Links to the WDPs for the roles.

    The URLs must be accessible from Microsoft Azure data centers. Use SAS tokens or an equivalent to provide secure access to the resources.


    XP0 only

    Links to the WDPs for the roles.

    The URLs must be accessible from Microsoft Azure data centers. Use SAS tokens or an equivalent to provide secure access to the resources.



    The password for thesitecore\admin user when Sitecore is deployed.

    The minimum length is 8 characters.



    The name of the administrator user for the virtual SQL Server for core, master, web, and reporting SQL Azure databases.




    The password for the administrator user for the virtual SQL Server for core, master, web, and reporting SQL Azure databases.

    The minimum length is 8 characters.


    XP and XDB only

    Shared authentication key for XDB Reporting service.

    The minimum length is 32 characters, for example, a GUID.

    analyticsMongoDbConnectionString trackingLiveMongoDbConnectionString trackingHistoryMongoDbConnectionString trackingContactMongoDbConnectionString

    XP0, XP and XDB

    MongoDB connection strings for analytics and tracking databases.




    Optional location for Application Insights telemetry data storage. East US by default.

    The Microsoft Azure Service Availability by Region lists the locations supporting Application Insights.


    XM, XP, XDB

    Optional size of the Sitecore configuration.

    xP1-xP5 for XP, xM1-xM5 for XM and xDB1-xDB5 for XDB.

Add modules

To add modules to your deployment:

  1. Add the modules parameter to your azuredeploy.parameters.json file using the following snippet:
    modules: {
    value: {
      items: [
    /* add module entries here */
  2. Configure the Bootloader module.
  3. Configure WFFM for deployment on the Azure App Service.

Invoke the deployment command

To invoke the PowerShell command and initiate provisioning:

  1. In PowerShell, go to the Azure Toolkit folder and load the Azure Toolkit module: Import-Module .\tools\Sitecore.Cloud.Cmdlets.psm1 -Verbose.
  2. Add an Azure account to your PowerShell session: Add-AzureRMAccount.
  3. If there is access to multiple subscriptions, select the subscription that you want to deploy into: Set-AzureRMContext -SubscriptionName "<name of the subscription>".
  4. Start provisioning using the Start-SitecoreAzureDeployment commandlet:
    Start-SitecoreAzureDeployment [-location] <String> [-Name] <String> [-ArmTemplateUrl] <String> [-ArmParametersPath] <String> [-LicenseXmlPath] <String> [-SetKeyValue] <Hashtable> 

The Start-SitecoreAzureDeployment commandlet accepts the following parameters:




The name of the Azure datacenter where you want the resources deployed.

Refer to the Azure datacenter compatibility table for the list of Microsoft Azure datacenters that the Sitecore Experience Platform supports deployment to.


The name of the resource group for the new environment. It can refer to a new or an existing resource group. This is usually the same as the deployment ID.


The URL of the ARM template file for the environment configuration that you want to deploy.


The path to the populated parameters.json file for the template that you selected.


The path to the Sitecore license file that you want to deploy to the environment.


(Optional) Use this parameter in a script to deploy several environments by using a common set of default parameter values in the azuredeploy.parameters.json file and supplying environment-specific parameter values in the command line.

The value of this parameter is a hashtable that contains a subset of parameters declared in the azuredeploy.parameters.json file.

Any values that you specify in the command line in this parameter override the values specified in the azuredeploy.parameters.json file

For example, to set or override the value in the deploymentId parameter, enter the following:

-SetKeyValue @{ "deploymentId" = "<new value>" }.