Five New Optimizely Certifications are Here! Validate your expertise and advance your career with our latest certification exams. Click here to find out more

AI OnAI Off
Area: Optimizely CMS
Applies to versions: 10-11
Other versions:
ARCHIVED This content is retired and no longer maintained. See the version selector for other versions of this topic.

Deploying to Windows servers

This topic describes how to deploy Episerver sites through Visual Studio.

You can install Episerver through XCOPY deployment by copying application files. An XCOPY-style file transfer simplifies deployment and maintenance of Episerver sites because no registry entries are created, and no shared components are registered.

The XCOPY architecture in Episerver CMS has no machine- or site-specific information stored in configuration files, so you can use a shared folder for multiple servers. When you develop in a shared environment with source control, you can keep configuration files checked-in and still create a site that you can duplicate in a multi-site deployment.

You can have one single IIS application with multiple sites, or multiple IIS applications pointing to the same physical directory. The machine to which you install additional sites does not need to have Episerver installed.

Deploying a site

The following procedure shows how to deploy an Episerver site from development to production. You can automate this using MSDeploy or other tools.

You need three artifacts to bring over to the production server:

  • Site (the Episerver platform and templates with dependencies and modules). These are normally the root of a Visual Studio project.
  • SQL Server database (stored content and so on).
  • Application Data (media BLOBs, search index). These are files normally stored in App_Data for a Visual Studio project. (Versions prior to CMS 7.6 store these files by default in parallel with the Visual Studio project.)

Note: The following steps assume you have an existing site and good knowledge of using Visual Studio, Internet Information Services Manager and SQL Server Management Studio.

1. Creating the deployment artifacts

Create the deployment artifacts on the development machine to publish a package that can be installed on the target server.

  1. Open a Visual Studio project for the site you are deploying.
  2. Establish NuGet dependencies for the Episerver products used. (This is done by default for CMS 7.6 and later.)
  3. Include all files in modules, modulesbin and App_Data folders in the project. (You also can copy those folders manually to the output folder.)
  4. If Episerver Search is installed, include the IndexingService folder into the project.
  5. Right-click the project in Visual Studio and click Publish. Specify a publish destination of type FileSystem.
  6. Under Settings, make sure Exclude files from the App_Data folder is not checked to restore those files on the destination. (Do not select Precompile during publishing because it disables required functionality such as Virtual Path Providers.)
  7. Publish the project.

    Note: If the database files are not stored in App_Data, see Back Up and Restore of SQL Server Databases on MSDN for details about moving databases.

2. Deploying the artifacts on the target server

Note: The following steps are performed on the target server and assumes you have moved the artifacts created in the previous section to the new server. The web server should have IIS and ASP.NET installed. You also need SQL Server Management Studio to connect to the database server. To use Episerver Search, you also need the Windows feature HTTP Activation (Roles and Features > .NET Framework 4/4.5 Features > WCF Services) installed on the web servers.

  1. Attach the database. See Attach a database on MSDN.

    To complete this step, move the database files from the App_Data folder to the designated data folder for Microsoft SQL Server.

    You can also use backup/restore to attach a database. See Back up and restore of SQL server databases on MSDN.

  2. Create a new SQL Login:
    1. Right-click on the Security node and select New > SQL Login.
    2. Select SQL Server Authentication.
    3. Unselect User must change password at next login.
    4. Under User Mapping, select the new database and make sure the user is member of the db_owner group.
  3. On the web server, create a new folder for your site (for example c:\inetpub\Site1), and copy the contents of the deployed site.
  4. Set access rights on the App_Data folder so that the group IIS_IUSRS have Change access.
  5. Open Internet Information Services Manager and connect to the web server.
  6. Create a new IIS site:
    1. Right-click the Sites node.
    2. Select Add Website.
    3. Select the wwwroot subfolder as the Physical path for the new site.
  7. Update the EPiServerDB connection string in the configuration file in the site root (such as web.config or connectionStrings.config, depending on setup) with connection details to the new database (server, database, SQL login and password).
    Make sure your db connection string contains MultipleActiveResultsSet=true. It is enabled by default when you install a website from a scratch, but not if you are generating a connection string from the server explorer in Visual Studio.
  8. If Episerver Search is installed, update the episerver.search section to make sure the baseUri refers to the new IIS site.

Note: For security and performance reasons always move media BLOBs to a folder outside the application root (as described in the next section), either on a fileshare or a local folder. Storing BLOBs in the App_Data folder is only designed for development purposes.

3. Adding load-balancing support

This section describes how to enable load-balancing, configure remote events and external storage of BLOBs (files on a file share). The example uses the default provider for events (WCF over UDP) and the default provider for storage of BLOBs.

Note: UDP broadcast is not supported by Azure virtual networks. Use the dedicated Azure Service Bus provider instead or WCF over TCP.

  1. Move the Blob subfolder of the App_Data folder to a shared server, such as the database server, and then share the folder. Give access rights for both the share and the folder to the user running the Application Pool for the site in Windows.
  2. Edit EPiServerFramework.config and add configuration for the file BLOB providers. Make sure the path-attribute is valid: 
    <blob defaultProvider="fileShare">
  <providers>
    <add name="fileShare" path="\\dbserver\blobs" type="EPiServer.Framework.Blobs.FileBlobProvider, EPiServer.Framework" />
  </providers>
</blob>
  3. Clear the browser cache and test the setup by browsing the site. Images on the site should work as before but now are delivered from the shared location.
  4. Enable the default provider for remote events by configuring the endpoints RemoteEventServiceClientEndPoint and RemoteEventServiceEndPoint in web.config. This automatically enables the default provider.
    Code example for CMS 11.1 and higher: 
    <system.serviceModel>
  <serviceHostingEnvironment aspNetCompatibilityEnabled="true" multipleSiteBindingsEnabled="true"/>
  <extensions>
    <bindingElementExtensions>
      <add name="udpTransportCustom" 
           type="Microsoft.ServiceModel.Samples.UdpTransportElement, EPiServer.Framework.AspNet"/>
    </bindingElementExtensions>
  </extensions>
  <services>
    <service name="EPiServer.Events.Remote.EventReplication">
      <endpoint name="RemoteEventServiceEndPoint"
                contract="EPiServer.Events.ServiceModel.IEventReplication"
                binding="customBinding"
                bindingConfiguration="RemoteEventsBinding"
                address="soap.udp://239.255.255.19:5000/RemoteEventService" />
    </service>
  </services>
  <client>
    <endpoint name="RemoteEventServiceClientEndPoint"
              address="soap.udp://239.255.255.19:5000/RemoteEventService"
              binding="customBinding"
              bindingConfiguration="RemoteEventsBinding"
              contract="EPiServer.Events.ServiceModel.IEventReplication" />
  </client>
  <behaviors>
    <serviceBehaviors>
      <behavior name="DebugServiceBehaviour">
        <serviceDebug includeExceptionDetailInFaults="true"/>
      </behavior>
    </serviceBehaviors>
  </behaviors>
  <bindings>
    <customBinding>
      <binding name="RemoteEventsBinding">
        <binaryMessageEncoding />
        <udpTransportCustom multicast="True"/>
      </binding>
    </customBinding>
  </bindings>
</system.serviceModel>
  5. If Episerver Search is installed, you cannot load-balanced the search index. You must store it on a master server. Change the service to allow remote callers by setting an access key under the clients list in the episerver.search.indexingservice section in web.config: 
    <add name="ACCESSKEY_HERE" 
     description="local" 
     allowLocal="false" 
     ipAddress="0.0.0.0/0" 
     ip6Address="::/0" 
     readonly="false" />
  6. Change the client to access one of the servers with the specific access key by changing the services list episerver.search section in web.config: 
    <add name="serviceName" 
     baseUri="http://SERVER1/IndexingService/IndexingService.svc" 
     accessKey="ACCESSKEY_HERE" />
  7. The site is ready to be load-balanced. Copy the site folder to a second server and create a new site in IIS with the same settings as the previous server. No configuration changes required.
  8. Test remote events by logging in to one of the servers and publish change to a page. The published changes appear on the other server. Use the search functionality from both servers to verify it was configured correctly.

A hosting provider can help you load-balance incoming traffic between the servers. You also can use other software load-balancers such as HAProxy, Network Load Balancing (NLB) or Application Request Routing (ARR).

Note: 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 approaches to enabling session state that depend on the sticky session feature (also known as session affinity) provided by a load-balancer that makes sure a user is reaching the same server combined with the default in-memory session state provider. You also can use an optimized provider for load-balancing, such as the built-in StateServer.

Episerver recommends that you enable the ARR Affinity setting for applications in DXC to ensure proper functioning and saving of contents, in respect to cache invalidation by remote events. In Azure, go to the App Service where you want to make the change, select Settings > Application Settings and enable ARR Affinity.

You can also set ARR Affinity in web.config as follows:

<system.webServer>
  <httpProtocol>
    <customHeaders>
      <add name="Arr-Disable-Session-Affinity" value="false" />
    </customHeaders>
  </httpProtocol>
</system.webServer>

Related topics

Blog posts

Last updated: Jun 14, 2021