Packaging a Sitecore solution for the Microsoft Azure App Service

Current version: 3.0

This topic describes using the Sitecore Azure Toolkit to package a local Sitecore instance into Web Deployment Packages (WDPs) ready for deployment to the Microsoft Azure App Service®. This functionality is only required for packaging customized local Sitecore solutions.

Important

Solutions deployment functionality is backward compatible and SAT 3.0.0 can be used to deploy previous SXP versions on Azure.

You can download WDPs for standard Sitecore solutions from the Sitecore Experience Platform download page.

Note

Sitecore Azure Toolkit does not currently support packaging local xConnect components into roles. Standard WDPs for the roles: Collection, Reference Data, Marketing Automation, Collection Search, and Marketing Automation Reporting are available as part of the packages downloadable from the Sitecore Experience Platform download page.

Prerequisites

Before you start the packaging process, you must have:

A local Sitecore instance that you use as input to the packaging process. The Sitecore Azure Toolkit supports packaging Sitecore instances that are installed with the installation program or from a ZIP file and uses the default folder structure.
The Microsoft Data Tier Application Framework (DAC Fx). This framework is usually installed with Microsoft SQL Server® or Microsoft Visual Studio®. You can also download DAC Fx from the Microsoft Download Center.
The Sitecore Azure Toolkit must be installed according to the instructions described in Getting Started with Sitecore Azure Toolkit.

Packaging transformations

During the process of packaging Sitecore to work correctly on Azure, the Sitecore Azure Toolkit will create one or more WDPs. Each of the WDPs contains the original Sitecore installation, transformed into the structures and configurations required to install a specific Sitecore role on an appropriate resource within Azure. For example, the Content Management role in a 'Small' sized Sitecore Experience platform deployment, hosts exclusively on an Azure Web Apps resource. To ensure it works when deployed on that resource, you must ensure that the configuration uses Azure Cognitive Search as its content search provider. While the WDP for the Content Management role is being packed, instructions for this configuration enablement are provided to the process through a Sitecore Cargo Payload file (SCCPL). Sitecore provides all the required SCCPL files to package a standard Sitecore installation into the various topologies deployable on Azure. These files are within the CargoPayloads folder that is part of the Sitecore Azure Toolkit download. However, to meet custom deployment requirements for a customized installation, you might have to extend, customize, or add to these files.

Invoking the packaging command

To start the packaging process, you import the Sitecore Azure Toolkit PowerShell module and invoke the Start-SitecoreAzurePackaging commandlet.

Note

You must run the following commands in Microsoft Windows PowerShell® in the folder where the Sitecore Azure Toolkit is installed:

RequestResponse

> Import-Module .\tools\Sitecore.Cloud.Cmdlets.psm1
> Import-Module .\tools\Sitecore.Cloud.Cmdlets.dll
> Start-SitecoreAzurePackaging [-sitecorePath] <String> [-destinationFolderPath] <String> [-cargoPayloadFolderPath] <String> [-commonConfigPath] <String> [-skuConfigPath] <String> [-parameterXmlPath] <String> [[-fileVersion] <String>]

The Start-SitecoreAzurePackaging commandlet has the following parameters:

Parameter	Description
`sitecorePath`	The path to either a Sitecore instance website folder of the Sitecore installation to be packaged or a packaged Sitecore instance folder in a zip file. An example of a path to a website folder: `C:\inetpub\wwwroot\sampleWebSite\Website`
`destinationFolderPath`	The folder where the generated packages are to be stored. An example of a path to store the generated packages: `C:\Sitecore\WDPs`
`cargoPayloadFolderPath`	The path to the folder containing the Sitecore version-specific role and feature transformation files. An example of the path for the Sitecore version specific role and feature transformation files: `SitecoreAzureToolkitResourcesFolder\resources\CargoPayloads`
`commonConfigPath`	The path to the file that contains a list of the transformations files to be applied to all of the roles. An example of the path for the file containing all the generic transformations required for Sitecore: `SitecoreAzureToolkitResourcesFolder\resources\Configs\common.packaging.config.json`
`skuConfigPath`	The path to the file that contains the lists of role-specific transformations for the selected Sitecore version and the Sitecore configuration on the Microsoft App Service. Examples of the paths to the files that contain the role-specific transformations: For XM small to extra-large configurations, `SitecoreAzureToolkitResourcesFolder\resources\Configs\XM.packaging.config.json` For XP small to extra-large configurations, `SitecoreAzureToolkitResourcesFolder\resources\Configs\XP.packaging.config.json` For XP single configurations, `SitecoreAzureToolkitResourcesFolder\resources\Configs\XPSingle.packaging.config.json`
`archiveAndParameterXmlPath`	The path to the WebDeploy Sitecore version-specific archive manifest and parameter declaration files. `SitecoreAzureToolkitResourcesFolder\resources\MsDeployXMls`
`fileVersion`	An optional parameter that allows you to embed a version marker in the generated WebDeploy packages. The marker is stored in the `Version.txt` file inside the generated packages.
`integratedSecurity`	The default value is `false` - This means that the user ID and password from the connection strings in the `<Website name>\App_Config\ConnectionStrings.config` file will be used. If the value is set to `true` - The credentials of the current Windows account are used for authentication, (the user must have admin rights to access the SQL server). It resolves security limitation issues while you are packaging a Sitecore instance.

Important

The SQL server accounts that you use to access the Sitecore databases are overwritten when you deploy a Sitecore instance using Web Deploy packages.

When invoked, the Start-SitecoreAzurePackaging commandlet produces a number of WebDeploy packages in the destination folder. All packages follow the same name pattern, which includes the role name, for example, Sitecore version rev. 171002_cm.scwdp.zip.

Note

Sometimes the commandlet also generates an intermediate WDP package with no role-specific suffix in its name. You can ignore this package during deployment.

A packaging example

The following code sample shows how to use the Start-SitecoreAzurePackaging commandlet to prepare WDP packages for an XP configuration. The sample assumes the following:

Sitecore is installed locally in C:\inetpub\example, and the website folder is C:\inetpub\example\Website.
Sitecore Azure Toolkit is installed in C:\Tools\SitecoreAzureToolkit.
Generated packages are stored in C:\Workspace\WDPs.

The package(s) created by the commandlet are dependent on the Sitecore configuration requested during packaging. Typically, there is one WDP per role so, for example, an XM topology would have one WDP produced for the Content Management role and another one for the Content Delivery role.

Do you have some feedback for us?

If you have suggestions for improving this article,