Area: Optimizely CMS

ARCHIVED This content is retired and no longer maintained. See the latest version here.

Deploying to Azure Web Apps

Note: Azure Web Apps used to be called Azure Web Sites, see Microsoft’s announcement for details.

This document describes how to set up an EPiServer CMS site to run on Azure Web Apps. In this scenario, an Alloy sample site is created from the EPiServer Visual Studio plug-in (at least version 7.7), but most steps can also be applied to sites created in other ways. Refer to Azure Web Apps for more detailed information about Azure.

Requirements and notifications

The following apply when deploying EPiServer CMS websites to Azure:

A specific cloud enabled license is required, refer to the EPiServer License Center to get this.
The Azure Management Portal requires an account with login details.
Content mirroring and workflows are not supported.
When installing a database using Windows Azure SQL Database (SQL Azure), ensure that each individual product and add-on planned to be used on the site also has support for SQL Azure, in order for the site to work properly.
Deploying to cloud-based websites requires that each deployed application and module is designed for cloud.

Cloud website setup

This is an example of a CMS website running on Azure Web Apps environment with multiple instances. The website instances share the same Azure SQL database, and the blob storage in Azure is used for storing of the file binary data. Load balancing is applied, and the Azure Service Bus manages events between the CMS websites. Note that deploying to Azure Web Apps requires that each deployed application and module is designed for cloud.

Using elastic scaling, the number of CMS sites can easily be increased or reduced depending on capacity needs at the time, from the Azure administration interface.

Follow the steps below to create an EPiServer CMS website running in an Azure website environment.

1. Creating a site

In Visual Studio, create a new project by selecting New...Project, and then EPiServer Web site. In the dialog, select Alloy templates (either MVC or Web Forms). Deselect "Add EPiServer Search"; to use search functionality when running in Azure, see section "Search in Azure" below.
Install the NuGet package EPiServer.Azure to the project.
Add the cloud license to the website, this will be used and activated later when deploying the website to Azure.

Note: This requires the EPiServer Visual Studio plug-in to be installed, make sure you are using at least version 7.7. You can install this plug-in via Extension Manager in Visual Studio.

2. Creating Azure resources

Creating an Azure website

In the Azure management portal, select NEW in the bottom left corner, and select WEB SITE -> CUSTOM CREATE.
Provide a URL for your website. Also chose the option to create a new SQL database.
In database settings, either select an existing server or create a new one, and provide a login user and password.

Creating an Azure storage

When running on Azure, the media (for example, images) should be stored in the Azure BLOB storage to enable scaling.

Follow the steps below to create a BLOB storage account:

In the Azure Management portal, select NEW in the bottom left corner, and select DATA SERVICES -> STORAGE -> QUICK CREATE.
Provide a URL for the storage and chose the option to create the storage account. Note that the storage container name must be in lowercase, for instance "mysitemedia", for DNS compatibility.

Note: Create two BLOB storage accounts, one for development and one for production, to make it easy to switch between them using just the connection string.

Creating a Service Bus

To be able to scale the site to run on several instances, we need to set up a Service Bus in Azure to handle messages between the site instances.

Follow the steps below to create a service bus:

In the Azure Management portal, select SERVICE BUS in the left menu.
Select CREATE in the bottom menu, and in the dialog select a namespace name and a region. The type should be MESSAGING and messaging tier STANDARD.

Note: Create two Service Bus accounts, one for development and one for production, to make it easy to switch between them using just the connection string.

3. Updating configuration

In Visual Studio, update the configuration as described below.

Mapping of BLOB and event providers

Open web.config and add the following configuration under the episerver.framework-section to map BLOB and event providers to Azure:

<blob defaultProvider="azureblobs">
  <providers>
    <add name="azureblobs" type="EPiServer.Azure.Blobs.AzureBlobProvider,EPiServer.Azure" 
          connectionStringName="EPiServerAzureBlobs" container="mysitemedia"/>
  </providers>
</blob>
<event defaultProvider="azureevents">
  <providers>
    <add name="azureevents" type="EPiServer.Azure.Events.AzureEventProvider,EPiServer.Azure" 
          connectionStringName="EPiServerAzureEvents" topic="MySiteEvents"/>
  </providers>
</event>

Note: The attribute container for the BLOB provider and topic for event provider should be unique per site, within the same storage or service bus account.

Connection strings

In web.config, change the connection string for EPiServerDB to the connection string from Azure Management portal (see above). Remember to keep the setting MultipleActiveResultSets=true
Add a connection string named EPiServerAzureBlobs (matching the setting in episerver.framework for the provider). The connection string to the BLOB storage should be in the format: connectionString="DefaultEndpointsProtocol=https;AccountName=<name>;AccountKey=<key>", where <name> is what was given in section Create Azure Storage, and <key> can be found in the Azure Management portal under Storage, if you select the name and then select MANAGE ACCESS KEYS in the bottom menu.
Add a connection string named EPiServerAzureEvents (matching the setting in episerver.framework for the provider). The connection string to Service Bus can be found in the Azure Management portal under SERVICE BUS, if you select the name that was given in section Create Service Bus and select CONNECTION INFORMATION in the bottom menu.

Example of database connection strings in web.config, defined for Azure:

<connectionStrings>
    <clear />
    <add name="EPiServerDB" connectionString="Server=tcp:abcdefgh.database.windows.net,1433;Database=mySiteDB;User ID=dbadmin@abcdefgh;Password={password};Trusted_Connection=False;Encrypt=True;Connection Timeout=30;MultipleActiveResultSets=True" providerName="System.Data.SqlClient" />
    <add name="EPiServerAzureBlobs" connectionString="DefaultEndpointsProtocol=https;AccountName=mystorageccount;AccountKey=abcdefghijklmnoabcdefghijklmnoabcdefghijklmno" />
    <add name="EPiServerAzureEvents" connectionString="Endpoint=sb://myservicebus.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=abcdefghijklmnoabcdefghijklmnoabcdefghijklmno=" />
</connectionStrings>

Note: If your client is not allowed to access database server then you need to configure it via azure portal. Browse to azure web protal and select the sql database and follow the manage allowed ip addresses instructions.

Workflows

Note: You can skip this step for sites created using the latest version of the Visual Studio extension where workflows are disabled by default.

The database schema for Workflow 3.5 (the version EPiServer CMS currently uses) is not supported in the Azure database. Therefore the configuration for Workflow persistence service must be removed from web.config, that is the entry with type SqlWorkflowPersistenceService under workflowRuntime/Services.

Removal of workflow persistance configuration in web.config:

<workflowRuntime EnablePerformanceCounters="false">
  <Services>
    <add type="System.Workflow.Runtime.Hosting.DefaultWorkflowSchedulerService, System.Workflow.Runtime, Version=3.0.00000.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" maxSimultaneousWorkflows="5" />
    <add type="System.Workflow.Runtime.Hosting.SharedConnectionWorkflowCommitWorkBatchService, System.Workflow.Runtime, Version=3.0.00000.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
    <strong>REMOVE THIS: <add type="System.Workflow.Runtime.Hosting.SqlWorkflowPersistenceService, System.Workflow.Runtime, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" UnloadOnIdle="true" /></strong> 
  </Services>
</workflowRuntime>

Disable workflows completely by adding the disabled attribute to the workflowSettings element [requires 7.14]

<episerver>
(..)
<workflowSettings disabled="true" />
(..)
</episerver>

4. Deploying

There are many options to deploy code and data to Azure, you can for example upload the site manually using FTP or integrate your source control system to get the process fully automated. In these steps we will describe the publish functionality available from within Visual Studio:

Publishing code and database from Visual Studio

This topic applies to Visual Studio 2012 and later and covers features that are included in the latest Visual Studio Web Publish Update, previous versions does not have the database publishing capabilities described here. This option is also only available when the connectionstrings are defined in web.config (rather than in an external file such as connectionstrings.config).

Right-click on the Visual Studio project and select Publish, click on the Import button to import publishing settings from Azure and then continue to the next step.
The next step, Connection, should display the imported Azure profile. No changes should be required here. Do not select Precompile under publishing in the settings.
The next step, Settings, enter the remote connection string to SQL Azure (under the EPiServerDB-section).
Enable Update database and click Configure database updates and then clear the option [Auto schema update]. Also click Add SQL Script and browse to the EPiServer.CMS.Core NuGet packages (which means [SolutionDir]\packages\EPServer.CMS.Core.7.6.0\tools\EPiServer.Cms.Core.sql).
Click Publish to publish both site and database.

Important: Make sure the modules and modulesbin folders are included in the project to make sure these as published as well. Publishing the database schema as described above should only be performed on the first publish operation.

Note: You can also deploy the database schema using SQL Server Management Studio or the tools available in the Azure Management Portal, the script you should run is available relative to the project as mentioned in the steps above (which means [SolutionDir]\packages\EPServer.CMS.Core.7.6.0\tools\EPiServer.Cms.Core.sql). You can also deploy an existing database using the migration wizard available from Codeplex.

Deploying through source control

It is possible to configure Azure Web Apps so that it uses continuous deployment from source code control. It supports for example Git, GitHub and TFS. Refer to Publish from source control on Azure for a full description. Basically, it works in the way that when you do a commit to your source control, Windows Azure will get the latest code from the source control, build it and deploy the output to the website. When working with a local Git repository you can instead push your changes to Azure Web Apps.

Deploying content

From version 7.7 of CMS there is a bootstrap feature for content. It works so that if there is an export package located at "[SolutionDir]\App_Data\DefaultSiteContent.episerverdata" then during initialization that package is imported and a site is created. The bootstrap will only happen if the site does not have any previous content. For cloud deployment this means that it can be a good idea to first publish the project to the cloud environment before starting a local site configured against the cloud database. Then the bootstrap will happen in the cloud environment which is much faster (the site and database is likely in same datacenter) and also sets the SiteUrl to the cloud url for the created site.

An alternative way to transfer data to an EPiServer site running on Azure Web Apps is to use the the EPiServer CMS Export/Import functionality. Export the start page from your local site and database and import on the site running in Azure before continuing to the next step.

5. Creating an admin/edit user

To be able to login to the site on Azure you need to create a user with access to the edit/admin view, start the local site while connected to SQL Azure and perform the following steps. Note that the source IP address must be allowed to access the Azure database server, you can enable this in the Azure Management Portal on the specific SQL Azure server.

Start the site (using for example Debug/F5).
Go to the EPiServer CMS administrative user interface under Administer Groups. (which means http://site:port/EPiServer/Cms/Admin). Login with a local Windows administrator account.
Create the two groups WebAdmins and WebEditors, these are default EPiServer groups providing access to the edit/admin user interface.
Go to Create User and create a user that is a member of both WebAdmins and WebEditors.

You will need this user later when logging in to the Azure website after deployment.

6. Changing the site URL

Depending on how the site was created (see section Deploying/Deploying content) you might need to update the site definition for the EPiServer CMS website created in the first steps after deployment. If so log in to the website and go to Manage Websites in the CMS Admin view under Config, and change the Site URL to the URL in Azure. This will also map a host name to the correct site in CMS. The URL can be found in the Azure Management portal under WEB SITES when selecting the created website, and selecting dashboard in the top menu. Then the site URL is given in the right column.

Search in Azure

When hosting in Azure the best practice is to use a scalable search solution such as EPiServer Find. Since EPiServer Find is a hosted service that you connect to, it will work the same way as when your site runs on-premise.

If you want to use the built-in EPiServer Search when running in Azure Web Apps the suggestion is to install EPiServer.Search NuGet package on an empty web site (see Installing and Deploying Search Service section) and then deploy the Search Service as a separate Azure Web Apps instance. The baseUri attribute for the search client configuration on the site using the Search Service should be set to the Azure Web Apps hosting the Search Service.

Note: that the Azure website running the search service should not be scaled to run on several instances, since this will cause data corruption in the Lucene index. If scaling is needed then use EPiServer Find instead.

Note that if you add search capability after you have added the content, you need to trigger a build of the index. Go to the following URL on the website: http://<MySite>/<MyUIFolder>/Cms/Admin/IndexContent.aspx.

Staged deployment

Azure Web Apps supports deployment slots to make it possible to deploy new code into a staging environment before moving it to production. To make sure deployment slots does not interfer with the production environment make sure the connection strings EPiServerDB, EPiServerAzureEvents and EPiServerAzureBlobs are defined in the Azure portal as sticky to each slot. If a deployment slot re-uses the production connection strings it will be treated as a load balanced server part of the production environment, including licensing restrictions. Refer to Microsoft documentation for details on using staging with Azure Web Apps.

Defining EPiServerDB as a connection string in the Azure Portal will require at least EPiServer.CMS.Core 8.3.0, and you must enable this feature by also adding an app setting in the portal episerver:ReadOnlyConfigurationAPI with the value set to "true".

Session State

The core parts of EPiServer CMS do not use Session State but some functionality does, such as some of the Visitor Groups criteria. There are two approaces to enabling session state, either depend on the sticky session feature (also known as session affinity) provided by Azure Web Apps that makes sure user is reaching the same server combined with the default in-memory session state provider. Another approach to enable better scaling is using an optimized provider for Azure, such as the session provider for Azure Web Apps.