Deployment Center

Product version:

EPiServer CMS 6 R2

Document last saved:

10/16/2014 11:18:17 AM

Table of Contents

Introduction

The EPiServer Deployment Center is the user interface of the EPiServer Installation and Deployment System. The EPiServer Deployment Center is used when installing and deploying EPiServer CMS and other EPiServer products. From the Deployment Center you can also customize, extend and modify your EPiServer installations. Examples of such actions are creating EPiServer (CMS/Community/Relate) websites, deleting EPiServer websites, installing modules onto EPiServer websites etc. In this document the various features of Deployment Center will be described in more detail. 

Although the Installation and Deployment System is shipped with many of the EPiServer products – such as EPiServer CMS 6, Relate and Community – it is not a standalone product in itself. The system is separated into two parts, a common part that is used by all EPiServer products and a product specific part for each product.

The following work procedure is used for installing EPiServer products and modules with EPiServer Deployment Center:

  1. Check the system requirements and follow the installation instructions for the product or module.
  2. Download, unzip the installation package from EPiServer World (login access required) and run setup.exe.
  3. Open EPiServer Deployment Center (Start > Programs > EPiServer) to select action.

The common part is installed under the <Program Files>\EPiServer\Shared\Install folder and the product specific parts are installed under <Program Files>\EPiServer\ProductName\ProductVersion\Install. The ProductName is the product name such as CMS or Relate and ProductVersion is the version number of that product.

The User Interface of EPiServer Deployment Center

All installed EPiServer products that support EPiServer Deployment Center are shown in the tree under All Actions. Under each product node there is a version node for each version of the product installed. The tasks that can be performed for/on the product version are listed under the product version node.

The EPiServer Deployment Center consists of the following tabs:
– Quick Links. Select the site or application to install the product or module on. The available options are shown to the right.
– All Actions. Select product or module. The available options are shown to the right.

Task Wizards

Most tasks listed in the Deployment Center have an associated user interface wizard. A wizard is one or more pages where information needed to perform the task is collected from the user. Most wizards show a summary page before execution as final confirmation about what is going to happen. The screen shots below show examples of wizard pages from the EPiServer CMS Install Site and SQL Server Wizard.

The wizard summary page is shown above which gives details of the website, database and other resources that will be created by the task.

When the task is running, a progress indicator is shown to keep the user informed. The figure above shows the progress when a task is run from the EPiServer Deployment Center. The dialog can be hidden, in this case a message box will be shown when the task has completed. See the following example:

The tasks that appear in the EPiServer Deployment Center are actually implemented as PowerShell scripts.  More information about Windows PowerShell can be found on microsoft.com.

It is these PowerShell scripts that decide if a user interface wizard should be shown to the user to collect input information and then subsequently carry out the task in hand using a combination of in-built PowerShell functionality and EPiServer’s Deployment API.

New in EPiServer CMS 6 R2 is that compatible modules for an EPiServer CMS version will be displayed in the Deployment Center installation wizard when installing a new site and on the Quick Links tab when selecting an installed site in Deployment Center. Optionally, the file CompatibilityMatrix.config is used to allow modules packaged with a previous versions of CMS to be installed on a newer CMS version. This file is downloaded from EPiServer and overwritten each time Deployment Center starts.

EPiServer Deployment API

The EPiServer Deployment API is a managed code set that can perform actions to create, delete and manipulate websites, databases, files, folders and much more in a transactional manner. The API also includes re-usable wizard controls and classes. As mentioned before in this document, the system is divided into common and product specific parts with the Deployment API being a prime example of this.

How EPiServer Deployment Center Works

System Flow

The EPiServer Deployment Center enumerates configurable folders on the system to locate primarily, Metadata files (.metadata) and secondarily, PowerShell files (.ps1). The folders searched are defined in the EPiServerInstall.exe.config file located in the <Program Files>\EPiServer\Shared\Install folder.

If Metadata files are found then these are used to populate the tree with task nodes. Otherwise, if only PowerShell script files are found the PowerShell file names are used to populate the tree with task nodes.

The Metadata files, if present, are XML files that contain information about what tasks are available to the Deployment Center. The XML elements describing each task have an attribute point to the PowerShell script that should be run to carry out the task. For futher information regarding this see the technical note XML Update Reference.

Script Flow

The PowerShell scripts developed by EPiServer typically have the same logical flow as shown below:

EPiServer PowerShell Snap-ins

More information about the cmdlets available in the EPiServer snap-ins can be found in the tech note EPiServer for PowerShell applications.

User Interface Wizards

The UI Wizards are shown by the PowerShell scripts in order to collect input information for the task from the user. The EPiServer Deployment API contains a base class for wizards, EPiServer.Install.UI.WizardBase. The base class provides the entire wizard infrastructure (modal dialog, next, back, cancel functionality etc) so all the derived class needs to define is the pages to be shown in the wizard. Each page is actually an instance of a class derived from System.Windows.Forms.UserContol. The EPiServer Deployment API contains many pre-defined ‘pages’ for typical scenarios (website creation, database creation, folder creation etc).

The derived wizard class needs to override the PreShow and PostShow methods of WizardBase. In the PreShow method, the class should initialize its page user controls and then add them to the WizardBase.Pages collection. In the PostShow method, the class should take the opportunity to process the information entered by the user into the page user controls and set its public properties appropriately to enable the PowerShell script to read them and carry out its task.

Deployment API

The EPiServer Deployment API can be sliced both horizontally, in terms of functionality provided, and vertically, in terms of physical implementation layers.

Functionality implemented in the Common Deployment API:

Functionality implemented in the CMS Deployment API:

 
Each API is made up of a physical 3 tier implementation stack:

 

The cmdlets are provided to give the PowerShell scripts easy access to the .NET managed API. In most cases, they do not do much in themselves but rather create an instance of the appropriate .NET managed API class for the task and call the appropriate method.

The .NET Managed API is a collection of classes, one for each of the functionality areas, plus a controller class. These classes create and initialize one or more installers for the task they are asked to do and pass them off to the controller for transacted execution.

The installer classes are the ones that perform the actual implementation for the task in hand. Each class derives from the Microsoft base class System.Configuration.Install.Installer. The installer model was chosen as it naturally lends itself to transactions. The controller ensures that all the installers added as part of a bulk install are executed in a transaction. This means that if anything goes wrong in the install phase then the controller will execute a rollback to restore the system to its previous state.

Installation Instructions – EPiServer CMS 6 R2

This document describes how to install the EPiServer CMS package on your machine and how to set up your first EPiServer CMS site. This document covers both the Express installation scenario and the extended installation using the EPiServer Deployment Center. 

Table of Contents

Overview

EPiServer CMS 6 can be found in the download section - here on EPiServer World.  Included in the downloaded EPiServer CMS 6 file are the Microsoft Installer files and the Setup.exe. Running the "Setup.exe" file will start the installation of the various components, the EPiServer Deployment Center and optionally a database and an example Web site. The EPiServer Deployment Center also supports installation of other EPiServer modules, packages and connectors

After setup of EPiServer CMS 6 is complete, installation of the integrated Visual Studio 2008 tools and EPiServer CMS 6 SDK can be carried out. This is performed by running the EPiServerVsIntegration.msi file that is part of the installation package.

Here is an overview of the EPiServer CMS 6 installation components:

  • Setup.exe
    Run this file to begin installation. This executable is responsible for checking and installing some prerequisites such as Windows PowerShell and IIS. See the First Installation section below when installing for the first time on the machine. Setup.exe uses the files in the unzipped folder - all except for the EPiServerVsIntegration.msi which must be run manually.
  • EPiServerShared.msi
    This package contains the components that are shared by all (CMS 6) versions of EPiServer CMS, i.e. the different Windows Services and the EPiServer Deployment Center. The EPiServer Deployment Center is a a lightweight Windows Application that is used to initiate all installation-related actions by browsing and selecting PowerShell scripts to run; see below for further information.
  • EPiServerCMS.msi
    This package contains all necessary files to install and upgrade to a specific version of EPiServer CMS, this includes PowerShell scripts, assemblies and example templates.
  • Powershell Redist
    Microsoft Powershell installation files.
  • EPiServerVsIntegration.msi
    Run this file to install the integrated Visual Studio 2008 tools and the EPiServer CMS 6.
  • EPiServerFramework.msi
    This package contains all necessary files to install EPiServerFramework. 

Running Setup.exe

The first step of the installation is to run Setup.exe. Setup.exe will start by checking if the required software components and versions are installed on the machine. If Windows Powershell is not detected on your system it will automatically installed at this point. If any of the other required software components are missing a dialog will appear informing you of the software that is required to be installed or updated.

Once the system requirements have been fulfilled, Setup.exe will in run the msi files in this order:

  1. EPiServerShared.msi
  2. EPiServerFramework.msi
  3. EPiServerCMS.msi

EPiServerShared.msi and EPiServerFramework.msi do not require any user input. Instructions for EPiServerCMS.msi follows.:is covered in the following chapter. 

Running EPiServerCMS.msi

The first step in the EPiServerCMS.msi wizard prompts you to choose one of three setup types:

  • Application Files - Deploys EPiServer components on the target machine. After the installation you must use EPiServer Deployment Center to set up EPiServer CMS sites.
  • Express - Identical to the Application Files option with the addition that a sample site will be automatically set up.
  • Custom - Enables you to choose which features to install. The selectable feature are:
    • Core Files - required feature, this includes the CMS assemblies, UI files etc..
    • Public Templates - allows you to install Public Templates with EPiServer Deployment Center.
    • Mirroring Service - allows you to install the Mirroring Service with EPiServer Deployment Center. An Enterprice licese is needed to use this functionality.
    • Example Site - sets up an example site as part of the installation. This is similar to the Express install option, the difference being that the Custom/Example Site feature installation allows you to define your own settings for the example site. The Installation Wizard section contains information about the installation wizard that is started.

Once the installation has completed you have the option to launch EPiServer Deployment Center and/or show the getting started guide. EPiServer Deployment Center can also be launched from the EPiServer folder in the Windows start menu.

Installation Wizard

This section describes the steps included in the wizard started by the Install site and SQL Server database script. This wizard is also started by selecting Custom installation and including the Example Site feature as described in the previous section.

Step 1 - IIS Configuration

The first step in the installation wizard requires input on how EPiServer CMS should be set up in IIS. The settings in this step are:

  • Name
    The name of an IIS site in which EPiServer CMS will be installed.
    You can either type in a name or select an existing site using the dropdown. A new site will be created in IIS if you type in a name that does not match an existing site. When the Name box loses focus (when tabbing to the next box, for example) the values in the Path and Application Pool Name boxes will be updated to reflect the new name of the site.
  • Application (Optional)
    The name of an IIS application in which EPiServer CMS will be installed.
    The Application box does not have a value by default and entering a value is optional. If the Application box is left empty EPiServer CMS will be installed as a website in IIS. If a value is entered into the Application box EPiServer CMS will be installed as an application located under the site specified in the Name box.
  • Path
    The folder in the file system where the application files should be placed.
    The value in this box is automatically calculated based on the value in the Name box. The calculated path will be C:\EPiServer\Sites\[NameOfSite]. You can change this value if you want to use a different folder.
  • Application Pool Name
    The name of an IIS application pool that will be used to run the site.
    As with the Path box, the value in this box will be automatically calculated based on the value in the Name box. The calculated name will be [NameOfSite]AppPool. You can change this value if you want to use a different application pool than the suggested one. You can either type in a name or select an existing application pool using the dropdown. A new application pool will be created in IIS if you type in a name that does not match an existing application pool.
  • Web Server Bindings
    A list of bindings that will be set up for the site in IIS.
    The list can contain any number of bindings but must include at least one. The list is automatically populated with one row that alllows all host addresses but requires a spefic port - the script will make sure that the port in the default row is not used by another site. The details of site bindings will not be discussed in this document, more information about site bindings can be found at the iis.net site.
  • EPiServer User Interface - Relative Path
    The relative URL path used to access the user interface.
    Enter a path that, when combined with any of the site bindings, should access the UI interface. Note that the default value will not be accepted by the validation that occurs when you click the Next button - you have to enter your own value here. 

Step 2 - SQL Configuration

This step will gather information about how to connect to the database server and information about the EPiServer CMS database about to be created. NOTE During the installation, the existing SQL database collation (sort order) will be used when creating the database. If you have specific collation requirements, consider your choice of collation and create a database which meets your requirements ahead of deployment.

  • Select or Enter the name of the Server instance to use
    Either manually enter the address of an SQL server instance or use the dropdown to select from a list of discovered instances. Note that clicking the dropdown arrow will start the process for finding available instances, this operation can take some time. can take some time. The (default) value in the Port box is equal to 1433 - the default port for SQL servers.
  • Select the authentication mechansim  the installer should use
    The credentials the installer should use to perform database operations.
    If you select Windows Authentication the credentials of the user running EPiServer Deployment Center will be used. Using Windows Authentication usually works well when you are installing to a local SQL Server. Selecting SQL Server Authentication enables you to specify an SQL login and password that should be used. SQl Server Authentication is typically used when the SQL Server is located on another machine.
  • Enter the name of the database to create or select an existing database
    Select the name of the database you intend using from the Existing Database list or enter the name of a new database. If an existing database is selected it must contain the EPiServer CMS database schema for the installation to succeed.
  • Select the Login and Password that the EPiServer CMS should use
    Either create a new user and password or select an existing user that has owner rights to the database (passwords must include lower and upper case, a digit and a non-alphanumeric character). In the Password box type the password associated with the specified user. 

Step 3 - VPP Folder

The installation script will create three default VPP directories (Documents, Global, PageFiles), where should they be placed.

  • Path
    The folder in the file system where the default VPP folders should be placed.
    The default value for this setting is automatically calculated based on the name of the site you specified in step 1. The calculated name is C:\EPiServer\VPP\[NameOfSite]. You can change this value if you want to use a different folder. 

Step 4 - Modules

In this step you can select which modules, if any, to apply to the new installation. All available modules that are compatible with the EPiServer CMS version you are installing are presented in a checkbox list. Check the modules you wish to install. 

Step 5 - License

You can optionally provide a path for a license.config file that you want to use for the site. If omitted the site will be created but will report licensing errors. 

Step 6 - Summary

The last step is a summary of all the steps that will be taken by the wizard when it completes. If you are satisfied with the settings - click Install to start the installation.

Issues When Upgrading from EPiServer CMS 6

Alloy Technology Sample Templates

Note that the following issue may occur when upgrading an EPiServer CMS 6 website that has the Alloy Technologies sample templates installed. The issue occurs due to an error in ExcelPageProvider. This can be solved by commenting out the ExcelPageProvider from the configuration during upgrade as in the example below.

  <pageProvider> 
    <providers> 
<!--      <add entryPoint="78" filePath="~\ExcelPageProviderSource.xlsx" idColumn="ResellerID" pageName="ResellerName" pageTypeName="[Demo] Reseller" sheetName="Resellers" capabilities="None" /> -->
    </providers> 
  </pageProvider>

Fetch Data Feature

There were also issues when you upgrade a site that uses the "fetch data" feature. It turns out that there is a bug in one of the database upgrade scripts that results in loosing the reference to the fetched data page. In an upgraded site affected pages will show up as empty pages. You can also verify if you are affected or not by executing the following SQL-query:

select fkPageId from tblworkpage
where tblworkpage.linktype in (1,4)

The above query returns a row for all pages that are configured to fetch data from another page or is a shortcut to another page. If this query returns any rows on your site (before or after upgrade) you need to take action.

To recover from this, you have the following options:

  • Download the updated SQL script and save it in c:\Program Files x86\EPiServer\CMS\6.1.379.0\Upgrade\Database\sql (replace the old one) before performing the upgrade.
  • If you only have a few instances of pages that fetch data in the site and you have completed the upgrade it might be easier to manually go through the affected pages and set the fetch data reference once again.

When you replace the script with the updated script and rerun the upgrade from R1 to R2, the SQL select query still return the same rows as it did before replacing the script. This is expected, because the query will return all instances where fetch data and shortcut to other pages are used regardless of whether the upgrade was performed or not or if the patch was applied or not. 

  • If you run the query before upgrade and it returns rows - you're safe, just apply the patch and perform the upgrade and you should be good to go. 
  • If you run the script after upgrading and it returns rows - you need to consider "rolling back" the upgrade, apply patch and then rerunning the upgrade or manually reassigning the missing references (if possible).

Issues With Editors' Access to Visitor Groups

To be able to access Visitor Groups you must be a member of the access groups CmsAdmins or VisitorGroupAdmins. If you want, you can provide access for editors to visitor groups by adding them to VisitorGroupAdmins. (If you upgrade from EPiServer CMS 6.0 to 6 R2, the groups CmsAdmins and CmsEditors are already defined in the configuration. If you upgrade from EPiServer 5 to 6 R2, add the groups CmsAdmins and CmsEditors manually.) The following example shows how you can provide access for editors in the EPiServerFramework.config file under virtualRoles:

<virtualRoles replacePrincipal="true">
    <providers>
      ...
      <add name="VisitorGroupAdmins" type="EPiServer.Security.MappedRole, EPiServer" roles="WebEditors" mode="Any" />
    </providers>

Last updated: November 7, 2011