Read-only deployments

Xperience by Kentico applications can be deployed in read-only mode, which enables zero-downtime updates to your production database and file system. Switching traffic to a read-only deployment allows you to perform Xperience updates on your production application, while continuing to serve content from a frozen snapshot of the data using a cloned database.

The read-only mode prevents all write operations to the database and Azure Blob storage, ensuring data consistency when applying updates. Once updates are complete, you can switch traffic back to the updated database without any service interruption.

Prerequisites

Before implementing support for read-only deployments, ensure your infrastructure meets the following requirements.

Private cloud

Private cloud deployments require the following infrastructure components:

Read-only mode behavior

When read-only mode is enabled, Xperience automatically restricts write operations across the entire application to prevent data modifications.

Disabled functionality

The following Xperience features are disabled or restricted when read-only mode is enabled:

Required project changes

While Xperience automatically prevents its own write operations, you must manually guard all custom code that performs database write operations. Failure to do so will result in ReadOnlyModeException errors or HTTP 503 statuses when your application runs in read-only mode.

This requirement extends to the implementations of the following live site features:

• Forms – forms automatically become non-interactive in read-only mode (elements have the disabled attribute applied). However, you may need to adjust your form styling to provide an appropriate user experience. You can also modify your pages to serve alternative content to forms when read-only mode is enabled.
• Data protection – consent management, cookie level changes.
• Membership – user registration, sign-in, profile modifications, password resets.
• Digital marketing – activity tracking, contact management, cross-site tracking.
  • Email subscription and unsubscription operations return HTTP 503 or redirect to a configured fallback page. See Email marketing fallback pages.
• Digital commerce – shopping cart operations, order creation, payment processing, inventory updates, customer account modifications.

Test your application thoroughly in a staging environment with read-only mode enabled to identify and guard all custom write operations.

Inject and use the IReadOnlyModeProvider interface to check read-only status before performing write operations.

// Provider instance obtained via dependency injection
private readonly IReadOnlyModeProvider readOnlyProvider;

if (readOnlyProvider.IsReadOnly)
{
    // Handle read-only scenarios
}

// Provider instance obtained via dependency injection
private readonly IReadOnlyModeProvider readOnlyProvider;

// Throws ReadOnlyModeException if read-only mode is enabled
readOnlyProvider.ThrowIfReadOnly();

// Perform write operations after the read-only guard clause
customInfo.Insert();

Configure read-only mode for applications

Configure read-only mode through the ReadOnlyModeOptions class in your application settings. The class follows the options pattern.

For example, you can configure the application via your appsettings.json file:

{
  "ReadOnlyModeOptions": {
    "ReadOnly": true,
    "VersioningTimestamp": "2025-01-15T14:30:00.0000000Z"
  }
}

Register the read-only mode options in your Program.cs file:

var builder = WebApplication.CreateBuilder(args);

// Register read-only mode configuration
builder.Services.Configure<ReadOnlyModeOptions>(
    builder.Configuration.GetSection("ReadOnlyModeOptions")
);

// ...

Deployment process overview

The following diagram illustrates the high-level flow of a read-only deployment:

The deployment process follows these general steps:

1. Clone the database – Use database replication, snapshotting, or similar features to create a copy of your production database while the source database remains in read-write mode. After cloning is complete, set the clone database as read-only using your database management platform (for example, Azure SQL Database portal) or SQL commands to prevent accidental modifications.

2. Enable read-only mode on the clone – Deploy the same application build (binaries) to a separate deployment slot and configure it to run in read-only mode. Set the application’s connection string to point to the cloned database and configure the VersioningTimestamp to match the timestamp when the database was cloned. This ensures blob operations retrieve versions that align with the frozen database state.

   • We recommend using managed identities for Azure Blob Storage authentication, granting the read-only application identity only read permissions to the blob storage.

3. Switch traffic to read-only instance – Update your traffic management or deployment setup to direct all incoming requests to the read-only application instance. Your live site continues serving content without interruption, but write operations are blocked.

4. Perform database updates – With traffic switched away, safely update the original production database.

   Avoid file changes during updates

   During the update:

   • Do not delete any blob storage files used by the read-only instance.
   • Do not replace or update any files managed by the system (content item assets, etc.) that are in use by the read-only instance.

   Blob versioning cannot correctly deal with such changes. Deleting or replacing files during the update of the production instance may affect or break the content being served by the read-only instance. If possible, we recommend using content synchronization to deploy file changes rather than performing full deployments.

5. Switch traffic back – After updates are complete and verified, switch traffic back to the updated production database. The application resumes normal read-write operations.

6. Discard the clone – Remove the temporary clone database and associated resources. The read-only deployment is complete.

Email marketing fallback pages

When read-only mode is enabled, email subscription and unsubscription operations cannot modify the database. To provide a better user experience, configure a fallback page that visitors see when attempting to subscribe or unsubscribe during read-only mode.

Configure fallback pages

1. Open the Channel management application in the Xperience administration.
2. Select your website channel and navigate to the Channel settings tab.
3. In the Email marketing section, locate the Fallback page for read-only mode setting.
4. Select a page to display when visitors attempt subscription operations during read-only mode.
5. Save your changes.

When a fallback page is configured, subscription and unsubscription requests redirect to this page instead of returning an error. The fallback page applies to recipient lists with a Thank you or Goodbye page from the given channel.

If no fallback page is configured, the application returns HTTP 503 to indicate the operation cannot be completed.