Deploy a new Sitecore environment to Azure App Service

Last updated Thursday, October 12, 2017 in Sitecore Azure Toolkit for Developer, Administrator
Keywords: Azure, Cloud

You use the Sitecore Azure Provisioning Toolkit to deploy a new Sitecore environment to Microsoft Azure App Service®. This topic describes how to:

Plan your environment

Sitecore Azure Toolkit by default supports three Sitecore configurations to suit different needs:




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


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


This is 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.

Prepare WebDeploy packages

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

To prepare WebDeploy packages:

  1. Obtain a Microsoft Azure subscription to deploy a Sitecore environment.
  2. Create a Microsoft Azure storage account using this guide.
  3. Use Azure Storage Explorer to connect to a Microsoft Azure storage account and upload Sitecore WebDeploy packages for the chosen configuration. Ensure you use a blob type storage container.
    • You can download prebuilt WebDeploy packages from the Sitecore Experience Platform Download page.


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

  4. To obtain URLs for your WebDeploy packages, in Azure Storage Explorer, click Copy URL.
  5. Use Azure Storage Explorer to create a Shared Access Signature (SAS) token for the storage container and append the token to the WebDeploy package URLs.
  6. Make a note of the package URLs for later use in ARM templates.

Obtain MongoDB connection strings

When deploying XP configurations, you must provide MongoDB 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 MongoDB using Azure Virtual Machines. When the MongoDB cluster is ready, note the connection strings for the databases for later use 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. In the Github repository, for the selected Sitecore configuration, download the environment template (azuredeploy.json) and the corresponding parameters file (azuredeploy.parameters.json).
  2. Open the azuredeploy.parameters.json file in the editor and fill in the following parameters:

    Parameter name



    Value restrictions



    Unique ID of the deployment. This value is prepended to the names of all resources

    Must contain only alphanumeric characters and hyphens. Maximum length is 60 characters.


    XM1 and XP1

    Links to the WebDeploy packages 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.



    XP1 only



    XP0 only



    Password for ‘sitecore\admin’ user when Sitecore is deployed.

    Minimum length is 8 characters.



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



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

    Minimum length is 8 characters.


    XP1 only

    Shared authentication key for XDB Reporting service.

    Minimum length is 32 characters, for example a GUID.


    XP0 and XP1

    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.

Invoke the deployment command

To invoke the PowerShell command and initiate provisioning:

  1. In PowerShell, navigate 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 to deploy into: Set-AzureRMContext -SubscriptionName "<name of the subscription>".
  4. Start provisioning using the Start-SitecoreAzureDeployment commandlet:
    Start-SitecoreAzureDeployment [-location] <String> [-Name] <String> [-ArmTemplatePath] <String> [-ArmParametersPath] <String> [-LicenseXmlPath] <String> [-SetKeyValue] <Hashtable>

The Sitecore-SitecoreAzureDeployment commandlet accepts the following parameters:




Name of the Azure datacenter where you want the resources deployed.

Refer to the Azure data center compatibility table for the list of Microsoft Azure data centers that Sitecore Experience Platform supports deployment to.


Name of the resource group for the new environment. It can refer to a new or an existing resource group. This should usually be the same as the deployment ID.


Path to the ARM template file for the environment configuration to deploy.


Path to the populated parameters.json file for the selected template.


Path to the Sitecore license file to deploy to the environment.


Content of the Sitecore license file (XML). Set this parameter by passing the path of the license file to the LicenseXmlPath parameter of the Start-SitecoreAzureProvisioning commandlet.


Use this parameter in a script to deploy several environments by using a common set of default parameter values in azuredeploy.parameters.json 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 azuredeploy.parameters.json.

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

By default, the value of this parameter should be an empty hashtable: -SetKeyValue @{}.

For example, to set or override the value in the deploymentId parameter, enter the following: -SetKeyValue @{ "deploymentId" = "<new value>" }.

Send feedback about the documentation to