Back arrowBack to resources
Optimizely icon Optimizely
A Fast Guide to Installing Optimizely CMS 12 Locally

A Fast Guide to Installing Optimizely CMS 12 Locally

Alex Rollin
Alex Rollin
October 30, 2025
Last updated : February 15, 2026
October 30, 2025

Setting up a new CMS locally shouldn't take all day. If you're ready to start working with Optimizely CMS 12 but aren't sure where to begin, this guide walks you through the entire installation process step by step. You'll have a working development environment running on your machine in under an hour.

Optimizely CMS 12 runs on .NET 6, 7, or 8, making it compatible with the latest development tools and frameworks. Whether you're evaluating the platform for a new project or getting familiar with it for an existing one, having a local installation lets you experiment, build, and test without affecting any live environments.

Prerequisites for Optimizely CMS 12 Local Setup

Before starting the installation, you'll need several tools installed on your machine. Most developers will already have some of these, but it's worth checking you have everything ready.

Required Software

1. .NET SDK (Version 6.0, 7.0, or 8.0)
The foundation for running Optimizely CMS 12. Download the version that matches your project requirements from Microsoft's .NET download page. Version 8.0 is recommended for new projects.

2. Visual Studio 2022 or 2023
While you can use other editors, Visual Studio provides the best development experience for Optimizely. The free Community Edition works perfectly. Download it from Visual Studio's website.

3. SQL Server Express or Developer Edition
Optimizely stores its content in a SQL database. SQL Server Express is free and sufficient for local development. Get it from Microsoft's SQL Server downloads.

4. SQL Server Management Studio (SSMS)
This tool helps you manage your databases visually. While not strictly required, it makes troubleshooting database issues much easier. Download from Microsoft's SSMS page.

Optional but Helpful

Node.js - If your project uses any JavaScript build tools or frameworks. Download from nodejs.org.

IIS (Internet Information Services) - For testing in a production-like environment. Enable it through Windows Features.

Administrator rights - You'll need these for certain installation steps, particularly when working with IIS.

Step-by-Step Implementation

Step 1: Install Optimizely Templates and CLI Tools

Open PowerShell or Command Prompt as an administrator. First, install the Optimizely project templates:

dotnet new -i EPiServer.Templates

Next, install the Optimizely CLI tool that helps manage databases and users:

dotnet tool install EPiServer.Net.Cli --global --add-source https://nuget.optimizely.com/feed/packages.svc/

The CLI tool installation might take a minute or two. Once complete, you can verify it worked by running:

dotnet-episerver --version

Step 2: Create Your Optimizely Project

You have two main options here: start with the Alloy demo site (recommended for learning) or create an empty project.

For the Alloy demo site with sample content and pages:

dotnet new epi-alloy-mvc -n MyOptiSite
cd MyOptiSite

For a blank project without any sample content:

dotnet new epi-cms-empty -n MyOptiSite
cd MyOptiSite

The Alloy template includes example page types, blocks, and content that help you understand how Optimizely structures work.

Step 3: Configure Your Database Connection

By default, new projects use a LocalDB .mdf file. We've found that using a full SQL Server instance provides better performance and fewer connection issues during development.

First, delete any .mdf files in the App_Data folder of your project.

Open appsettings.Development.json in your project root and update the connection string:

{
  "ConnectionStrings": {
    "EPiServerDB": "Server=localhost;Database=OptiCms12;Trusted_Connection=True;MultipleActiveResultSets=True"
  }
}

Adjust the Server value based on your SQL Server installation:

  • localhost for default SQL Server installations
  • localhost\SQLEXPRESS for SQL Express
  • (localdb)\MSSQLLocalDB for LocalDB

Step 4: Create the Database

Use the Optimizely CLI to create and configure your database:

dotnet-episerver create-cms-database MyOptiSite.csproj -S localhost -E -dn OptiCms12

Breaking down these parameters:

  • -S localhost specifies your SQL Server instance
  • -E uses Windows authentication (no password needed)
  • -dn OptiCms12 names your database

If you prefer SQL authentication instead of Windows authentication, replace -E with -U username -P password.

Step 5: Create an Admin User

Every CMS needs at least one admin user. Create one using the CLI:

dotnet-episerver add-admin-user MyOptiSite.csproj -u admin -e [email protected] -p StrongPassword123! -c EPiServerDB

Parameters explained:

  • -u admin sets the username
  • -e [email protected] sets the email address
  • -p StrongPassword123! sets the password (make it strong!)
  • -c EPiServerDB references your connection string name

Step 6: Build and Run Your Site

Now you're ready to compile and launch your site:

dotnet build
dotnet run

Your site will start and display URLs in the console output, typically:

  • https://localhost:5001
  • http://localhost:5000

Visit the HTTPS URL in your browser. To access the CMS editorial interface, add /episerver/cms to the URL: https://localhost:5001/episerver/cms

Log in with the admin credentials you created in Step 5.

Code Examples with Explanations

Once your site is running, you'll want to add custom functionality. Here's how to create a basic page type that editors can use to create content.

Creating a Simple Page Type

Create a new file Models/Pages/ArticlePage.cs:

using EPiServer.Core;
using EPiServer.DataAnnotations;
using System.ComponentModel.DataAnnotations;

namespace MyOptiSite.Models.Pages
{
    [ContentType(
        DisplayName = "Article Page", 
        GUID = "3e7c4f7e-1234-4567-8901-123456789abc", 
        Description = "Use this page type for articles and blog posts")]
    public class ArticlePage : PageData
    {
        [CultureSpecific]
        [Display(
            Name = "Article Title",
            Description = "The main headline of your article",
            GroupName = SystemTabNames.Content,
            Order = 10)]
        public virtual string ArticleTitle { get; set; }

        [CultureSpecific]
        [Display(
            Name = "Article Body",
            Description = "The main content of your article",
            GroupName = SystemTabNames.Content,
            Order = 20)]
        public virtual XhtmlString ArticleBody { get; set; }

        [Display(
            Name = "Publish Date",
            Description = "When this article was published",
            GroupName = SystemTabNames.Content,
            Order = 30)]
        public virtual DateTime PublishDate { get; set; }
    }
}

After adding this code, rebuild your project. The new page type will appear in the CMS when editors create new pages.

Adding a Controller for Your Page Type

Create Controllers/ArticlePageController.cs:

using EPiServer.Web.Mvc;
using Microsoft.AspNetCore.Mvc;
using MyOptiSite.Models.Pages;

namespace MyOptiSite.Controllers
{
    public class ArticlePageController : PageController<ArticlePage>
    {
        public IActionResult Index(ArticlePage currentPage)
        {
            // Add any logic needed before rendering
            return View(currentPage);
        }
    }
}

Creating the View

Add a corresponding view at Views/ArticlePage/Index.cshtml:

<article>
    <h1>@Model.ArticleTitle</h1>
    <time datetime="@Model.PublishDate.ToString("yyyy-MM-dd")">
        @Model.PublishDate.ToString("MMMM d, yyyy")
    </time>
    <div class="article-content">
        @Html.Raw(Model.ArticleBody)
    </div>
</article>

Common Mistakes to Avoid

Database Connection Issues

The most frequent problem developers encounter is database connectivity. If you see connection errors:

  • Verify SQL Server is running (check Windows Services)
  • Confirm your connection string matches your SQL Server instance name
  • Test the connection using SQL Server Management Studio
  • Check Windows Firewall isn't blocking SQL Server

Our experience shows that using Windows Authentication (Trusted_Connection=True) eliminates most authentication problems during local development.

Port Conflicts

If you get a "port already in use" error when running your site, another application is using port 5000 or 5001. Fix this by editing Properties/launchSettings.json:

{
  "profiles": {
    "MyOptiSite": {
      "applicationUrl": "https://localhost:5003;http://localhost:5002"
    }
  }
}

Missing NuGet Package Source

Optimizely packages come from their own NuGet feed. If Visual Studio can't find packages, add the Optimizely source:

  • In Visual Studio, go to Tools → NuGet Package Manager → Package Manager Settings
  • Click Package Sources
  • Add a new source:
    • Name: Optimizely
    • Source: https://api.nuget.optimizely.com/v3/index.json

Forgetting to Create an Admin User

Without an admin user, you can't access the CMS interface. If you forget this step, the site will run but you won't be able to log in. Always create at least one admin user using the CLI command shown in Step 5.

Using Outdated .NET Versions

Optimizely CMS 12 requires .NET 6 or later. If you have an older version, you'll see build errors about missing framework references. Update your .NET SDK to fix this.

Testing and Verification Steps

After installation, verify everything works correctly with these checks:

1. Site Loads Successfully

Navigate to your site's homepage. You should see either the Alloy demo content or a basic page (depending on which template you used).

2. CMS Login Works

Visit /episerver/cms and log in with your admin credentials. You should see the editorial interface with navigation on the left side.

3. Create Test Content

In the CMS, create a new page:

  • Click the globe icon (Sites)
  • Right-click on your site root
  • Select "New Page"
  • Choose a page type
  • Fill in required fields
  • Click "Publish"

Teams we work with report that testing content creation immediately helps identify any permission or configuration issues before they become problems later.

4. Database Connectivity

Open SQL Server Management Studio and connect to your database. You should see tables prefixed with tbl_ containing your CMS data.

5. Build Without Errors

Run a clean rebuild to ensure no compilation issues:

dotnet clean
dotnet build

6. Check Browser Developer Console

Open your browser's developer tools (F12) and check the Console tab for JavaScript errors. The site should load without any red error messages.

Optional: Setting Up IIS for Production-Like Testing

While Kestrel (the built-in web server) works great for development, you might want to test with IIS to match your production environment more closely.

Enable IIS

  • Open Windows Features (search "Turn Windows features on or off")
  • Check "Internet Information Services"
  • Expand and check:
    • Web Management Tools → IIS Management Console
    • World Wide Web Services → Application Development Features → ASP.NET Core

Install .NET Hosting Bundle

Download and install the ASP.NET Core Hosting Bundle from Microsoft's download page. This lets IIS run .NET applications.

Publish Your Site

dotnet publish -c Release -o C:\inetpub\wwwroot\MyOptiSite

Configure IIS

  • Open IIS Manager
  • Right-click Sites → Add Website
  • Configure:
    • Site name: MyOptiSite
    • Physical path: C:\inetpub\wwwroot\MyOptiSite
    • Hostname: myoptisite.local
  • Set Application Pool to "No Managed Code"

Update Hosts File

Add this line to C:\Windows\System32\drivers\etc\hosts:

127.0.0.1   myoptisite.local

Now you can access your site at http://myoptisite.local.

Conclusion

You now have Optimizely CMS 12 running locally with a working database, admin access, and the ability to create custom page types. From here, you can start building your content structure, adding functionality, and exploring the platform's capabilities.

The setup process we've covered gives you a solid foundation for development. You can create content types, test editorial workflows, and build features without affecting any production systems. Remember that local development doesn't require any Optimizely licenses - they're only needed when you deploy to public domains.

We've found that having a properly configured local environment saves countless hours during development. Taking time to set things up correctly now means fewer surprises when you deploy to staging or production environments.

If you're planning to build a production site with Optimizely CMS 12 and need help with architecture decisions, content modeling, or deployment planning, our team at Rollin can guide you through the process. We work with businesses to design and implement Optimizely sites that meet specific content management needs while maintaining strong performance and editor satisfaction. Contact us to discuss how we can help with your Optimizely CMS 12 project.

Share this article