Warm up sites

9 min

Note Sites behind a login may experience a 403/400 error on deployments during warm up because the status cannot be confirmed with a log-in redirect. The warmup validation runs during deployments regardless of the options configured in the EPiServer.CloudPlatform.Cms.Warmup options.

Removing the Everyone role from a root or home page may trigger authentication checks, as the system must verify user roles against defined access rights.

See information on scaling up an app.

Warm-up occurs when a Web App receives requests, such as pre-populating in-memory cache before it receives production traffic. This process makes code deployments to production and scaling up or out as seamless as possible. Warm-up also runs on each instance that auto-scaling adds or that health monitoring replaces. See Auto-scaling and instance health.

Optimizely's deployment automation engine attempts to configure a warm-up section automatically during deployments:

Issuing a web request to the start page.

Parsing the resulting HTML output to find relative links on the site's start page.

The system performs this for each unique hostname bound to the site. The system automatically adds this warm-up package as a dependency from EPiServer.CloudPlatform.Cms, a required package to run in DXP

Warm up the application

To warm up the application, EPiServer.CloudPlatform.Cms.Warmup parses homepage links and follows them with a request. You can configure a limited number of options on WarmupOptions.

"EPiServer": {
  "CMS": {
    "WarmupOptions": {
      "Disable": "false",
      "FollowLinkLevel": 1,
      "WaitingForStartupTimeout": "0:3:0",
      "StartupWaitingInterval": "0:3:0",
      "TotalWarmupTimeout": "0:10:0", //Available on v1.8.0 forward
      "RequestTimeout": "0:0:1:0",
      "MaxNumberParallelRequests": 10
      "AdditionalPaths": [          
  			"/en/alloy-plan",          
  			"/en/alloy-save"
			]
    }
  }
}

public void ConfigureServices(IServiceCollection services) {
  services.Configure<WarmupOptions>(x => {
    x.Disable = false;
    x.FollowLinkLevel = 1;
    x.WaitingForStartupTimeout = TimeSpan.FromSeconds(180);
    x.StartupWaitingInterval = TimeSpan.FromMilliseconds(10);
    x.TotalWarmupTimeout = TimeSpan.FromMinutes(10); //Available on v1.8.0 forward
    x.RequestTimeout = TimeSpan.FromMinutes(1);
    x.MaxNumberParallelRequests = 10;
    x.AdditionalPaths.Add("/en/alloy-plan");
    x.AdditionalPaths.Add("/en/alloy-save");
  });
}

Warm up the local development environment

You can trigger warmup in your local development environment. This helps expose bugs or issues before deploying to DXP and Integration, Pre-production, and Production environments.

if (_webHostingEnvironment.IsDevelopment()) {

  services.AddCmsWarmup(configure => {
    configure.Disable = false;
    configure.FollowLinkLevel = 10; // Should cover most pages?
    configure.WaitingForStartupTimeout = TimeSpan.FromSeconds(180);
    configure.StartupWaitingInterval = TimeSpan.FromMilliseconds(10);
    configure.RequestTimeout = TimeSpan.FromMinutes(1);
    configure.MaxNumberParallelRequests = 10; // Increase to speed up warmup and simulate more load
    configure.AdditionalPaths.Add("/en/alloy-plan"); // Add path to warmup that crawling won't find following links                    
  });

Note .AddCmsWarmup() implicitly triggers with .AddCloudPlatformSupport(). However, avoid triggering it in your local or development environment.

Environment-specific configuration for local development

Developers commonly need to run your Optimizely DXP application locally for development and testing. However, the service configuration for the DXP cloud environment often differs from what a local development machine requires.

Challenge: cloud dependencies

The .AddCloudPlatformSupport() extension method is the standard way to configure an application for the DXP environment. This method is a convenient meta-package registering several essential cloud services, including:

Azure Blob Storage provider for media.

Azure Service Bus for event synchronization.

The application warmup service (IWarmupService).

While this is ideal for cloud deployment, it causes errors during local development if you do not configure your machine with the necessary Azure connection strings and resources.

Solution: conditional configuration

You should conditionally register services based on the hosting environment. For local development, you can register just the warmup service using .AddCmsWarmup() without the other cloud dependencies. You can achieve this by injecting IWebHostEnvironment into your Startup.cs and checking if the environment is Development.

Example implementation

The following example shows how to configure your Startup.cs to use .AddCloudPlatformSupport() in the cloud and fall back to .AddCmsWarmup() for local development.

Inject IWebHostEnvironment into your Startup class:

// Startup.cs

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting; // Required for IsDevelopment()

public class Startup {
  private readonly IWebHostEnvironment _webHostEnvironment;

  public Startup(IConfiguration configuration, IWebHostEnvironment webHostEnvironment) {
    Configuration = configuration;
    _webHostEnvironment = webHostEnvironment;
  }

  public IConfiguration Configuration {
    get;
  }

  // ...
}

Conditionally register the services in ConfigureServices:

// Startup.cs -> ConfigureServices method

public void ConfigureServices(IServiceCollection services) {
  // ... other service registrations like AddCms()

  if (_webHostEnvironment.IsDevelopment()) {
    // For local development:
    // Register only the CMS warmup service to avoid cloud dependency issues.
    // This lets you test warmup functionality locally.
    services.AddCmsWarmup();
  } else {
    // For DXP (Integration, Preproduction, Production) environments:
    // Register the suite of DXP cloud services, which includes the warmup service.
    services.AddCloudPlatformSupport();
  }

  // ... other services
}

Summary of Services

.AddCloudPlatformSupport() – Use this for deployments to any DXP environment. It is a comprehensive method configuring blob storage, service bus, and the warmup service.

.AddCmsWarmup() – Use this only for local development when you need to test the site warmup feature without setting up and connecting to Azure Blob Storage and Service Bus.

By adopting this pattern, you can maintain a single codebase working seamlessly for both local development and deployment to the Optimizely DXP.

Note

EPiServer.CloudPlatform.Cms 1.8.0 improves the warmup health check to accurately reflect readiness during deployment. Previously, the health check would return Healthy after a fixed number of pings even if warmup had not completed, which could cause traffic to be routed to instances that were not yet ready. The health check now stays Unhealthy until the warmup process genuinely ends, with a configurable total timeout to ensure warmup cannot block a deployment indefinitely.

Customers experiencing ZDD issues can tune the TotalWarmupTimeout attribute in WarmupOptions to match their site's startup characteristics and ensure the health check signal aligns with their deployment flow expectations.