November Happy Hour will be moved to Thursday December 5th.

AI OnAI Off

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

FURTHER INFORMATION

» Release Notes

» Breaking Changes

» Oracle Database Configuration