Illustration of a terminal window running an install command beside stacked foundation blocks

How to Install Optimizely Foundation?

First published in July 2023. Restored in October 2026, with notes on anything that has changed since.

Update, October 2026. Foundation is a CMS 12 reference solution built on .NET 6, which Microsoft stopped supporting in November 2024. It also relies on Search & Navigation, which isn’t supported in CMS 13. For a new CMS 13 project, start from the CMS 13 templates instead (see How to install Optimizely).

What is Optimizely Foundation?

Optimizely Foundation is an open-source project offered by Episerver, now Optimizely, providing a structured and modular reference architecture for developers. It enables the integration of various Optimizely products into solutions. With projects for CMS, Commerce Connect (formerly Customized Commerce), Personalization, Search & Navigation, and the Community API, developers can select and include or exclude specific components as needed.

It has undergone rigorous testing, including penetration and load testing, and is certified to run on the DXP Service. Optimizely Foundation offers a starting point for development and showcases best practices through the Mosey demo site.

Optimizely Foundation Installation Instructions

In this article we’ll describe how to install the Optimizely Foundation open-source starter solution, as well as tips for fixing issues you may encounter along the way.

Prerequisites: installed the Optimizely CLI and templates, SQL, Node.js, .NET 6

Follow these instructions to install the Optimizely Foundation Starter Solution (opens in a new tab).

Frequently Asked Questions

What is Optimizely Foundation?

Optimizely Foundation is an open-source reference solution for developers. It combines projects for CMS, Commerce Connect, Personalization, Search & Navigation and the Community API, and includes the Mosey demo site to show best practices.

Should I use Foundation for a new project?

Not for a new CMS 13 project. Foundation is a CMS 12 solution built on .NET 6, which Microsoft stopped supporting in November 2024, and it relies on Search & Navigation, which isn't supported in CMS 13. Start from the CMS 13 templates instead.

How do I install Optimizely Foundation?

Open a command prompt as administrator and run:

  1. git clone https://github.com/episerver/Foundation.git
  2. cd foundation
  3. git checkout main
  4. setup.cmd
  5. dotnet run --project .\src\Foundation\Foundation.csproj

How do I fix the error 'DataException: A transient error occurred in the database'?

Enable Named Pipes in SQL Server Configuration Manager:

  1. Open SQL Server Configuration Manager.
  2. Under SQL Server Services, check that SQL Server and SQL Server Agent are running.
  3. Expand SQL Native Client Configuration and select Client Protocols.
  4. Set Named Pipes to Enabled.

How do I fix the 'Object Reference' error in AnonymousCartMergingMiddleware.cs?

If you're debugging the first build and run, you may see an 'Object Reference' error on the line that reads the anonymous ID. Continue, and the site should still load.

How do I fix the error 'No such host is known'?

Point Foundation at a Search & Navigation index:

  1. Create a free demo index at find.optimizely.com. Demo indexes are removed after 30 days.
  2. In appsettings.json, replace the DefaultIndex and ServiceUrl values in the Find section with the ones from the generated code snippet.
  3. In Admin mode, run the Search & Navigation Content Indexing Job.