Installation Instructions - EPiServer CMS

Introduction

Installation of EPiServer CMS is achieved with EPiServer Deployment Center, which is used to install and maintain EPiServer products.

This document describes how to install, upgrade and delete EPiServer CMS 6 and its components.The EPiServer CMS 6 installation comprises of EPiServer CMS 6 assemblies and various components for installation of Web sites. The Express Installation is a  "one click installation" scenario - making it very quick and easy to install a first version of EPiServer CMS.

EPiServer Deployment Center is based on PowerShell Scripts, which makes it easy for any third party company to use the same installer for their products as well. 

Table of Contents

• Overview
• First Installation
• Express Installation
• Custom Installation
• Live Monitor Installation
• Installing Application Files
• EPiServer Deployment Center Instructions
• Oracle Database Configuration
• SDK documentation
• Module Installation
• Setting up IIS7
• Installation Components in Detail
• Troubleshooting
• Windows PowerShell Installation

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.
   

First Installation

If during EPiServer CMS installation Microsoft Windows Powershell is not found on the target machine then the EPiServer CMS installer will install it as part of the installation process. EPiServer Shared Components will be installed as well as database and Web site creation - if opted for. When performing a first installation the followling steps should be carried out:

1. Download the EPiServer CMS 6 release zip file and unzip the contents to your hard drive (be sure to extract the files, do not just open the zip file).
2. Run the "Setup.exe" file. On running setup.exe the installer will check if the required software components and versions are installed on the machine. If any of the software components or versions or incorrect then a dialog will appear informing you of the software that is required to be installed or updated. See the system requirements.
3. In order to install EPiServer Deployment Center and EPiServer CMS 6 Microsoft Windows Powershell is required to be installed on the machine - Powershell is part of the installation package. 
   Installation of Microsoft Windows Powershell may take several minutes.
   Click OK.
   
4. The EPiServer CMS Setup Wizard will appear - click Next in the dialog to continue with the installation.
5. Accept the terms of the license agreement by clicking in the accept box and then click Next. 
   
6. Choose the type of installation you want to install
    
   • "Application Files" will only deploy EPiServer components on the target machine. Selecting this option will not give you any more options in the wizard.
   • "Express" will in addition to deploying all necessary file also create a sample site. Selecting this will not give you any more options in the wizard. See Express Installation below for further information.
   • "Custom" will make it possible to choose which features to install. Selecting this option will provide you with a new wizard step.  If you choose to install Example Site additional input will be required for specifying the properties of the example site. See the Custom Installation guide below for further information and instruction.
7. Click the Install button in the EPiServer CMS Wizard to begin installation.
8. Click the Finish button in the EPiServer Installation Wizard.
9. Click OK and the chosen installation should now be complete.
   
10. EPiServer Deployment Center has now been installed on the machine and should be listed under EPiServer along with the other programs installed on the machine. For the EPiServer Deployment Center file structure see the EPiServer Structure On Disk section.

Express Installation

Selecting an "Express" installation will create a sample Web Site on the local machine without dialog interaction. The file structure of this Web Site should be similar to the image below. The EPiServer CMS 6 installation file structure is described in the section EPiServer Structure On Disk.

To perform an Express Installation an SQL server is required to be installed on the local machine otherwise the option will be disabled - see the system requirements concerning which SQL Server databases are supported.

Currently an express installation is only available when you you install EPiServer CMS  6 for the first time. Though it is possible to carry out an express installation from a command prompt, see this blog post for further information.

Custom Installation

After selecting "Custom" complete the additional steps that are required:

1. Click on the icon and then next In order to choose the features you want to install:
   Core Files - Install EPiServer CMS application files
   Public Templates - Install EPiServer CMS Public Template Files.  Allowing you to install Public Templates with the Installation wizard.
   Mirroring Service - Install EPiServer CMS Mirroring Service as a separate web application. The Mirroring Service enables you to continously replicate content between EPiServer CMS applications. An Enterprice licese is needed to use this functionality.
   Example Site - Will create an EPiServer Web site and database with customized settings and names.
2. You will need to provide configuration for your Web server: 
   - Enter a name for the site to be installed in the Site name box
   - Enter Application (Optionally)
   - Enter Path for the SIte
   - Enter Application Pool Name
   - Enter Web Server Bindings
   - Enter EPiServer User interface information - Relative Path
   
   
   
   Click Next.
3. The next step will gather information about how to connect to the database server and information about the EPiServer CMS database about to be created:
   • Select or Enter the name of the Server instance to use and the Port number (default) in the Port field defines the database server's default port. If you wish to install to another database server port, change the value to the desired port number.
   • Select the authentication mechansim to use when accessing the server
   • 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. You can use EPiServer Deployment Center to create databases with the EPiServer CMS schema, see the EPiServer Deployment Center Instructions section for more information.
   • 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. Note that the user running EPiServer Deployment Center must have owner access rights to access the database.
     
   • Click Next.
4. Select or create the folder where Virtual Path Provider files will be stored for the site. Each VPP will create a child folder under the folder selected in the wizard:
   
   
   Click Next.
5. In the next step, check the Install Public Templates if desired:
   
   
   Click Next.
6. In the next step 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:
   
   
   Click Next.
7. The last step is a summary of all the steps that will be taken by the wizard when it completes.
   
   
   Click Install.
8. The progress dialog will report all steps performed and the site will be created.
   
   
   
9. The installation is almost complete and you are now opted to launch deployment center and display the EPiServer CMS  6 Get Started documentation.
   
   
   
10. Reboot the system in order to complete the installation.

Live Monitor 2.0 Installation for EPiServer CMS 6

Installation of Live Monitor in EPiServer CMS 6 is performed separately - download and run the Live Monitor msi file - see the Live Monitor 2.0 Installation Instructions.

Application Files Installation

Choosing "Application Files" will only deploy EPiServer CMS components on the target machine. Selecting this will not give you any more options in the wizard. 

EPiServer Deployment Center Instructions

When opening the EPiServer Deployment Center, the different versions of EPiServer CMS currently installed on your machine will be listed. The EPiServer CMS Web sites currently on the machine will be listed under the relevant version of EPiServer CMS. Select the task you wish to perform on a listed Web Site and click on the Run button.

• Delete Site
• Install a Module from a Compressed File
• Install Public Templates
• Install site and SQL Server database
• Install site without database
• Install SQL Server Database
• Upgrade site with SQL Server database

Delete Site

Choose this option if you wish to delete a Web site and optionally its database, users and VPP.

1. After choosing Delete Sites in EPiServer Deployment Center, all your existing EPiServer CMS sites are displayed. Choose the Web site to be deleted:
   
   
   Click Next.
2. Select the parts of the installed site that you want to delete. The default setting is to delete all parts of the site. Clear the relevant check boxes if you do not want:
   Delete the application files folder
   - Delete the IIS Application Pool used
   - Delete the database
   - Delete the database login used by EPiServer CMS
   - Delete the VPP folders
   
   
   Click Next.
3. An overview of the objects that shall be deleted will be displayed. Click Uninstall and Web site deletion will commence. A progress bar of the deletion process will then be displayed.
   
4. "Finished" is displayed in the progress bar when Web site deletion is completed.
   Note: As Windows membership provider is the default membership provider logging on should be achieved by entering your Windows username and password.  

Install a Module from a Compressed File

Choosing this option allows you to install an EPiServer module from a compressed zip file.

Install Mirroring

For information see the document EPiServer CMS Mirroring 2.0. 

Install Public Templates

Choosing this option install the EPiServer CMS Public Templates on an existing website.  

Install site and SQL Server database

Choosing this option installs a Web site with a database. Most of the steps for this option are identical to that when performing a Custom Installation. See the information from Step 2 in the Custom Installation section. 

Install site without database

Choosing this option installs EPiServer CMS application files and VPP folders without installing a database. Most of the steps for this option are identical to that when performing a Custom Installation - though not Step 3 (select/create database) . See the information in Step 2 and from Steps 4 to 6 in the Custom Installation section. 

Install SQL Server Database

Choosing this option installs a database with EPiServer CMS schema only. The steps for installing a database only are the same as Steps 3 and 7 in the Custom Installation section except that you can not choose an existing database. 

Migrate data for site with SQL Server database

Migrates the data in the EPiServer CMS website from version 5.2 format to version 6.0

Upgrade site with SQL Server database

Upgrades a website and SQL Server database EPiServer CMS 5.2 SP2 to EPiServer CMS 6.0

Oracle Database Configuration

It is possible to configure EPiServer CMS 6 with an Oracle database. See the document Configuring EPiServer CMS with an Oracle Database for further information.

SDK Installation

Code examples for the new EPiServer CMS 6 functionality are available, see the following:

• Download Dynamic Data Store Examples
• Download QuickChat Gadget Example
• Live Monitor 2.0

An SDK for EPiServer CMS 6 is not available.

The EPiServer CMS 6 SDK (.chm) help-file is installed on your machine after running the EPiServerVsIntegration.msi file.  It should be listed with the EPiServer Deployment Center (..\Program Files\EPiServer).  The SDK documentation is also available online - EPiServer CMS 6 SDK .
The EPiServer CMS integrated Visual Studio 2008 tools are also installed after running the EPiServerVsIntegration.msi file.  These consist of the EPiServer project template and the following templates for EPiServer CMS 6 development - page template, GUI plugin, Web user control and custom property.

Module Installation 

For information regarding installation of your own module see Fredrik Tjärnberg's article. This article introduces the Visual Studio project template for download (that builds upon Windows Installer Xml (WiX)) that will help you create your own module installation package for EPiServer CMS.

Setting up IIS7 (Windows Server 2008 and Vista)

IIS 7 requires you to select exactly which modules you wish to run on your Web Server. If IIS7 has not been configured, the Deployment Center will give the option to install all the IIS features needed for running EPiServer CMS 6. Here is a list of recommended Role Services that should be installed to successfully deploy EPiServer CMS 6:

Installation Components in More Detail

Windows Installer Files

Installing EPiServer CMS is built on Windows Installer to support installation, uninstallation, component upgrade as well as component and installation integrity. Windows Installer has built in support for User Account Control and requests user elevation when necessary (Vista and WS 2008). We use windows installer technology for deploying files, updating registry and checking prerequisites. As a final step depending on user input during the installation wizard the windows installer can call into EPiServer Deployment Center (see below) for performing site creation and deletion (during uninstall).

We use windows installer technology for deploying files, updating registry and checking prerequisites.In order to get a running site a new tool called EPiServer Installation Manager (EPiServerInstall.exe) is used. 

EPiServer Deployment Center

In order to get a running site a new tool called EPiServer Deployment Center (EPiServerInstall.exe) is used. This tool launches Windows PowerShell and executes one of several predefined scripts. The idea is that we want a script based configuration of the site since it is easier to maintain over time and also provides a way for partners and customers to customize the way an EPiServer CMS site is created / deleted or how an EPiServer CMS module is applied. Modules packages e.g. Public Templates which comes with a default EPiServer CMS installation can provide their own logic to be executed by the installer. EPiServerInstall can be run in interactively or from the command line. When launching it without parameters it will show a UI presenting all available scripts to execute for each individual version of EPiServer CMS.

Setup.exe (bootstrapper)

This executable is responsible for checking and installing some prerequisites such as Windows PowerShell and IIS (if not present on the target machine) and for launching windows installer installations. It also migrates unregister older version of the EPiServer Services (Scheduler, Indexing and Log services) and migrating the configuration to the new services for R2.

If you wish to change, repair or remove the EPiServer CMS 6 installation then click on the Setup.exe file and then Next. The Dialog below will then appear. Click on the appropriate button.

EPiServer Structure On Disk

Below is an example of a EPiServer file structure layout:

Troubleshooting

Logging

When the installation fails for some reason and you don't get a satisfying indication why it failed it might be  a good idea to take a look at log files.

There are different log files involved when installing EPiServer CMS:

EPiServer Deployment Center

The installation manager logs all its activity in %ProgramFiles%\EPiServer\Shared\Install\Logs

Setup.exe

Setup.exe will log everything by default.  The result is three log files located in the same directory as the Setup.exe files.

EPiServerVsIntegration.msi

Since the VS tools for EPiServer are installed using a windows installer file you need to launch the installation from the command line to turn on logging. The following command should help:

msiexec  /i EPiServerVsIntegration.msi /lv VsInstallationLog.txt

Installing EPiServerVsIntegration.msi issue

The EPiServerVsIntegration cannot be installed side by side with an old version, and before installing the new version this has to be done:
• First uninstall the old version
• Then, go to "C:\Program Files (x86)\Microsoft Visual Studio 9.0\Common7\IDE\ProjectTemplatesCache\CSharp\EPiServer" and remove "EPiServerProject.zip".
• Install the new version

Problems opening Public Templates in Visual Studio 2008

If you experience problems opening the Public Templates Project  in Visual Studio 2008 you may wish to try the following:

1. Open the PublicTemplates.csproj file in a text editor and change the UseIIS attribute to false - <UseIIS>false</UseIIS>.
2. Save the file.
3. Open the the project file in Visual Studio 2008. 

Logging on to an 'Empty' Web Site

If you have created an empty Web site and are experiencing problems entering Edit/Admin mode in the Web config file verify that pageStartId is set to a positive value.

Reboot System

Reboot the system if the installation does not appear to be operating correctly.

Upgrading from EPiServer CMS 5 - XForms

When upgrading databases to EPiServer CMS 6 containing large amounts of xform postings you may run into problems with SQL command timeouts. These problems occurs during the migration process of xform postings from object store to the dynamic data store.
To resolve these issues there are some steps you need to carry out the following:

1. Create an index on object store
   CREATE NONCLUSTERED INDEX [IX_tblItem_SchemaId] ON [dbo].[tblItem]
(
                             [fkSchemaId] ASC
)WITH (PAD_INDEX  = OFF, STATISTICS_NORECOMPUTE  = OFF, SORT_IN_TEMPDB = OFF, IGNORE_DUP_KEY = OFF, DROP_EXISTING = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS  = ON, ALLOW_PAGE_LOCKS  = ON) ON [PRIMARY]

2. When converting large amounts of XForm postings you may have to explicitly grow the database before upgrading or you may experience timeout exceptions when the database must autogrow. This however depends on the settings and the size of the database you're upgrading.
3. Changing database command timeout for installation:
   By default, the database command timeout during installation and upgrade is set to 5 minutes. The default value has been set this high to allow for some time consuming recursive stored precedures to execute properly. These stored procedures are only executed during upgrade.
   The command timeout can be altered by adding a configuration directive to the EPiServerInstall.exe.config configuration file, as shown below. The configuration file is located in
   %ProgramFiles(x86)%\EPiServer\Shared\Install\EPiServerInstall.exe.config.
   
   <appSettings>
    <!-- Change command timeout to 5 minutes -->
    <add key="commandTimeout" value="300"/>
</appSettings>

Breaking Changes

See breaking changes in EPiServer CMS 6.

Web Site base on EPiServer Demo Templates Package

See the relevant documentation for the Demo Templates package for EPiServer CMS 6.

Problems during application startup and installation error operation on a socket

See the FAQ which contains information regarding the error operation on a socket.

Windows PowerShell Installation

The setup program will install PowerShell when it is missing on the target machine. The PowerShell installation is launched without a UI and if anything goes wrong the setup program only reports that PowerShell installation failed. When this happens it can be useful to  launch the PowerShell installation manually to find out more about why it is failing.

The PowerShell redist folder inside the installation folder contains all installers for all supported platforms except Windows Server 2008. The following table shows which installer to use on for a given platform.

Installing Windows PowerShell on Windows Server 2008

On Windows Server 2008, PowerShell is enabled by executing the following command:

pkgmgr.exe /iu:MicrosoftWindowsPowerShell 

You can also report bugs to the EPiServer Developer Support (this requires partner access).