Packaging a Sitecore solution for the Microsoft Azure App Service

Last updated Thursday, November 16, 2017 in Sitecore Azure Toolkit for Content Author
Keywords: Azure, Cloud

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. 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 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 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:

> Import-Module .\tools\Sitecore.Cloud.Cmdlets.psm1
> 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

Example

sitecorePath

The path to either a Sitecore instance 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

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 9.0 specific role and feature transformation files:

SitecoreAzureToolkitFolder\resources\9.0.0\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 9.0:

SitecoreAzureToolkitFolder\resources\9.0.0\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 Sitecore 9.0:

For XM small to extra-large configurations,

SitecoreAzureToolkitFolder\resources\9.0.0\Configs\ XM.packaging.config.json

For XP small to extra-large configurations,

SitecoreAzureToolkitFolder\resources\9.0.0\Configs\ XP.packaging.config.json

For XP single configurations,

SitecoreAzureToolkitFolder\resources\9.0.0\Configs\ XPSingle.packaging.config.json

parameterXmlPath

The path to the WebDeploy Sitecore version-specific archive manifest and parameter declaration files.

An example of the paths to the WebDeploy Sitecore version and role-specific archive manifest and parameter declaration files for Sitecore 9.0:

SitecoreAzureToolkitFolder\resources\9.0.0\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.

Example of a version marker:

9.0.0

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 9.0 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.

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.
    $SAT="C:\Tools\SitecoreAzureToolkit"
    # Import commandlets
    Import-Module "$SAT\tools\Sitecore.Cloud.Cmdlets.psm1"
    # Set the parameter variables
    $SKU="XM"
    $Version="9.0.0"
    $Resources="$SAT\resources\$Version"
    $Website="C:\inetpub\example\Website"
    $Output="C:\Workspace\WDPs"
    # Create the output folder
    mkdir $Output
    # Start the packaging process
    Start-SitecoreAzurePackaging `
        -sitecorePath "$Website" `
        -destinationFolderPath $Output `
        -cargoPayloadFolderPath "$Resources\cargopayloads" `
        -commonConfigPath "$Resources\configs\common.packaging.config.json" `
        -skuConfigPath "$Resources\configs\$SKU.packaging.config.json" `
        -parameterXmlPath "$Resources\msdeployxmls" `
        -fileVersion 1.0

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.

Send feedback about the documentation to docsite@sitecore.net.