---
title: Deploying and hosting ASP.NET Core applications
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

This page covers hosting requirements and basic deployment scenarios for the ASP.NET Core live site application. For hosting requirements of the Xperience administration application (running ASP.NET Web Forms), see [System requirements](https://docs.kentico.com/13/installation/system-requirements.md).

## Hosting requirements

- ASP.NET Core Runtime for [.NET 8](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) through [.NET 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed on the hosting machine.
- A hosting environment [supporting .NET 8](https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/?view=aspnetcore-8.0) or later.
- Hosting plan parameters:
  - **Minimum**: 4 GB memory (RAM), 200 MB database size
  - **Recommended**: 8 GB memory, 1 GB database size

> **Info:** **Note**: The recommended hosting parameters depend on the scale and implementation details of each project. Very large or heavily trafficked websites may have significantly higher requirements. For virtual hosting servers, the listed values refer to the memory capacity available for your web application, not the server's overall resources.

## Publishing and deploying projects

This section describes a basic publishing and deployment process for Xperience ASP.NET Core applications.

1. Set up a hosting environment and publishing process for the project. For details, refer to Microsoft's documentation for your chosen hosting method and platform (on-premise Windows or Linux server, Azure, Docker, etc.): [Host and deploy ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy)

   > **Note:** **Handling Xperience-specific static files**
   >
   > Carefully consider the impact your chosen publishing process may have on static files synchronized between the live site and administration applications. These resources – [media library](https://docs.kentico.com/13/managing-website-content/working-with-files/media-library-files.md) files, [smart search](https://docs.kentico.com/13/configuring-xperience/setting-up-search-on-your-website/using-locally-stored-search-indexes/creating-local-search-indexes.md) indexes, etc. – stored in the _\~/SiteCodeName_ folder in live site application's root directory are synchronized with the [connected administration application](https://docs.kentico.com/13/developing-websites/developing-xperience-applications-using-asp-net-core/starting-with-asp-net-core-development.md) using the [web farms](https://docs.kentico.com/13/configuring-xperience/setting-up-web-farms.md) feature.
   >
   > The publishing process must account for these files and ensure they remain consistent with the rest of the environment, **especially** when publishing the application to production deployments. Otherwise, you may encounter missing images, broken search functionality and other issues on the live site. For example, you can use the [content staging](https://docs.kentico.com/13/deploying-websites/content-staging.md) feature to ensure that your development and production environments remain synchronized. Alternatively, set up your publishing process so that it does not modify the _\~/SiteCodeName_ folder on the target deployment.

   - Make sure that your site and the hosting environment are correctly configured according to [Configuring cookie SameSite mode](https://docs.kentico.com/13/developing-websites/working-with-cookies/configuring-cookie-samesite-mode.md).
   - If deploying to a Linux-based hosting environment, see [Linux deployments - known issues](#linux-deployments-known-issues).

2. Deploy your Xperience database. You can choose between the following approaches:

   1. Restore a database backup on your hosting SQL server, and manually update the connection string of both projects.\
      – OR –
   2. Install a new database on your hosting SQL server and use the Xperience [Export/import feature](https://docs.kentico.com/13/deploying-websites/exporting-and-importing-sites.md)  to transfer the site:
      1. Delete the connection string from the configuration files of the live site and administration projects.
      2. Open the **Sites**  application on your local development instance and click **Export site** () next to the site that you want to deploy.
      3. Go through the [Site export wizard](https://docs.kentico.com/13/deploying-websites/exporting-and-importing-sites/exporting-sites.md).
         - The system saves the export package into the _\CMS\CMSSiteUtils\\**Export**_ folder.
      4. Copy the exported package into the _\CMS\CMSSiteUtils\\**Import**_ folder on the **hosting server**.
      5. Open the administration interface of the deployed project in a browser.
         - The application automatically opens the [Database installation wizard](https://docs.kentico.com/13/installation/additional-database-installation.md).
      6. Create a new Xperience database on your hosting SQL server.
      7. At the end of the Database installation wizard, choose to import your existing site (from the previously exported package).
      8. Copy the new connection string from the web.config of the deployed administration project into the configuration file of your live site project.

   > **Note:** **Database server time zones**
   >
   > If possible, use the same time zone for both your local environment and the production server hosting your database. Otherwise you may encounter time shift problems with the deployed data, for example in the settings of [scheduled tasks](https://docs.kentico.com/13/configuring-xperience/scheduling-tasks.md).
   >
   > If you cannot synchronize the time zones, we recommend that you verify and reconfigure the timing settings of scheduled tasks after the deployment.

3. (Optional) See [Hosting configuration notes](#hosting-configuration-notes) for additional configuration you should consider for the hosting environment.

### Publishing the project's site folder

The project's site folder is used to store static files from [media libraries](https://docs.kentico.com/13/managing-website-content/working-with-files/media-library-files.md) and other site-specific files. It is by default located in the root of the project on the filesystem (_\~/_). Since the folder is not by default included in the project, it is not published when running _dotnet publish_.

To include the contents of the folder when publishing, add the following snippet into the Core project's _.csproj_ file:

```csharp

<ItemGroup>
  <Content Include="SiteFolderName\**">
    <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
  </Content>
</ItemGroup>

```

## Hosting configuration notes

### Automating application start

The Xperience ASP.NET Core application runs as a standard console application. The application's hosting environment needs to ensure the application starts after the server reboots, the application is restarted (e.g., via the administration application in **System** -> **General** -> **Restart all web farm servers**), or an unexpected error that causes the application to crash occurs.

Automating starts and restarts is typically done using process managers such as [Internet Information Services](https://www.iis.net/) for Windows-based servers, or [Nginx](https://www.nginx.com/) for Linux. Refer to the [Microsoft documentation](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/?view=aspnetcore-3.1#set-up-a-process-manager) for guides on how to configure process managers based on your hosting environment.

### Handling errors during application initialization

The Xperience ASP.NET Core integration package does not provide any support for error handling or recovery from errors that occur during application initialization. If an error occurs during the initialization process (e.g., the application's database experiences an outage), the hosting environment needs to ensure application recovery. For example, by terminating the application and attempting a restart during subsequent requests.

Refer to Microsoft [documentation sources](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/) for recommended ways of handling error recovery during application initialization under various hosting types.

For example, when hosting the application under [Internet Information Services](https://www.iis.net/) (IIS) servers, you can use the [CaptureStartupErrors](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/host/web-host?view=aspnetcore-3.1#host-configuration-values) web host configuration option:

```csharp title="Program.cs"

using Microsoft.Extensions.Hosting;

...

public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder
                        .UseIISIntegration()
                         // When set to false, errors during startup result in the host exiting (the process terminating)
                        .CaptureStartupErrors(false)
                        .UseStartup<Startup>();
                });

```

### Enabling static web assets in non-Development local environments

The Xperience application must have static web assets enabled to correctly load script files and other resources. When running Xperience locally (e.g., using the built-in Visual Studio IIS Express server), static web assets are enabled by default in the [Development](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.hosting.environments.development) environment. However, if you are using a different environment, e.g., by setting ASPNETCORE\_ENVIRONMENT to a different value in the _Properties/launchSettings.json_ file, you need to enable static web assets – call [UseStaticWebAssets](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.hosting.webhostbuilderextensions.usestaticwebassets) on [IWebHostBuilder](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.hosting.iwebhostbuilder) in _Program.cs_.

```csharp title="Program.cs"

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Hosting;

...

public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder
                        .UseIISIntegration()
                        .UseStaticWebAssets() // Enables static web assets
                        .UseStartup<Startup>();
                });

```

### Hosting the application under a virtual directory outside of IIS

If you wish to host the Core application in a virtual directory outside of an IIS server, you need to manually configure the application's base virtual path:

1. Add the [UsePathBase middleware](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.builder.usepathbaseextensions.usepathbase) to the application's middleware pipeline. Pass the full path from the server root to the application's virtual directory, **including** the leading '_/_' character, as the method's argument.
   - We recommend adding this middleware to the pipeline as soon as possible. For the earliest possible inclusion into the pipeline, use a [startup filter](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/startup#extend-startup-with-startup-filters):

     ```csharp title="AddVirtualDirectoryToBasePathStartupFilter.cs"

     public class AddVirtualDirectoryToBasePathStartupFilter : IStartupFilter
     {
         public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
         {
             return builder =>
             {
                 // Sets the root-relative application path to '<ServerRoot>/app'
                 builder.UsePathBase("/app");
                 next(builder);
             };
         }
     }

     ```
2. Set the **ApplicationPath** property of the **SystemContext** class to the same path you provided to the **UsePathBase** middleware. Set the value at the beginning of the application's **Configure** method, before other Xperience-specific middleware sensitive to this configuration is run.

   ```csharp title="Application's startup class"

   using CMS.Base;
   ...

   public void Configure(IApplicationBuilder app, IConfiguration configuration)
   {
       // Sets the root-relative application path to '<ServerRoot>/app'
       SystemContext.ApplicationPath = "/app";
       ...
   }

   ```

The application is now configured to run in the specified virtual directory.

## Known issues

### Images resized via the API not displaying on the live site

On some deployments (Windows Server Core or Nano, specific Linux distributions), you may encounter an issue where [resized images](https://docs.kentico.com/13/developing-websites/retrieving-content.md) (e.g., from [media libraries](https://docs.kentico.com/13/developing-websites/retrieving-content/displaying-content-from-media-libraries.md#getting-media-file-urls)) do not render.

This is caused by a missing implementation of the [GDI+](https://docs.microsoft.com/en-us/windows/win32/gdiplus/-gdiplus-gdi-start) library (not included by default on some distributions).

On Linux, you need to manually install the missing library:

```bash

sudo apt-get install libgdiplus

```

Affected Windows distributions do not have a clean workaround. We recommend switching to a distribution that contains an implementation of the GDI+ library (_gdiplus.dll_) by default.

## Linux deployments

### Filesystem behavior and limitations

> **Info:** This section applies from [Kentico Xperience Hotfix 13.0.10](https://devnet.kentico.com/download/hotfixes) onwards. In previous versions, Linux deployments contained filesystem-related issues that prevented certain features from working correctly.

Hotfix 13.0.10 introduced a new approach for detecting absolute and relative paths on Unix-like filesystems. Since both relative and absolute paths on Unix-like filesystems begin with a forward slash ('/'), Xperience cannot determine whether a path segment is absolute or relative. For example, this is important when determining the location of media library content, or in general whenever it is necessary to prepend relative path fragments with the physical path to the web application.

By default, the system uses the following process to detect the path type:

1. The system receives a path fragment. For example: _/media/mediagallery/image.jpg_
2. If the path is prefixed with the physical path to the web application (stored in the _SystemContext.WebApplicationPhysicalPath_ property), the path is treated as **absolute**. If not, the system checks whether the first two folders in the path exist on the filesystem **starting from the root** (taking the first two folders produced the least false positives during extensive testing). For the example above, the system tests for the existence of: _/media/mediagallery_
3. If the first two folders in the path do not exist, the path is treated as **relative**. If the first two folders exist, the path is treated as **absolute**.

You can override this behavior by adding the **CMSUnixRootedPathPrefixes** configuration key to the Core application. Adding the key **disables** the process described above. Instead, the key needs to contain a semicolon-delimited list of all path prefixes (e.g., _/etc/_, _/var/_, _/mnt/share/_) the system should treat as absolute. The list must be case-sensitive.

```csharp title="appsettings.json"

{
    "CMSUnixRootedPathPrefixes": "/etc/;/var/;/mnt/share/"
}

```

> **Note:** Only use the **CMSUnixRootedPathPrefixes** configuration key if your project contains non-standard [file system mapping](https://docs.kentico.com/13/custom-development/working-with-physical-files-using-the-api/configuring-file-system-providers.md) (e.g., for media library files), or if you encounter issues with the built-in path type detection mechanism. The default functionality covers all expected cases and filesystem configurations.

Moreover, Xperience does not validate permissions on Linux filesystems.

### Linux deployments – known issues

#### Images resized via the API not rendered on the live site

By default, Linux deployments of Xperience ASP.NET Core live site projects cannot display resized images (e.g., [retrieved from media libraries](https://docs.kentico.com/13/developing-websites/retrieving-content/displaying-content-from-media-libraries.md) or as [page attachments](https://docs.kentico.com/13/developing-websites/retrieving-content/displaying-page-attachments.md)).

The _System.Drawing.Common_ package used for image processing is deprecated for Linux environments (see [System.Drawing.Common only supported on Windows](https://learn.microsoft.com/en-us/dotnet/core/compatibility/core-libraries/6.0/system-drawing-common-windows-only)). To resolve the issue, developers need to apply [hotfix 13.0.107](https://devnet.kentico.com/download/hotfixes) or newer and install the [Kentico.Xperience.ImageProcessing.KX13](https://www.nuget.org/packages/Kentico.Xperience.ImageProcessing.KX13) NuGet package into the live site project. The package uses the [SkiaSharp](https://www.nuget.org/packages/SkiaSharp) library to process images.