Walkthrough: Deploying a new Sitecore environment to the Microsoft Azure App service

Current version: 9.3

Use this walkthrough to set up the right configuration for your solution, prepare the authentication certificate, configure an environment template, deploy a search provider and start provisioning.

This walkthrough describes how to:

Configure Sitecore

To configure Sitecore, you must use the right configuration to suit your Sitecore solution. Sitecore version 9.0 supports the following Sitecore configurations by default:

Configuration

Description

XP Single

This is the Sitecore Experience Platform configuration that runs:

  • The Sitecore Identity Server.

  • Four Sitecore roles: Content DeliveryContent Management, xDB Processing, and xDB Reporting as a single WebApp instance.

  • All XP roles: XConnect SearchXConnect CollectionxDB Reference DataxDB Marketing Automation, xDB Marketing Automation Reporting, Sitecore Cortex™ Processing, and Sitecore Cortex™ Reporting as a single Azure WebApp instance.

Note

There are a number of WebJobs that run under the one XConnect WebApp that hosts all of XP roles. Specifically, the roles are: the Marketing Automation Engine, the XConnect Search Indexer, and the Sitecore Cortex™ Processing Engine

Use this configuration for development and testing. For security and scalability reasons, it is best practice to use the XM or XP configuration in production environments.

XP Scaled

This is the Sitecore Experience Platform configuration that runs:

  • The Sitecore Identity Server.

  • Four Sitecore roles: Content DeliveryContent ManagementxDB Processing, and xDB Reporting. Each roles is run as a separate Azure WebApp.

  • All XP roles: XConnect SearchXConnect CollectionxDB Reference DataxDB Marketing AutomationxDB Marketing Automation Reporting, Sitecore Cortex™ Processing, and Sitecore Cortex™ Reporting. Each role is run on it's own WebApp instance, (unlike XP Single, where all roles are hosted on one WebApp instance).

Each WebJob runs under a specific role. Following are the different roles and the WebJob that they are hosting:

  • xDB Marketing Automation - Hosts the Marketing Automation Engine WebJob.

  • Sitecore Cortex™ Processing - Hosts the Cortex Processing Engine WebJob.

  • XConnect Search - Hosts the XConnect Search Indexer WebJob.

Use this environment when you are planning a fully featured Sitecore Experience Platform installation.

XM Single

This is the Sitecore Experience Management configuration that runs:

  • The Sitecore Identity Server.

  • Both the Content Delivery and Content Management roles as a single WebApp instance.

Use this configuration for development and testing when you are not planning to use the Analytics and Marketing features of the Sitecore Experience Platform (that is, in CMS-only mode).

XM Scaled

This is the Sitecore Experience Management configuration that runs: 

  • The Sitecore Identity Server.

  • 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).

xDB Single

This is the Sitecore Experience Database configuration that runs:

  • Two Sitecore roles: xDB Processing and xDB Reporting as a single WebApp instance.

  • All XP roles: XConnect SearchXConnect CollectionxDB Reference DataxDB Marketing AutomationxDB Marketing Automation Reporting, Sitecore Cortex™ Processing, and Sitecore Cortex™ Reporting as a single WebApp instance.

Note

There are a number of WebJobs that run under the one XConnect WebApp that hosts all of the XP roles. Specifically, the roles are: the Marketing Automation Engine, the XConnect Search Indexer, and the Sitecore Cortex™ Processing Engine.

Use this configuration for development and testing in combination with an on-premise Sitecore XM installation to provide the Experience Database features.

xDB Scaled

This is the Sitecore Experience Database configuration that runs:

  • Two Sitecore roles: xDB Processing, and xDB Reporting. Each roles is as a separate Azure WebApp.

  • All XP roles: XConnect SearchXConnect CollectionxDB Reference DataxDB Marketing AutomationxDB Marketing Automation Reporting, Sitecore Cortex™ Processing, and Sitecore Cortex™ Reporting. Each role is run as a separate WebApp instance, (unlike xDB Single, where all of the roles are hosted on the one WebApp instance).

Each WebJob runs under a specific role. Following are the different roles and the WebJob that they are hosting:

  • xDB Marketing Automation - Hosts the Marketing Automation Engine WebJob.

  • Sitecore Cortex™ Processing - Hosts the Cortex Processing Engine WebJob.

  • XConnect Search - Hosts the XConnect Search Indexer WebJob.

Use this environment in combination with an on-premise Sitecore XM installation to provide the Experience Database features.

When planning your topologies, and sizing as well as the type of environment you want to deploy, consult the Sitecore Azure Toolkit documentation on the Doc site.

Prepare the authentication certificate

To prepare the authentication certificate:

  1. Before starting a Sitecore 9.1 deployment, you must obtain or generate an authentication certificate and store it in PKCS #12 format (.pfx).

    Note

    XConnect requires client authentication certificates with a valid trust chain by default. Due to a limitation, in the Azure App Service, a certificate can only have a valid trust chain if the root certificate for it is issued by a globally trusted Certificate Authority.

  2. If you use a self-signed certificate or a certificate issued by a private Certificate Authority, such as Active Directory Certificate Services, then you must set the allowInvalidClientCertificates parameter to true and extend the azuredeploy.parameters.json file with the following:

    RequestResponse
      "allowInvalidClientCertificates": {
          "value": true
        }

    More details on the parameters file and how to extend it are described in step 4 of the following section.

Download and configure an environment template

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

  1. Go to the GitHub repository and locate the templates for your selected Sitecore configuration and version (for example, folder: Sitecore 9.0, subfolder: xp)

  2. In the appropriate subfolder of your selected configuration and version, identify the azuredeploy.json file. This is the main ARM template that you use during the deployment process. Obtain the raw URL for this file from GitHub by selecting the file, then clicking Raw. The file opens in a new browser window. Copy the URL directly from the address bar and make a note of this for later use.

  3. In the relevant subfolder for your selected configuration and version, identify and download the azuredeploy.parameters.json file. To control the deployment process, the ARM templates use this file to pass parameters.

  4. Save the file locally and fill in the parameters within the file, according to the configuration that is described in the relevant table:

    XP Single

    Parameter

    Description

    location

    The geographical region of the current deployment.

    sqlServerLogin

    The name of the administrator account being created for Azure SQL server.

    sqlServerPassword

    The password for the administrator account being created for Azure SQL server.

    sitecoreAdminPassword

    The password for the administrator account for your instance of XP.

    singleMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore XP Single Web Deployment package (WDP).

    xcSingleMsDeployPackageUrl

    The HTTP(s) URL for an XConnect Single WDP.

    siMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore Identity Server WDP.

    authCertificateBlob

    A Base64-encoded blob of the authentication certificate in PKCS #12 format (.pfx). See the deployment command example in the next section for encoding instructions.

    authCertificatePassword

    The password for the authentication certificate.

    templateLinkAccessToken

    The access token for the nested infrastructure and application templates. For example, Azure Storage Explorer can generate a SAS token for you to access the location where the templates were uploaded.

    XP Scaled

    Parameter

    Description

    location

    The geographical region of the current deployment.

    sqlServerLogin

    The name of the administrator account being created for Azure SQL server.

    sqlServerPassword

    The password for the administrator account being created for Azure SQL server.

    sitecoreAdminPassword

    The password for the administrator account for your instance of XP.

    repAuthenticationApiKey

    A unique value, for example, a GUID, which is used to authenticate when communicating from Content Management role to the Reporting Web App. The minimum length required is 32 characters.

    cmMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore XP Content Management Web Deploy package (WDP).

    cdMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore XP Content Delivery WDP.

    prcMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore XP Processing WDP.

    repMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore XP Reporting WDP.

    exmDdsMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore Dedicated Dispatch server WDP.

    exmCmMsDeployPackageUrl

    The HTTPS(s) URL for a Sitecore XP Content Management EXM patch WDP.

    bootloaderMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore Bootloader WDP.

    xcRefDataMsDeployPackageUrl

    The HTTP(s) URL for an XConnect Reference Data service WDP.

    xcCollectMsDeployPackageUrl

    The HTTP(s) URL for an XConnect Collection service WDP.

    xcSearchMsDeployPackageUrl

    The HTTP(s) URL for an XConnect Collection Search service WDP.

    maOpsMsDeployPackageUrl

    The HTTP(s) URL for a Marketing Automation service WDP.

    maRepMsDeployPackageUrl

    The HTTP(s) URL for a Marketing Automation Reporting service WDP.

    deployExmDds

    Indicates whether the Sitecore XP Dedicated Dispatch server must be installed.

    cortexReportingMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore Cortex™ Reporting service WDP.

    cortexProcessingMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore Cortex™ Processing Engine service WDP:

    siMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore Identity Server WDP.

    authCertificateBlob

    A Base64-encoded blob of the authentication certificate in PKCS #12 format (.pfx). See the deployment command example in the next section for encoding instructions.

    authCertificatePassword

    The password for the authentication certificate.

    templateLinkAccessToken

    The access token for the nested infrastructure and application templates. For example, Azure Storage Explorer can generate a SAS token for you to access the location where the templates were uploaded.

    XM Single

    Parameter

    Description

    location

    The geographical region of the current deployment.

    sqlServerLogin

    The name of the administrator account being created for Azure SQL server.

    sqlServerPassword

    The password for the administrator account being created for Azure SQL server.

    sitecoreAdminPassword

    The password for the administrator account for your instance of XM.

    singleMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore XM Single Web Deploy package (WDP).

    siMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore Identity Server WDP.

    authCertificateBlob

    A Base64-encoded blob of the authentication certificate in PKCS #12 format (.pfx). See the deployment command example in the next section for encoding instructions.

    authCertificatePassword

    The password for the authentication certificate.

    templateLinkAccessToken

    The access token for the nested infrastructure and application templates. For example, Azure Storage Explorer can generate a SAS token for you to access the location where the templates were uploaded.

    XM Scaled

    Parameter

    Description

    location

    The geographical region of the current deployment.

    sqlServerLogin

    The name of the administrator account being created for Azure SQL server.

    sqlServerPassword

    The password for the administrator account being created for Azure SQL server.

    sitecoreAdminPassword

    The password for the administrator account for your instance of XM.

    cmMsDeployPackageUrl

    The HTTP(s) URL to a Sitecore XM Content Management deployment package (WDP).

    cdMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore XM Content Delivery WDP.

    siMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore Identity Server WDP.

    authCertificateBlob

    A Base64-encoded blob of the authentication certificate in PKCS #12 format (.pfx). See the deployment command example in the next section for encoding instructions.

    authCertificatePassword

    The password for the authentication certificate.

    templateLinkAccessToken

    The access token for the nested infrastructure and application templates. For example, Azure Storage Explorer can generate a SAS token for you to access the location where the templates were uploaded.

    xDB Single

    Parameter

    Description

    location

    The geographical region of the current deployment.

    sqlServerLogin

    The name of the administrator account being created for Azure SQL server.

    sqlServerPassword

    The password for the administrator account being created for Azure SQL server.

    sitecoreAdminPassword

    The password for the administrator account for Azure SQL server.

    singleMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore xDB Single Web Deployment package (WDP).

    xcSingleMsDeployPackageUrl

    The HTTP(s) URL for an XConnect Single WDP.

    authCertificateBlob

    A Base64-encoded blob of the authentication certificate in PKCS #12 format (.pfx). See the deployment command example in the next section for encoding instructions.

    authCertificatePassword

    The password for the authentication certificate.

    templateLinkAccessToken

    The access token for the nested infrastructure and application templates. For example, Azure Storage Explorer can generate a SAS token for you to access the location where the templates were uploaded.

    xDB Scaled

    Parameter

    Description

    location

    The geographical region of the current deployment.

    sqlServerLogin

    The name of the administrator account being created for Azure SQL server.

    sqlServerPassword

    The password for the administrator account being created for Azure SQL server.

    sitecoreAdminPassword

    The password for the administrator account for Azure SQL server.

    repAuthenticationApiKey

    A unique value, for example, a GUID, which is used to authenticate when communicating from Content Management role to the Reporting Web App. The minimum length required is 32 characters.

    prcMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore xDB Processing Web Deploy Package.

    repMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore xDB Reporting WDP.

    xcRefDataMsDeployPackageUrl

    The HTTP(s) URL for an XConnect Reference Data service WDP.

    xcCollectMsDeployPackageUrl

    The HTTP(s) URL for an XConnect Collection service WDP.

    xcSearchMsDeployPackageUrl

    The HTTP(s) URL for an XConnect Collection Search service WDP.

    maOpsMsDeployPackageUrl

    The HTTP(s) URL for a Marketing Automation service WDP.

    maRepMsDeployPackageUrl

    The HTTP(s) URL for a Marketing Automation Reporting service WDP.

    cortexReportingMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore Cortex™ Reporting service WDP.

    cortexProcessingMsDeployPackageUrl

    The HTTP(s) URL for a Sitecore Cortex™ Processing service WDP.

    authCertificateBlob

    A Base64-encoded blob of the authentication certificate in PKCS #12 format (.pfx). See the deployment command example in the next section for encoding instructions.

    authCertificatePassword

    The password for the authentication certificate.

    templateLinkAccessToken

    The access token for the nested infrastructure and application templates. For example, Azure Storage Explorer can generate a SAS token for you to access the location where the templates were uploaded.

  5. Optionally, you can also append additional parameters to the azuredeploy.parameters.json file by extending it with any parameter declared in azuredeploy.json. The README.md file in the root folder for each Sitecore environment configuration gives additional information.

    Note

    The azuredeploy.parameters.json file includes the siMsDeployPackageUrl, however you must download the Sitecore Identity package separately as it is not included by default.

  6. You can override the default “Extra Small” value of the sitecoreSKU parameter for any scaled topology (XP, XM, xDB), and change it to "Small", "Medium", "Large" and "Extra Large". For example, to change it to Medium, use the following:

    RequestResponse
     "sitecoreSKU": {
          "value": "Medium"
        }

Deploy with Solr as a search provider

Azure Cognitive Search is the default provider for Azure deployments. From version 9.0.2 and later you can choose to use Solr as an alternative to Azure Cognitive Search. The Solr server is not provisioned by an ARM template, therefore after deploying to Azure, you must manually create a template and populate it with with Solr cores. To use the Solr server when the Azure Cognitive Search resource is not being provisioned, pass the parameters in the following tables:

XM Scaled and XM Single

Parameter

Description

solrConnectionString

The connection string to the existing Solr server that passes to the Sitecore Platform roles.

XP Scaled

Parameter

Description

solrConnectionString

The connection string to the existing Solr server that will passes to the Sitecore Platform roles.

xcSearchMsDeployPackageUrl

A blob storage (HTTPS) URL to the Solr XConnect Search web deploy package.

xcSolrConnectionString

(Optional) The connection string to your existing Solr server that passes to the XConnect roles. If you do not specify the parameter, the default value will equal: solrConnectionString.

XP Single

Parameter

Description

solrConnectionString

The connection string to an existing Solr server that passes to the Sitecore Platform roles.

xcSolrConnectionString

(Optional) The connection string to your existing Solr server that passes to the XConnect roles. If you do not specify the parameter, the default value will equal: solrConnectionString.

xcSingleMsDeployPackageUrl

The HTTP(s) URL to a Solr XConnect Single web deploy package.

xDB Scaled

Parameter

Description

xcsolrConnectionString

The connection string to the existing Solr server that passes to the XConnect roles. If you do not specify the parameter, the default value is: solrConnectionString.

xcSearchMsDeployPackageUrl

A HTTPS URL to the Solr XConnect Search web deploy package. 

xDB Single

Parameter

Description

xcsolrConnectionString

The connection string to the existing Solr server that passes to the XConnect roles.

xcSingleMsDeployPackageUrl

The HTTP(s) URL to a Solr XConnect Single web deploy package

Invoke the deployment command and start provisioning

To invoke the PowerShell command and initiate provisioning:

  1. In PowerShell, in the Sitecore Azure Toolkit folder, load the Sitecore Azure Toolkit module: Import-Module .\tools\Sitecore.Cloud.Cmdlets.psm1.

  2. Add the following Azure account to your PowerShell session: Add-AzureRMAccount.

  3. If you have access to multiple subscriptions, select the subscription that you want to deploy to: Set-AzureRMContext -SubscriptionName "<name of the subscription>".

  4. Start provisioning by 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:

    Parameter

    Description

    Location

    The name of the Azure datacenter where you want the resources deployed. The Azure datacenter compatibility table lists the Microsoft Azure datacenters that the Sitecore Experience Platform supports deployment to.

    Name

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

    ArmTemplateUrl

    The URL of the ARM template file for the environment configuration that you want to deploy. It points to the HTTP(S) location that is hosting the templates.

    If you are pointing to GitHub, use raw links, for example: https://raw.githubusercontent.com/Sitecore/Sitecore-Azure-Quickstart-Templates/master/Sitecore%209.0.0/xp/azuredeploy.json

    Note

    For nested templates to work, you must deploy them to storage available for the Azure ARM engine.

    ArmParametersPath

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

    LicenseXmlPath

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

    SetKeyValue

    A dictionary of environment-specific parameters that are in addition to the parameters in the azuredeploy.parameters.json file. You can use this to pass the client authentication certificate while encoding it to Base64, as shown in the following full script example. This ensures it meets the parameters requirement.

    Full script example:

    RequestResponse
    $SCSDK="Path to Sitecore Azure Toolkit"
    $SCTemplates="https://raw.githubusercontent.com/Sitecore/Sitecore-Azure-Quickstart-Templates/master/Sitecore%209.0/xp/"
    $DeploymentId = "Deployment ID"
    $LicenseFile = "Path to the Sitecore license.xml file"
    $SubscriptionId = "Microsoft Azure SubscriptionId"
    $Location="Target location of deployment"
    $ParamFile="Path to filled-in azuredeploy.parameters.json file"
    $Parameters = @{
         #set the size of all recommended instance sizes   
         "sitecoreSKU"="Medium";
         #by default this installs azuresearch
         #if you uncomment the following it will use an existing solr connectionstring that
         # you have created instead of using AzureSearch
         #"solrConnectionString"= "https://myinstancesomewhere/solr";
    }
    Import-Module $SCSDK\tools\Sitecore.Cloud.Cmdlets.psm1
    Add-AzureRMAccount
    Set-AzureRMContext -SubscriptionId $SubscriptionId
    Start-SitecoreAzureDeployment -Name $DeploymentId -Location $Location -ArmTemplateUrl "$SCTemplates/azuredeploy.json"  -ArmParametersPath $ParamFile  -LicenseXmlPath $LicenseFile  -SetKeyValue $Parameters
  5. Run the script and wait while the environment fully provisions.

Invoke the deployment command and start provisioning using SAT 2.5

If you use SAT version 2.5, you must follow a slightly different procedure to initiate provisioning:

  1. Import the required module Az.Accounts: Import-Module Az.Accounts.

  2. Connect the following Azure account to your PowerShell session: Connect-AzAccount.

  3. If you have access to multiple subscriptions, select the subscription that you want to deploy to: Set-AzContext -SubscriptionId "id of the subscription".

  4. Start provisioning by using the Start-SitecoreAzureDeployment commandlet:

    Start-SitecoreAzureDeployment [-location] <String> [-Name] <String> [-ArmTemplateUrl] <String> [-ArmParametersPath] <String> [-LicenseXmlPath] <String>; [-SetKeyValue] <Hashtable>

    Full script example:

    RequestResponse
    $SCSDK="Path to Sitecore Azure Toolkit"
    $SCTemplates="https://raw.githubusercontent.com/Sitecore/Sitecore-Azure-Quickstart-Templates/master/Sitecore%209.0/xp/"
    $DeploymentId = "Deployment ID"
    $LicenseFile = "Path to the Sitecore license.xml file"
    $SubscriptionId = "Microsoft Azure SubscriptionId"
    $Location="Target location of deployment"
    $ParamFile="Path to filled-in azuredeploy.parameters.json file"
    $Parameters = @{
         #set the size of all recommended instance sizes   
         "sitecoreSKU"="Medium";
         #by default this installs azuresearch
         #if you uncomment the following it will use an existing solr connectionstring that
         # you have created instead of using AzureSearch
         #"solrConnectionString"= "https://myinstancesomewhere/solr";
    }
    Import-Module $SCSDK\tools\Sitecore.Cloud.Cmdlets.psm1
     Import-Module Az.Accounts
           Connect-AzAccount
           Set-AzContext -SubscriptionId $SubscriptionId
    Start-SitecoreAzureDeployment -Name $DeploymentId -Location $Location -ArmTemplateUrl "$SCTemplates/azuredeploy.json"  -ArmParametersPath $ParamFile  -LicenseXmlPath $LicenseFile  -SetKeyValue $Parameters
  5. Run the script and wait while the environment fully provisions.

Do you have some feedback for us?

If you have suggestions for improving this article,