Getting started with the Sitecore Azure Toolkit

Current version: 2.6

The Sitecore Azure Toolkit contains the tools and resources that are necessary to prepare and deploy Sitecore solutions to the Microsoft Azure App Service®. Azure is a cloud-computing platform that provides a rich variety of services to help you create and run scalable applications without high upfront infrastructure investments.

The Sitecore Azure Toolkit simplifies the task of preparing and deploying a Sitecore solution with:

  • PowerShell commandlets to package a Sitecore instance into role-specific packages.

  • Out-of-the-box integration with Microsoft Azure services: Microsoft Azure SQL®, Microsoft Azure Redis Cache, Microsoft Application Insights®, Microsoft Azure Cognitive Search®

  • Prebuilt ARM templates for frequently used topologies: XM, XP, XPSingle.

  • Configuration tweaks to run Sitecore on the Azure App Service.

  • Security features: HTTPS, low-privileged SQL access, secure Sitecore password.

Deploying Sitecore onto Azure with the Sitecore Azure Toolkit

The following is a high-level overview of the process that takes place when you use the Sitecore Azure Toolkit (SAT) to deploy Sitecore to Azure:

  • First, you can download or create Web Deploy packages (WDPs) with the Sitecore Azure Toolkit. WDPs contain the application code and resources required to deploy Sitecore as well as any associated modules (if required). During the packaging process, the content of the WDPs are transformed to ensure correct operation when they are deployed to Azure. These transformations are defined via Sitecore Cargo Payload (SCCPL) packages which SAT references during the packaging process.

  • After obtaining the packages, you prepare the Azure Resource Manager templates (ARM templates). These templates instruct the Azure Resource Manager to deploy resources to Azure, this includes both infrastructure (such as Web Apps) and application (WDPs). Sitecore provides default templates, to prepare them means choosing the right templates and providing the right parameters to those templates to configure the required deployment correctly.

  • When you have prepared the WDPs and templates, you can deploy all of the required infrastructure and Sitecore applications onto Azure with a single command from SAT.

Prerequisites

To use the Sitecore Azure Toolkit, ensure you have the following:

  • .NET Framework 4.8

  • PowerShell 5.1 or later

  • Microsoft Azure PowerShell® 2.0.1 or later. To check your installed version, open PowerShell and run the following command:

    RequestResponse
    Get-InstalledModule -Name AZ -AllVersions

    To install Microsoft Azure PowerShell®, follow the instructions on the Install Azure PowerShell page.

    Note

    If you already have the AzureRM module installed, you should uninstall this before installing the AZ module.

  • Microsoft SQL Server Data-Tier Application Framework (DacFX) for SQL server 2012 or later.

    Note

    You usually install this framework with Microsoft SQL Server® or Microsoft Visual Studio®. You can also download DAC Fx from the Microsoft Download Center. DacFX is also installed with Microsoft Web Deploy 3.6 using the Web Platform Installer. In some software configurations Sitecore Azure Toolkit might not be able to load a proper version of DacFx automatically.

  • An Azure subscription for deployments. You can sign up for a free trial account on the Microsoft Azure website.

  • Cloud-hosted storage for Sitecore WebDeploy packages. An Azure Storage account can be used for this purpose.

Downloading the Sitecore Azure Toolkit

You can download the Sitecore Azure Toolkit from dev.sitecore.net, where you can also find the tools and resources necessary to package and deploy Sitecore solutions to the Azure App Service.

Note

When you download the Sitecore Azure Toolkit, the zip file is marked as blocked by Microsoft Windows therefore you must unblock the zip file. In Windows Explorer, right-click the file and click Properties. Then in the Properties dialog, on the General tab, click Unblock.

The following resources are distributed separately:

  • Prebuilt WebDeploy packages for Sitecore roles in different environments on the Sitecore Experience Platform download page.

  • Azure Resource Manager (ARM) provisioning templates and related parameter files on Github.

Installing the Sitecore Azure Toolkit

Sitecore Azure Toolkit is a ZIP package that you can unpack into a folder of the hard drive. When unpacked, Sitecore Azure Toolkit package creates the following files and folders:

  • Tools folder – Microsoft PowerShell commandlets and the necessary supplementary libraries.

    • Sitecore.Cloud.Cmdlets.psm1 and Sitecore.Cloud.Cmdlets.dll– the main modules containing the necessary commandlets.

  • Resources/9.0.0 – Version-specific resources for Sitecore 9.0.

    • CargoPayloads – role-specific and feature-specific transformation packages. They are also known as Sitecore Cargo Payload packages (SCCPL).

    • MsDeployXmls – parameters files for WebDeploy packages.

    • Configs – configuration files for packaging tasks.

  • Top-level files and a Copyrights folder – README and licensing information.

To load the main module into a PowerShell session, run the following commands in the folder where the toolkit is unpacked:

RequestResponse
Import-Module .\tools\Sitecore.Cloud.Cmdlets.psm1 -Verbose 
Import-Module .\tools\Sitecore.Cloud.Cmdlets.dll -Verbose 

These commands loads commandlets into the PowerShell session. Commandlets provide an interface into the functionality of the Sitecore Azure Toolkit, for example:

  • Start-SitecoreAzurePackaging – packages a Sitecore solution into WDP(s) so they are ready for deployment.

  • Start-SitecoreAzureModulePackaging – packages a Sitecore module into WDP(s) so they are ready for deployment.

  • Start-SitecoreAzureDeployment – initiates a Sitecore deployment onto Azure that includes all of the required resource infrastructure.

Azure Resource Manager templates

ARM templates are located on Github and provide a description of Sitecore environments hosted on Microsoft Azure App Service. The templates include definitions of the following resources:

  • Hosting plans for Sitecore instances.

  • Microsoft Azure SQL databases for content and reporting.

  • Redis Cache service for session state.

  • Microsoft Application Insights® for diagnostics.

  • Microsoft Azure Cognitive Search for content search and contact segmentation index.

The templates are compatible with the WebDeploy packages available on dev.sitecore.net for the corresponding Sitecore version or those that are produced by the Sitecore Azure Toolkit. The structure and organization of the templates are nested. The main template references an infrastructure template and an application template. The deployment responsibilities are then split respectively between templates to setup resources and templates to install the Sitecore application.

Web Deployment Packages

Prebuilt WDPs are located on the Sitecore Experience Platform download page. The WDP(s) come in a single .zip file and are grouped per version and per topology.  After downloading the WDPs you must extract them from the .zip file before the Sitecore Azure Toolkit can use them.

Each role of the topology sizes intended for production use is contained within its own WDP. This means, for example that there will be a WDP for the Content Delivery role, a WDP for the Content Management role, and so on. The only exception to this is for single topologies that are designed for development and testing purposes. For these topologies you can combine multiple roles into a single WDP for deployment on a single shared resource.

Sitecore creates WDPs from standard Sitecore deployment packages that have been modified to run on Azure during the packaging process. Use these WDPs for a standard original deployment of Sitecore.

Note

With appropriate configuration changes, the Sitecore Azure Toolkit also enables users to package their own custom Sitecore deployments into WDPs so they can run on Azure. Further details on how this process works are available within the packaging topics.

Using the Sitecore Azure Toolkit

Do you have some feedback for us?

If you have suggestions for improving this article,