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.

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

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:

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 and determines where to send requests for searching or publishing packages. 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

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:

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 require configuration for full CMS 13 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 configure it.

If you configure Opti ID, remove the EPiServer.Cms.UI.AspNetIdentity package reference. 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. 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

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.

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

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

DAM Asset Picker integration

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:

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 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 – Configure 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.