Mirroring

The installation package contains a setup file (setup.exe) that installs the Deployment Center and EPiServer CMS on the machine. This has to be done to be able to install Mirroring. Alternatively, EPiServerShared.msi and EPiServerCMS.msi can be run instead of the Setup.exe.

A mirroring job is normally done between two sites. This means that two sites probably have to be installed, one as a source site and one as a target site. Each site can be used as a source site or a target site regardless of the purpose from the beginning.

Table of Contents

• Install a New Site with Mirroring
• Install Mirroring on an Existing Site 
• Target SIte Configuration
• Source Site Configuration
• Configuration File Configuration
• Using Mirroring 1.0
• Main Difference Between Mirroring 1.0 and Mirroring 2.0
• Synchronizing Mirroring

Install a New Site with Mirroring

Open Deployment Center and choose Install site and SQL Server database or Install site without database depending on whether you wish to use SQL Server as a database or not.

The mirroring part of the site will be installed as an application under the site/application with a separate application pool. This can of course be changed manually after the installation if you wish to have the mirroring application in a separate site.

1. Site settings and bindings
   In the first step you need to choose site settings and bindings for the site you are creating.
   
   

2. Creating database
   Select settings for the database to be created.

3. Virtual Path Provider Folder
   Select a folder where files will be stored by the Virtual Path Providers.

4. Modules
   Check the Install Mirroring 2.0 in the module list.

5. License file
   Browse to a valid license file. If you do not have any valid license file yet, you can copy the file to the site when received.

6. Summary
   Check that the port in Bindings under Site Settings is 80.

7. Credentials
   At the end of the installation, the Mirroring module will pop up a window where you need to select the credentials that will be used when a Mirroring job is run. These settings will be editable from the mirroring configuration file (web.config).
   
   

Install Mirroring on an Existing Site

To be able to install Mirroring on an existing EPiServer CMS site, the site must be running on the same version as the mirroring dll (EPiServer.MirroringService.dll). Choose Install Mirroring 2.0 from the EPiServer Deployment Center to start the installation.

1. Choose site
   Choose which site you wish to install the Mirroring 2.0 application in. Only sites installed on port 80 will be visible and selectable.

2. Credentials
   At the end of the installation, the Mirroring module will pop up a window where you need to select the credentials that will be used when a Mirroring job is run. These settings will be editable from the mirroring configuration file (web.config).
   - Username, the username of a user that will do the export and import of pages and files when the mirroring job is run.
   - Set password, the password of the user that will do the export and import of pages and files when the mirroring job is run.
   - Domain, the domain the user belongs to that will do the export and import of pages and files when the mirroring job is run.
   
   

1. Summary
   The settings are displayed. Control all the settings before continuing with the installation.

Target Site Configuration

To use a site as a mirroring target, minimal configuration is required.

Create a Target Page

Go to EPiServer CMS Edit mode on the target site and create a page that will act as the root page for the mirrored pages. It's also possible to use an existing page as the mirroring root page.

Source Site Configuration

Channels

Go to the Admin mode on the source site. In the Config tab and select Mirroring under Tool Settings. Click this link to create and edit channels for Mirroring.

Create a new channel
Click on the button “Create” to create a new channel. The following list describes the fields to be completed and the information they should hold:

1. Name, a unique name for the Mirroring channel.
2. Parameters, an optional field that can be used by providers.
   In this version there are one parameter which can be handled by episerver provider (EPiServer.MirroringService.MirroringTransferProtocol.WCF.MirroringTransferClient). TransferAction.
   The TransferAction can have two options None  and ForceCurrentVersion, by default is None which creates a new version for each published page on the target site.
   The ForceCurrentVersion option does NOT create a new version for each published page, it updates the page on the target site.
3. Use default URI, check this box to use the URI defined in the configuration file (web.config) for the mirroring application.
4. URI, the URI to the destination mirroring applications target service, for example http://localhost/R3Mirroring/Mirroring/MirroringTransferServer.svc. The service for the default provider is “MirroringTransferServer.svc”.
5. Start page, the root page on the source site to be mirrored.
6. Root page on destination, the page number on the target site where the pages will be mirrored to.
7. Include the start page, determines if the start page will be mirrored or if only its children will be mirrored.
8. Import as anonymous user, determines if an anonymous user will do the export and import of pages and files when the mirroring job is run.
9. Import content as user, determines if an identified user will do the export and import of pages and files when the mirroring job is run.
10. Enable reporting, enables the reporting for the mirroring job.
11. E-mail address, the e-mail address of the specified user for the mirroring job.
12. Continue on Error, mirroring continues even there is problem on the importing side.
13. Enabled, determines if the channel is active or not. If it´s not enabled, nothing will be mirrored for the channel.
14. Enable validation, by default it checks all necessary page types and page definitions which is include in the start page and its descendant.

1. Edit a channel
   To edit a channel, click on the name of the channel, update the fields as appropriate and click on the Save button.
2. Delete a channel
   To delete a channel, click on the name of the channel and then click on the Delete button.
3. Reset state
   It is possible to reset the state of a channel. This will make the Mirroring application re-mirror everything from the root page of the Mirroring channel to the source site next time it is run.
4. To reset the channel, click on the name of the channel and then click the Reset State button.
5. Check System
   Check both the source and target site if all necessary parameters are correctly set up. Such as Uri, Root page at destination, Mirroring Server binding, Access to DataBase and etc.

Mirroring Channels

To start the Mirroring process manually, go to Mirroring Service under the Admin tab in Admin mode and click Start manually.

1. Automatically run jobs
   In the Settings tab, it's possible to set up automatic mirroring of channels by enabling the Active check box and choosing how often the job will be run.

2. History
   In the History tab it's possible to see the result of previous jobs that have been run. If a job has failed, this is the place where you can find out why the job failed.

Configuration File Configuration

Change Security Credentials

To change the security credentials that are used when a Mirroring job is run, open the configuration file (web.config) for the source mirroring application. Locate the “episerverMirroring“ element in the configuration file and change the credentials in the “MirroringTransferServer” provider.

<episerverMirroring>
    <mirroringTransfer defaultProvider="MirroringTransferServer">
      <providers>
        <add defaultEndpointName="mirroringTargetEndPoint" 
             numberOfPagesInPackage="500"
             numberOfFilesInPackage="100"
             destinationPath="c:\temp\mirroring\" 
             chunkSize="4194304" 
             name="MirroringTransferServer" 
             type="EPiServer.MirroringService.MirroringTransferProtocol.WCF.MirroringTransferClient,EPiServer.Enterprise" 
             username="jobe" 
             password="" 
             domain="ep" />
      </providers>
    </mirroringTransfer>
   <mirroringMonitoring offlineLoggningEnabled="true" offlineLogPath="Path to offline log"/>
  </episerverMirroring>

Change Chunk Size

By default, the chunk size of the data sent between the machines is set to 4194304 bytes. This can be changed by changing this value in the provider attributes.

Change Temporary Folder

When data is sent between the machines, temporary files are stored in a location that can be modified in the configuration file. In the “MirroringTransferServer” provider, there is an attribute called “destination path” where you can set the temporary path.

Change numberOfPagesinPackage

By default the numberOfPagesInPackage is 500. Indicates the max number of pages in package.

Change numberOfFilesInpackage

By default the numberOfFilesInPackage is 100. Indicates the max number of files in package.

Change Communication Protocol

When the mirroring application is installed, basicHttpBinding will be used by default when communicating between the machines. To change this, change the bindings in the configuration files for both the source and the target application. For more information about WCF and bindings, see http://msdn.microsoft.com/en-us/library/ms735119.aspx

Change offlineLoggingEnabled and offlineLogPath

By default offline monitoring is disabled and can be enabled by setting the offlinLoggningEnabled to true.
By default the path to offline monitoring log is "C:\Windows\Temp\episerver\cms6\mirroring\monitoring\" and it can be changed to another path by setting the offlineLogPath attribute.

Use Other Mirroring Provider

It´s possible to use other mirroring providers than the build-in provider. Add the provider in the “episerverMirroring” section and set the defaultProvider to the provider you want to run.

<episerverMirroring>
    <mirroringTransfer defaultProvider="myMirroringProvider">
      <providers>
        <add defaultEndpointName="mirroringTargetEndPoint" 
             destinationPath="c:\temp\mirroring\" 
             chunkSize="4194304" 
             name="MirroringTransferServer" 
             type="EPiServer.MirroringService.MirroringTransferProtocol.WCF.MirroringTransferClient,EPiServer.Enterprise" 
             username="jobe" 
             password="" 
             domain="ep" />
        <add name="myMirroringProvider"
             type="jobe.MirroringProvider, jobe.Providers"
              />
      </providers>
    </mirroringTransfer>
  <mirroringMonitoring offlineLoggningEnabled="true" offlinelogPath="Path to offline log"/>
</episerverMirroring>

Change the Mirroring Application to a Separate Site

When the Mirroring application is installed by the Deployment Center, it is installed as an application under the EPiServer CMS site chosen. To change the mirroring application to a separate site, there are some actions that must be done.

1. Add site in IIS
   Open up IIS and delete the Mirroring application under the source and target sites. After the application has been deleted, create a new site and set its root folder to the ‘Mirroring’ folder that was created as a sub-folder to the source/target site’s root folder. This document does not contain any information about how to use WCF and basicHttpBinding on another port than 80. See http://msdn.microsoft.com/en-us/library/ms733768.aspx Configuring Namespace Reservations for details about using a port other 80 for WCF application hosted in IIS.

2. Change service endpoints
   Open the configuration files for both the source and target mirroring sites. The addresses for both “mirroringSourceEndpoint” and “mirroringTransferEndpoint” must be updated so it points to the correct address.
   <endpoint address="http://site1Mirroring/MirroringSourceServer.svc" name="mirroringSourceEndpoint"…

<endpoint address="http://site1Mirroring/MirroringTransferServer.svc" name="mirroringTransferEndpoint"…

Using Mirroring 1.0

In new installations of EPiServer CMS sites, the old mirroring plug-in is disabled by default. To enable it, go to the Plug-In Manager in the Config tab in Admin mode, click EPiServer User Interface and then Overview. Now you will see that Legacy Mirroring is unchecked. Select this box and save. Reload the page and go to the Config tab again and you will see the Legacy mirroring in the list.

Main Differences Between Mirroring 1.0 and 2.0

Mirroring 2.0 is a re-write from the ground up. The only code that has been re-used from Mirroring 1.0 is the importer and exporter classes to import and export data to and from an EPiServer CMS site.

The following list details the main changes in Mirroring 2.0

• Based on Microsoft’s .NET Provider model, allows EPiServer partners and customers to plug-in their own code when performing Mirroring. The rest of the list details features in EPiServer default provider
• HTML and XML Mirroring are no longer supported. Mirroring in formats other than EPiServer’s Import/Export format can be created by partners and customers themselves and plugged-in using the above mentioned provider model.
• Both source and destination code for Mirroring 2.0 is run in a totally separate application to the EPiServer CMS site. The Mirroring application can even be hosted on a totally separate machine to the source and target sites. This allows for much better performance, scalability and greatly reduced impact on the EPiServer CMS site. The default configuration creates an application hosted in IIS, however this can be changed by partners and customers to be hosted and any type in Windows application.
• Microsoft’s Windows Communication Foundation provides the communications layer between the EPiServer CMS site and the Mirroring application for both the source and target sites and also between the source and target Mirroring applications. The default protocol used out of the box is BasicHttp. However, this is totally configurable by the partner/customer so that they may choose a protocol that matches their needs.
• Data sent between the source and target Mirroring applications is chunked in configurable packet sizes to reduce network stress and memory usage
• Mirroring jobs that fail or are stopped by IIS / server restarts continue from where they left off. This means that the whole Mirroring job does not have to be run again from the beginning.
• Mirroring 2.0 provides real-time monitoring of Mirroring jobs. 

Synchronizing Mirroring

You need to synchronize the bin folders both under Site root folder and Mirroring Service bin folder. When assemblies in the site bin folder and mirroring service bin folder are not same, you will receive the following error when performing “Check System”:

It is important to have both bin folders synchronized with each other, since the Mirroring Service runs as a separate application and is having its own application pool. When you add any custom code/property/module under the source site, the affected assembly should be copied over to the Mirroring Service bin folder as well. If you have installed mirroring service on both source and destination sites, then Site and Mirroring Service must have the same assemblies under the bin folders.