Install CMS 13

This guide covers a fresh installation of Optimizely CMS 13. CMS 13 requires .NET 10 and two mandatory components for full functionality: Opti ID and Optimizely Graph. Both are included in your CMS 13 license.

If you are migrating from an earlier version, see Upgrade to CMS 13 instead.

Before starting, review Overview of CMS 13 to understand the mandatory and optional components of CMS 13. You should consider the timelines needed for each component in your go-live planning.

Verify your environment meets the System requirements for CMS 13. Key requirements include the following:

Order a time-limited demo license from Optimizely License Center for evaluation. A license is not required when using IIS Express during development. A commercial license is required for testing and production environments.

Optimizely project templates provide the project scaffolding and NuGet configuration for CMS 13 sites.

Install the Optimizely project templates to create a CMS 13 site:

The templates include a nuget.config file with the Optimizely NuGet feed that contains Optimizely packages. This file maps available services to their endpoints and determines where to send requests for searching or publishing packages. See also NuGet package families in CMS.

Choose a project template based on your needs. The empty template provides a minimal starting point. The Alloy template includes sample content types and templates.

Run the following command to create a CMS project without sample content:

Run the following command to create a CMS project with sample content and templates:

To set the project name, output folder, and enable Docker support, use the following command:

To view all available options for the Alloy template, run the following command:

CMS 13 requires explicit service registration for each referenced NuGet package.

After creating your project, register CMS services in Startup.cs. The AddCms() method registers all core CMS services:

For modular registration options and detailed initialization configuration, see Initialize CMS 13.

Opti ID and Optimizely Graph are mandatory for CMS 13. Both are included in your license and require configuration for full CMS 13 functionality.

Opti ID provides single sign-on (SSO) across Optimizely products and enables DAM and Mark (Optimizely Agent Platform) integrations. Follow the steps in Configure Opti ID for CMS 13 to configure it.

Opti ID authenticates Optimizely product users who are editors and administrators. It's enforced in protected shell modules only: the edit UI, the admin UI, and add-ons. It does not authenticate site visitors.

If ASP.NET Identity was used only to sign editors and administrators in to the CMS, remove the EPiServer.Cms.UI.AspNetIdentity package reference and any services.AddCmsAspNetIdentity<TUser>() call once Opti ID is configured.

If ASP.NET Identity also serves site visitors during registration, sign-in, password reset, or gated content on the public site, keep the package and keep the AddCmsAspNetIdentity<TUser>() call. EPiServer.CMS.UI.AspNetIdentity ships in CMS 13 and is supported alongside Opti ID. Your visitor accounts, password hashes and role assignments stay where they are; no migration is required. Register Opti ID as below without making it the default scheme: services.AddCmsAspNetIdentity<SiteUser>(); // site visitors — unchanged services.AddOptimizelyIdentity(); // editors and administrators

See Use Opti ID with a separate site-visitor authentication scheme.

See Configure Opti ID for CMS 13 for the side-by-side pattern.

Optimizely Graph replaces the legacy content indexing, preview, and delivery pipeline. Graph powers Content Manager, Visual Builder, content binding, and Mark capabilities.

Add the NuGet package and register the service in Startup.cs or Program.cs:

Before configuring Graph in your project, enable the Graph service to sync DAM and CMS. Then follow the steps in Get started with Optimizely Graph for CMS 13.

Content Manager provides the editorial experience for locating and managing content. Opt in by registering it explicitly.

Add the NuGet package:

Register the service in Startup.cs or Program.cs:

The following example shows the minimum service registration with all mandatory components in the correct order:

CMS 13 stores content, settings, and user data in a SQL database.

Configure the EPiServerDB connection string in appsettings.json to point to a SQL Server 2022 or Azure SQL database. CMS 13 requires database compatibility level 140 or higher.

For connection string configuration and schema creation options, see Install database schema. For configuration through option classes and environment variables, see Configure CMS 13.

CMS 13 replaces the sites concept with applications and supports two types: In process (server-rendered) and Headless (content delivered through Graph to a separate frontend). After first startup, verify your settings at Settings > Applications in the CMS admin interface.

For details on application types and configuration, see Application framework.

CMS 13 supports optional integrations for digital asset management and search.

Before implementing the DAM Asset Picker, try Content Manager to locate and insert assets. Content Manager may meet your asset management needs without additional integration. Content Manager supports both embedded DAM assets and any externally synced content. The DAM Asset Picker provides additional asset organization features, but they may not be necessary for smaller asset libraries.

To integrate Optimizely Digital Asset Management (DAM) Asset Picker with CMS 13, add the package and register the service:

For DAM configuration details including appsettings.json configuration, see Configure DAM Asset picker.

Search & Navigation is not supported in CMS 13. Implement search using one of the following options:

For available apps and compatibility information, see Optimizely apps and integrations and Apps (add-ons) platform compatibility. For installation instructions, see Install Optimizely apps.

Follow this installation order based on your site type:

After completing the installation, continue with the following guides: