Hide menu Last updated: Oct 26 2016
Area: Episerver CMS Applies to versions: 10 and higher
Other versions:

Deploying to Azure Web Apps

Note: Azure Web Sites was changed to Azure Web Apps.

This topic describes how to set up an Episerver CMS site to run on Azure Web Apps. The example creates an Alloy sample site from the Episerver Visual Studio plug-in (from version 7.7), but you can apply most steps to sites created in other ways. 

Cloud requirements

  • You need a cloud-enabled license from the Episerver License Center.
  • Azure Management Portal requires an account with login details.
  • Content mirroring and workflows are not supported.
  • When you install a database using Microsoft Azure SQL Database, ensure that SQL Database supports each individual product and add-on that you want to use on the site for the site to work properly.
  • Ensure that each deployed application and module is designed for the cloud.

Setting up a cloud website

The following image illustrates a CMS website running in an Azure Web Apps environment with multiple instances. The website instances share the same SQL database and BLOB storage that stores binary file data in the cloud environment. The sites are load-balanced, and a Service Bus manages events between the CMS websites.

Elastic scaling lets you increase or reduce the number of CMS sites from the Azure administration interface.

CMS deployment concept

The following steps create an Episerver CMS website running in an Azure website environment.

1. Creating a site

  1. In Visual Studio, create a new project by selecting New > Project, and then EPiServer Web site.
  2. Select Alloy templates (either MVC or Web Forms).
  3. Uncheck Add EPiServer Search; to use search functionality when you run in Azure, see Search in Azure.
  4. Install the NuGet package EPiServer.Azure to the project.
  5. Add the cloud license to the website, which is used and activated later when you deploy the website to Azure.

    Note: To add the cloud license, you need to install the Episerver Visual Studio plug-in, and make sure you are using at least CMS version 7.7. You can install this plug-in via Extension Manager in Visual Studio.

2. Creating Azure resources

Log in to the Azure management portal and follow these steps to create a website:

  1. Create an Azure website.
    1. In the Azure management portal, select NEW in the bottom left corner, and select WEB SITE > CUSTOM CREATE.
    2. Enter a URL for your website.
    3. Choose the option to create a new SQL database.
    4. In database settings, select an existing server or create a new one, and provide a login user and password.
  2. Create Azure BLOB storage.

    When you run on Azure, you should store the media (such as images) in Azure BLOB storage to enable scaling.

    1. In the Azure Management portal, select NEW in the bottom left corner, and select DATA SERVICES > STORAGE > QUICK CREATE.
    2. Enter a URL for the storage and chose the option to create the storage account. The storage container name must be in lowercase, such as mysitemedia, for DNS compatibility.

      Tip: Create two BLOB storage accounts: one for development and one for production, and switch between them using just the connection string.

  3. Create a service bus.

    To scale the site to run on several instances, set up a Service Bus in Azure to handle messages among the site instances.

    1. In the Azure Management portal, select SERVICE BUS in the left menu.
    2. 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.

      Tip: Create two Service Bus accounts: one for development and one for production, and switch between them using just the connection string.

3. Updating the configuration

  1. Map 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.

  2. Update connection strings.
    1. In web.config, change the connection string for EPiServerDB to the connection string from Azure Management portal. Remember to keep the setting MultipleActiveResultSets=true.
    2. 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>"
      • <name> is what was given in section Create Azure BLOB storage.
      • <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.
    3. Add a connection string named EPiServerAzureEvents (matching the setting in episerver.framework for the provider). You can find the connection string to Service Bus in the Azure Management portal under SERVICE BUS, if you select the name that was given in Create a service bus and select CONNECTION INFORMATION in the bottom menu.
      The following example shows 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 cannot access the database server, configure access permissions through the Azure portal by selecting the SQL database and follow the Manage Allowed IP Addresses instructions.

  3. Update the 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 is not supported in the Azure database. Therefore, you must remove the configuration for Workflow persistence service 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 to Azure

You can upload the site manually using FTP, or integrate your source control system to get the process fully automated. 

Publishing code and database from Visual Studio

The following steps describe the publish functionality available from within Visual Studio 2012 and later. Previous versions of Visual Studio do 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).

Note: Make sure the modules and modulesbin folders are included in the project so they are published. Publishing the database schema should be performed only on the first publish operation.

  1. Right-click on the Visual Studio project and select Publish.  
  2. Click on the Import button to import publishing settings from Azure.
  3. Connection. Should display the imported Azure profile. No changes should be required here. Do not select Precompile under publishing in the settings.
  4. Settings. Enter the remote connection string to SQL Database (under the EPiServerDB-section).
  5. Enable Update database.
  6. Click Configure database updates.
  7. Clear the option [Auto schema update].
  8. 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).
  9. Click Publish to publish both site and database.

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 ([SolutionDir]\packages\EPServer.CMS.Core.7.6.0\tools\EPiServer.Cms.Core.sql). You also can deploy an existing database using the SQL Database Migration Wizard from CodePlex.

Deploying through source control

You can configure Azure Web Apps so that it uses continuous deployment from source code control. It supports Git, GitHub, and TFS. See Publish from source control on the Microsoft Azure portal. When you commit to your source control, Windows Azure gets the latest code from the source control, builds it, and deploys the output to the website. When you work with a local Git repository, you can push your changes to Azure Web Apps instead.

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 happens only if the site does not have any previous content. For cloud deployment, you may want to first publish the project to the cloud environment before starting a local site configured against the cloud database. Then the bootstrap happens in the cloud environment, which is much faster (because the site and database are likely in same datacenter) and also sets the SiteUrl to the cloud url for the created site.

You also can transfer data to an Episerver site running on Azure Web Apps using 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 log in to the site on Azure, create a user with access to the edit/admin view, start the local site while connected to SQL Database, and perform the following steps. You must allow the source IP address to access the Azure database server. You can enable this in the Azure Management Portal on the specific SQL Database server. How to create the first user depends on which identity provider has been configured; membership or AspNet Identity provider.

Membership Identity Provider

  1. Start the site (Debug/F5).
  2. Go to the CMS admin view > Administer Groups (http://site:port/EPiServer/Cms/Admin).
  3. Log in with a local Windows administrator account.
  4. Create the two groups WebAdmins and WebEditors, these are default Episerver groups providing access to the edit/admin user interface.
  5. 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. 

AspNet Identity Provider

  1. Start the site (Debug/F5).
  2. You are redirected to a register page where you can register the first user belonging to the WebAdmins group.
  3. Go to the CMS admin view > Administer Groups (http://site:port/EPiServer/Cms/Admin).
  4. Create another group WebEditors. The WebAdmins and WebEditors are default Episerver groups providing access to the edit/admin user interface.
  5. 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 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 the CMS admin view > Config > Manage Websites, 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

You should use a scalable search solution when you host in Azure. Episerver Find is a hosted service that you connect to and it works the same way as when your site runs on-premises.

If you want to use the built-in Episerver Search when running in Azure Web Apps, install the EPiServer.Search Nuget package on an empty web site, and then deploy the Search Service as a separate Azure Web Apps instance.  You should set the baseUri attribute for the search client configuration on the site using the Search Service to the Azure Web Apps hosting the Search Service. See Installing and deploying Search service for more information.

Note: The Azure website running the search service should not be scaled to run on several instances, because this causes data corruption in the Lucene index. If you need scaling then use Episerver Find instead.

Note: If you add search capability after you have added the content, you need to build the index at http://<MySite>/<MyUIFolder>/Cms/Admin/IndexContent.aspx on the website.

Staged deployment

Azure Web Apps supports deployment slots so you can deploy new code into a staging environment before moving it to production. To make sure deployment slots do not interfer with the production environment, make sure you define the EPiServerDB, EPiServerAzureEvents and EPiServerAzureBlobs connection strings in the Azure portal as "sticky" (session affinity) to each slot. If a deployment slot re-uses the production connection strings, it is treated as a load-balanced server, part of the production environment, including licensing restrictions. See Microsoft documentation for details about using staging with Azure Web Apps.

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

The core parts of Episerver CMS do not use Session State but some functionality does, such as some Visitor Groups criteria. There are two approaches to enabling session state, depending on the sticky session feature (also known as session affinity) provided by Azure Web Apps that makes sure a 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.

Related topics

Comments

Hello,

I struggled quite some time with a cache issue on azure web apps, and I'm not the only one:

http://world.episerver.com/forum/developer-forum/-Episerver-75-CMS/Thread-Container/2017/6/the-configuration-file-has-been-changed-by-another-program/?pageIndex=1

Maybe something to mention in the azure docs. When you have changed config errors, it might have something to do with dynamic cache. See more in referred thread.

Kind regards,

bob