Deploy to Windows servers

7 min

Deploy an Optimizely Content Management System (CMS) application to Windows servers using dotnet publish. The published output contains all required files and can be copied directly to one or more target servers — no separate Optimizely installation is needed.

To host the application on IIS, see Microsoft Host ASP.NET Core on Windows with IIS.

Deploy a site

The following procedure shows how to deploy an Optimizely site from development to production. You can automate this using the dotnet command or other tools.

You need three artifacts to bring over to the production server:

Site – the published application output (from dotnet publish).

SQL Server database – stored content and so on.

Application Data – media BLOBs, search index. These are files normally stored in App_Data.

Note The following steps assume you have an existing site and familiarity with IIS and SQL Server Management Studio.

1. Create the deployment artifacts

Run dotnet publish from your project directory to produce a deployment-ready output folder:

dotnet publish -c Release -o ./publish

This restores NuGet dependencies, builds the project, and outputs all required files to the ./publish folder.

If your project uses files in the App_Data folder (such as media BLOBs or search indexes), copy them into the publish output manually or include them in your project file so they are published automatically.

2. Deploy the artifacts on the target server

Note The following steps are performed on the target server and assumes you have moved the artifacts created in the previous section to the new server. The web server should have IIS and the .NET 8 Hosting Bundle installed. You also need SQL Server Management Studio to connect to the database server.

Attach the database. See Attach a database on MSDN. To complete this step, move the database files from the App_Data folder to the designated data folder for Microsoft SQL Server. You can also use backup or restore to attach a database. See Backup and restore of SQL server databases on MSDN.

Create a new SQL Login:

Right-click on the Security node and select New > SQL Login.

Select SQL Server Authentication.

Unselect User must change password at next login.

Under User Mapping, select the database and make sure the user is a member of the db_owner group.

On the web server, create a new folder for your site (for example c:\inetpub\Site1), and copy the contents of the deployed site.

Open Internet Information Services Manager and connect to the web server.

Create a new IIS site:

Right-click the Sites node.

Select Add Website.

Set the Physical path to the published app's root folder (the folder containing the generated web.config).

Update the EPiServerDB connection string in appsettings.json with connection details to the database (server, database, SQL login, and password).

Note For security and performance reasons always move media BLOBs to a folder outside the application root (as described in the next section), either on a fileshare or a local folder. Storing BLOBs in the App_Data folder is only designed for development purposes.

3. Add load-balancing support

This section describes how to enable load-balancing, configure remote events, and external storage of BLOBs (files on a fileshare). The example uses the Azure service bus and the default provider for storage of BLOBs.

Note Use the dedicated Azure Service Bus provider.

Move the Blob subfolder of the App_Data folder to a shared server, such as the database server, and then share the folder. Give access rights for the share and the folder to the user running the Application Pool for the site in Windows.

Edit appsettings.json and add configuration for the file BLOB providers. Make sure the Path property points to the correct path of the shared folder in step 1:

{
  "EPiServer":{
    "Cms":{
      "FileBlobProvider":{
        "Path": "\\dbserver\blobs"
      }
    }
  }
}

Clear the browser cache and test the setup by browsing the site. Images on the site should work as before but now are delivered from the shared location.

Configure the default provider for remote events by configuring the endpoints. The site is ready to be load-balanced.

Copy the site folder to a second server and create a site in IIS with the same settings as the previous server. No configuration changes are required.

Test remote events by logging in to one of the servers and publishing changes to a page. The published changes appear on the other server. Use the search functionality from both servers to verify it was configured correctly.

A hosting provider can help you load-balance incoming traffic between the servers. You also can use other software load-balancers such as HAProxy, Network Load Balancing (NLB), or Application Request Routing (ARR).

Note The core parts of CMS do not use Session State, but some functionality does, such as certain audience criteria. If your load-balanced setup requires session state, use sticky sessions (session affinity) on your load balancer, or configure a distributed session provider.

If you are hosting on Optimizely Digital Experience Platform (DXP) or Azure App Service, enable ARR Affinity to ensure proper cache invalidation by remote events. In the Azure Portal, go to your App Service, select Configuration > General Settings, and set ARR Affinity to On.