Install CMS 13

This article covers a fresh installation of Optimizely CMS 13. CMS 13 requires .NET 10 and two recommended components: 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.

Prerequisites

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

• .NET 10 SDK or higher
• Microsoft SQL Server 2022 or Azure SQL (compatibility level 140+)
• Visual Studio 2026 (18.0+) or a compatible editor with .NET 10 support

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.

Install templates

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

dotnet new install EPiServer.Templates

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

📘

Note

Each template contains a README file with instructions. To report issues or contribute, visit content-templates on GitHub. For command reference, see dotnet new.

Create a CMS site

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.

Empty CMS site

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

dotnet new epi-cms-empty

Alloy sample site

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

dotnet new epi-alloy-mvc

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

dotnet new epi-alloy-mvc --name alloy-docker --output ./alloy-docker --enable-docker

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

dotnet new epi-alloy-mvc --help

Register CMS services

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

services.AddCms();

⚠️

Important

CMS 13 uses assembly scanning to discover referenced packages at startup. Every NuGet package your project references must have its services explicitly registered, or the application fails at startup.

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

Configure mandatory components

Opti ID and Optimizely Graph are mandatory for CMS 13. Both are included in your license and must be configured for your site to benefit from full CMS 13 feature functionality.

Configure Opti ID

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

If you configure Opti ID, remove the EPiServer.Cms.UI.AspNetIdentity package reference added in the Upgrade CMS packages to 13 section, as Opti ID replaces ASP.NET Identity for authentication.

Configure Optimizely Graph

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

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

dotnet add package Optimizely.Graph.Cms

services.AddContentGraph();

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.

Enable Content Manager

Content Manager provides the editorial experience for locating and managing content. You can opt-in by registering it explicitly.

Add the NuGet package:

dotnet add package EPiServer.Cms.UI.ContentManager

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

services.AddContentManager();

Combined registration example

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

services.AddCms();
services.AddContentGraph();
services.AddContentManager();

Configure the database

Configure your 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 setup and schema creation options, see Install database schema. For configuration through option classes and environment variables, see Configure CMS 13.

Configure the application model

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.

📘

Note

The CMS admin interface is available at /Optimizely/CMS (not the previous /EPiServer path). If you configure Opti ID, the path changes to /ui/cms.

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

Configure optional integrations

DAM Asset Picker integration

Before you decide to implement the DAM Asset Picker, Optimizely recommends you first use Content Manager to locate and insert assets to see if it meets your asset management needs. Content Manager supports both embedded DAM assets and any externally synced content. While the DAM Asset Picker provides a more robust asset picking experience, depending on the number of assets you manage and the depth of your asset organization, the additional features may not be necessary.

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

dotnet add package EPiServer.Cms.DamIntegration.UI

services.AddDamUI();

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

Search implementation

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

• Optimizely Graph – Build custom search using GraphQL queries. See Get started with Optimizely Graph for CMS 13.
• Third-party search provider – Use a search provider of your choice with CMS 13.

Install apps (add-ons)

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:

• If you install apps on a new CMS site, do the installation in the following order:
  1. Install an empty CMS site.
  2. Install apps (Forms, A/B testing, and so on).
• If you install apps on an existing CMS site with the Alloy templates, do the installation in the following order:
  1. Install apps (Forms, A/B testing, and so on).
  2. Rebuild the project.

Next steps

After completing the installation, continue with the following guides:

• Configure CMS 13 – Set up option classes, configuration files, and environment variables.
• Initialize CMS 13 – Understand the initialization system and create custom modules.
• Deploy CMS 13 – Deploy to Azure, Windows servers, or Docker environments.
• Breaking changes in CMS 13 – Review API and behavior changes in CMS 13.