--- title: Deploy to the SaaS environment related: - https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/specialized-deployment-scenarios.md - https://docs.kentico.com/documentation/developers-and-admins/installation.md - https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/manage-saas-deployments.md - https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md --- > 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). > **Note:** **Minimum Xperience by Kentico version** > > The minimum Xperience by Kentico version for new projects that can be deployed to the SaaS environment is **30.11.0**. If you are using an earlier version, you need to [update](https://docs.kentico.com/documentation/developers-and-admins/installation/update-xperience-by-kentico-projects.md) your project to the latest version before deploying it to the SaaS environment. Xperience by Kentico enables you to deploy, host, and maintain Xperience websites in a Software-as-a-Service (SaaS) environment. You can deploy to multiple environments to isolate the production and non-production application instances. Kentico manages the deployment infrastructure and selected third-party services for you – such as [Microsoft Application Insights](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md#microsoft-application-insights-integration), [Cloudflare CDN](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md#cloudflare-cdn), and [Twilio SendGrid](https://docs.kentico.com/documentation/developers-and-admins/configuration/email-configuration.md#emailconfiguration-enablemanagedsendgrid). This allows you to focus on website and content development. Develop a website for deployment to the SaaS environment: 1. [Get access to your project in Xperience Portal](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md#xperienceportal-accessportal). 2. [Prepare a .NET project for deployment to the SaaS environment](#prepare-a-project-for-deployment-to-the-saas-environment). 3. [Develop](https://docs.kentico.com/documentation/developers-and-admins/development.md) and [configure](https://docs.kentico.com/documentation/developers-and-admins/configuration.md) features in your project. 4. [Deploy](#deploytothesaasenvironment-deploy) your application to the SaaS environment. 5. [Manage](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/manage-saas-deployments.md) your deployed application in Xperience Portal. ![Overview of the SaaS deployment](https://docs.kentico.com/docsassets/documentation/deploy-to-the-saas-environment/saas_deployment_diagram.png "Overview of the SaaS deployment") ## Prepare a project for deployment to the SaaS environment You can now prepare a .NET project for deployment to the SaaS environment. 1. [Install the Xperience project templates](https://docs.kentico.com/documentation/developers-and-admins/installation.md#install-project-templates-package). 2. [Create an Xperience project](https://docs.kentico.com/documentation/developers-and-admins/installation.md#create-a-project). - Use the `--cloud` parameter when [creating the Xperience project](https://docs.kentico.com/documentation/developers-and-admins/installation.md#create-a-project). This parameter ensures the necessary configuration is included: - The [Kentico.Xperience.Cloud](https://www.nuget.org/packages/Kentico.Xperience.Cloud) NuGet package - [SendGrid](https://docs.kentico.com/documentation/developers-and-admins/configuration/email-configuration.md#managed-sendgrid-integration) and [Microsoft Application Insights](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md#deploytothesaasenvironment-enableappinsights) startup configurations - A PowerShell script for [generating the deployment package](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment.md#create-a-deployment-package) and a [CD configuration file](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md#generate-cd-configuration-files) - [Storage path mapping](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/storage-path-mapping.md) configured in `Program.cs` (for [mapping of files to Azure Blob storage](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/azure-blob-storage.md#default-kentico-managed-azure-blob-storage-configuration)) 3. [Create the project database](https://docs.kentico.com/documentation/developers-and-admins/installation.md#create-the-project-database). - Generate [a developer license key](https://docs.kentico.com/documentation/developers-and-admins/installation/licenses.md#license-keys-for-saas-local-development). - Set the value of the `--hash-string-salt` parameter to the one found on the [Xperience Portal Dashboard](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md#hash-string-salt-for-the-xperience-portal-project). 4. Include the `UseKenticoCloudOriginProtection` and `UseKenticoCloud` components in the [project's middleware pipeline](https://docs.kentico.com/documentation/developers-and-admins/development/website-development-basics/configure-new-projects.md#configure-application-startup). - Call `UseKenticoCloudOriginProtection` directly after `InitKentico` to enable [origin protection](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md#origin-protection). - Use the `.IsQa()` and `.IsUat()` [extension methods](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md#environment-identification-extension-methods) to include environment-specific configuration or code - [Call](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md#microsoft-application-insights-integration) `AddXperienceCloudApplicationInsights` when building the web application - Configure cache headers for [Cloudflare CDN](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md#cloudflare-cdn) 5. Build the project. Run the following command from the project's root directory or build the project using Visual Studio. ```cmd dotnet build ``` The project is now ready for further [development](https://docs.kentico.com/documentation/developers-and-admins/development.md) and [customization](https://docs.kentico.com/documentation/developers-and-admins/customization.md). You can add content to the project or [extend](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface.md) the connected Xperience administration. The following code example demonstrates the required SaaS configuration. Ellipsis indicates breaks where other middleware may be added: ```csharp title="Program.cs - SaaS configuration" using Kentico.Web.Mvc; using Kentico.Xperience.Cloud; using Microsoft.Extensions.Hosting; using Microsoft.AspNetCore.Builder; using Microsoft.Extensions.DependencyInjection; var builder = WebApplication.CreateBuilder(args); // Required for projects that will be deployed to the SaaS environment builder.Services.AddXperienceCloudStoragePathMapping(); builder.Services.AddXperienceCloudApplicationInsights(builder.Configuration); builder.Services.AddXperienceCloudChannelRequirements(); // Required for projects that will be deployed to the SaaS environment if (builder.Environment.IsQa() || builder.Environment.IsUat() || builder.Environment.IsEnvironment(CloudEnvironments.Custom) || builder.Environment.IsEnvironment(CloudEnvironments.Staging) || builder.Environment.IsProduction()) { builder.Services.AddKenticoCloud(builder.Configuration); builder.Services.AddXperienceCloudSendGrid(builder.Configuration); builder.Services.AddXperienceCloudDataProtection(builder.Configuration); } builder.Services.AddKentico(); builder.Services.AddAuthentication(); builder.Services.AddControllersWithViews(); var app = builder.Build(); app.InitKentico(); // Enables SaaS origin protection app.UseKenticoCloudOriginProtection(); ... app.UseAuthentication(); // SaaS-specific middleware (required for SaaS deployment) app.UseKenticoCloud(); app.UseKentico(); ... // Starts the application app.Run(); ``` ## Deploy to the SaaS environment When your Xperience project is [prepared](#prepare-a-project-for-deployment-to-the-saas-environment) and [configured](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md) in a local development environment, you can deploy the application to the SaaS environment. Choose the appropriate deployment method for your scenario: - **Initial deployments**: Deploy to the SaaS environment with a [deployment package](#deploy-with-a-deployment-package). If your project includes a large amount of assets or other data, use [custom restore](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/specialized-deployment-scenarios.md#deploy-a-large-amount-of-data-during-initial-deployments) to deploy this data. - **Regular content updates**: Use [content sync](https://docs.kentico.com/documentation/business-users/content-sync.md) to deploy updates for [supported](https://docs.kentico.com/documentation/business-users/content-sync.md#supported-content) types of content (_Advanced_ license required). See [Content sync configuration](https://docs.kentico.com/documentation/developers-and-admins/configuration/content-sync-configuration.md) for configuration details. If the updated content is not supported by content sync or if the feature is not available, deploy the changes via a new [deployment package](#deploy-with-a-deployment-package). - **Application updates**: Use the [deployment package](#deploy-with-a-deployment-package) when [updating](https://docs.kentico.com/documentation/developers-and-admins/installation/update-xperience-by-kentico-projects.md) to a new version of Xperience by Kentico or when deploying new [custom features](https://docs.kentico.com/documentation/developers-and-admins/customization.md). Changing application files is only possible through this type of deployment. ### Deployment type overview When planning a deployment, consider how it affects application availability. After you deploy, you can verify the **deployment type** in **Deployment history** to see which of the three types was used: - **Live** – Your application remains fully operational throughout the deployment. Occurs when you deploy without database or storage changes. - **Offline** – Your application goes offline and displays a static page during deployment. Occurs when you deploy with database or storage changes. [Customize the offline page](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md#define-a-custom-app-offline-file) to match your brand during the downtime. - **Zero-downtime** – Your application enters [read-only mode](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md) during deployment. Occurs when you deploy with database or storage changes and [zero-downtime](#zero-downtime-deployments) enabled. ## Deploy with a deployment package Deploying to the SaaS environment with a deployment package allows you to deploy all parts of your SaaS project (application binaries, selected database data and storage assets). To deploy using this method, [create a deployment package](#create-a-deployment-package) and [ upload it to your Xperience Portal project](#upload-a-deployment-package-to-your-xperience-portal-project). > **Info:** Deployment packages do not create an exact copy of your local project in the target environment because they contain only the database objects included in your [CD repository](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md). See [Deployment overview](#deployment-overview) and [Create a deployment package](#create-a-deployment-package) for details. ### Deployment overview The following steps provide an overview of the entire lifecycle of a deployment: 1. You [install](https://docs.kentico.com/documentation/developers-and-admins/installation.md), [configure](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md) and [develop](https://docs.kentico.com/documentation/developers-and-admins/development.md) an Xperience project from a [template](https://docs.kentico.com/documentation/developers-and-admins/installation.md#available-project-templates). A project installed with the `--cloud` option contains the following: - An Xperience .NET application. - Adjustments for SaaS deployment in the application's service collection and middleware pipeline within the **Program.cs** file. - A configuration file for the [Continuous Deployment (CD)](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md) repository, used to deploy database objects. - The **Export-DeploymentPackage.ps1** PowerShell script that creates a deployment package for the project. - [Storage path mapping](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/storage-path-mapping.md) configured in `Program.cs` that maps folders containing physical files such as [content item assets](https://docs.kentico.com/documentation/business-users/content-hub/content-item-assets.md) and binary files to Azure Blob storage and local storage for development. See [Azure Blob storage](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/azure-blob-storage.md). 2. You [create a deployment package](#create-a-deployment-package) from the project. A deployment package is a ZIP archive that contains the following: - Application libraries and static files. - `$CDRepository` folder containing serialized database objects. - A specified [CD configuration](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md). - (_Optional_) `$StorageAssets` folder for physical files. 3. When you [upload](#upload-a-deployment-package-to-your-xperience-portal-project) the deployment package to the SaaS environment, it is restored in the QA environment according to the specified [CD configuration](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md). 4. When you [deploy the package to another environment](#deploy-the-package-to-another-deployment-environment), the same deployment package is applied to the selected environment and restored according to the [CD configuration](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md). - Changes in the administration interface done during testing on the previous environment will not be reflected in other environments. - Databases of different environments are completely independent and never copied between environments. They are only updated by new deployments or users performing actions in the administration interface. 5. When deploying a package to the production environment, the same deployment package is applied and restored according to the [CD configuration](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md). - See [Deploy data to the production environment](#deploy-data-to-the-production-environment) to learn how to upload content to the production environment. After deploying to each environment, the SaaS infrastructure performs a slot swap to replace the currently running application with the newly deployed version. The swap includes a [status validation check](#swap-status-validation) to verify that the application started correctly. > **Note:** **Notes** > > - Currently, the **maximum size of the deployment package is 2 GB**. Some binary files, such as content item assets, are bundled in the deployment package. If you need to deploy more data during initial deployments (e.g., when [upgrading](https://docs.kentico.com/documentation/developers-and-admins/upgrade-to-xperience-by-kentico.md) to Xperience by Kentico), use [custom restore](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/specialized-deployment-scenarios.md#deploy-a-large-amount-of-data-during-initial-deployments). > - It is essential to consider what [CD configuration](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md) to be used with each deployment package. You can [exclude objects](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/configure-ci-cd-repositories.md) from the CD repository to limit what objects are restored in the SaaS environment. You can also specify a [CD restore mode](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md#cdrestoremode) used to restore the CD repository. > - When deploying to a SaaS environment containing an existing deployment, the Xperience version that you deploy **cannot be lower** than the version in the target environment. You can only deploy the same or newer version. > - Non-production environments (_QA_ and _UAT_) only serve to test the functionality of your project. Any data or content edited in these environments **will not** be transferred during deployment to the _Production_ environment. > - After promoting a build to the _Production_ environment, production data can be added. Use [workflows](https://docs.kentico.com/documentation/developers-and-admins/configuration/workflows.md) to prevent incomplete data from appearing publicly. > - Only the latest deployed package can be promoted to the next environment. ### Create a deployment package A deployment package is a ZIP archive with application libraries and static files, and a _$CDRepository_ folder with serialized database objects, and optionally a _$StorageAssets_ folder for physical files. Follow the procedure to build your application and create a deployment package: 1. Use [Continuous Deployment](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md) to serialize database objects to the file system: 1. Edit the **$CDRepository/repository.config** file according to your object filtering and deployment requirements. See [Exclude objects from CI/CD](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/configure-ci-cd-repositories.md). > **Info:** You cannot adjust the location of the Continuous Deployment repository. The deployment process expects the _$CDRepository_ folder to be in the project root. 2. Prepare [migration scripts](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/ci-cd-database-migration-scripts.md) for any database changes not covered by Continuous Deployment. > **Tip:** **Run SQL scripts on the database**\ > You can use [CD migration scripts](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/ci-cd-database-migration-scripts.md) to perform SQL queries on the database of applications deployed in [SaaS environments](#deploy-the-package-to-another-deployment-environment), for example, to fix database inconsistencies. However, remember to always [create a restore point](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/manage-saas-deployments.md#create-a-manual-restore-point) before modifying the database. 3. Run the CD store command from the project's root directory: ```powershell dotnet run --no-build -- --kxp-cd-store --repository-path ".\$CDRepository" ``` > **Tip:** **Escaping the '$' character** > > When performing this action in certain command line interfaces (e.g., PowerShell running on MacOS and the default Windows Terminal), you need to escape the dollar sign (`$`) by prefixing it with the grave accent (`` ` ``). 2. Deploy any unmanaged binary files that are not part of the `$StorageAssets` directory directly to [Azure Blob storage](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/azure-blob-storage.md), as the **Export-DeploymentPackage.ps1** script will not include them in the deployment package. > **Tip:** **Copying files to Azure Blob storage** > > You can use tools like [Azure Storage Explorer](https://learn.microsoft.com/en-us/azure/storage/storage-explorer/vs-azure-tools-storage-manage-with-storage-explorer) and [AzCopy](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azcopy-blobs-copy) to _directly copy files to the Azure storage container_. > > Azure Storage Explorer works for manual operations, while AzCopy is a command line utility that you can use on an ad-hoc basis or in pipelines and scripts. If your development environment is hosted in Azure and deployed through an Azure DevOps pipeline, you can use the [Azure file copy](https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/azure-file-copy-v6?view=azure-pipelines) task. 3. Create the deployment package with the **Export-DeploymentPackage.ps1** script. > **Info:** On Windows environments, the executing account must have permissions to run PowerShell scripts from external sources: > > ```powershell > # Bypass all execution checks for the current user > Set-ExecutionPolicy Bypass -Scope CurrentUser -Force > ``` > > See [Set-ExecutionPolicy](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy) for other types of permission levels. - Refer to the list of parameters before running the script. ```powershell .\Export-DeploymentPackage.ps1 -AssemblyName "DancingGoat" ``` - `-AssemblyName` – the name of the main web application assembly used during project publishing. - The value **must be equal** to the [assembly name](https://docs.microsoft.com/en-us/dotnet/api/system.reflection.assemblyname?view=net-6.0) of the Xperience project (by default, the assembly name is equal to the project _.csproj_ file name without an extension). - _(Optional)_ `-OutputPackagePath` – the full path where the deployment package will be exported. Must include the package file name and extension. - For example, `./DeploymentPackage.zip`. - When omitted, the deployment package **DeploymentPackage.zip** is exported to the directory from which the script was executed. - _(Optional)_ `-KeepProductVersion` – by default, the deployment package is created with a **Build number** equal to the source project's package version, suffixed with the export date and time in format '_yyyyMMddHHmm_'. - Add this parameter if you wish to exclude the date and time from the **Build number**. - The **Build number** is displayed in the **Deployment history** within Xperience Portal. - _(Optional)_ `-StorageAssetsDeploymentMode [-Create] [-CreateUpdate]` – determines whether the export preserves or overwrites the storage assets already present in [Azure Blob storage](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/azure-blob-storage.md): - When omitted, the `-Create` mode is used, and existing storage assets will not be overwritten and only new assets are added. - Use the `-CreateUpdate` parameter to allow overwriting of existing storage assets. > **Note:** If your deployment package contains [media library files](https://docs.kentico.com/documentation/business-users/media-libraries/manage-media-files.md), the `StorageAssetsDeploymentMode` value must match the `RestoreMode` element value in the CD configuration file. See [Reference - CI/CD object types](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/reference-ci-cd-object-types.md#content-management). - _(Optional)_ `-ZeroDowntimeSupportEnabled` – marks the deployment package as zero-downtime ready. Include this parameter if your application code supports [read-only mode](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md). When a zero-downtime ready package is deployed to an environment that already contains code configured to support read-only mode, the deployment will be executed as a [zero-downtime deployment](#zero-downtime-deployments). The deployment package is now created, and you can deploy to the SaaS environment by [uploading the deployment package to your Xperience Portal project](#upload-a-deployment-package-to-your-xperience-portal-project). ### Upload a deployment package to your Xperience Portal project Once you have [created a deployment package](#create-a-deployment-package), trigger the deployment to the **QA** environment by uploading a deployment package to your Xperience Portal project directly from [Xperience Portal](#upload-a-deployment-package-from-xperience-portal) or programmatically using [Xperience Portal API](#upload-a-deployment-package-using-xperience-portal-api). > **Info:** Uploading a deployment package to Xperience Portal is unavailable during [scheduled Xperience Portal project maintenance](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md#schedule-maintenance-of-xperience-portal-projects) and initial project creation. > **Note:** The deployment package is currently limited by a **maximum size of 2 GB**. If you need to deploy more data during initial deployments (e.g., when [upgrading](https://docs.kentico.com/documentation/developers-and-admins/upgrade-to-xperience-by-kentico.md) to Xperience by Kentico), use [custom restore](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/specialized-deployment-scenarios.md#deploy-a-large-amount-of-data-during-initial-deployments). #### Upload a deployment package from Xperience Portal 1. [Access your Xperience Portal project](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md#xperienceportal-accessportal). 2. Navigate to the **Deployments** application. 3. Under the **QA** environment, select **Upload package**. - Users in **DevOps Engineer** or **Tenant Administrator** [roles](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal/reference-xperience-portal-user-roles.md) can also upload deployment packages directly to other non-production environments, or even directly to the _PROD_ environment in extraordinary circumstances. See [Specialized SaaS deployment scenarios](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/specialized-deployment-scenarios.md#deploy-emergency-fixes-to-the-saas-environment). 4. Choose a valid deployment package (a ZIP archive with a maximum size of 2 GB) and select **Upload**. You will be redirected to the **Deployments** application after the upload is complete. 5. The progress of any current deployments can be tracked in the **Deployment progress** section, where you can check the status of the deployment. After the deployment is completed, you can review it in the **Deployment history** section. After the deployment finishes, your site is ready and running in the **QA** (or another selected) environment. Access the deployed application with the URL displayed under the selected environment section in the **Deployments** application in your Xperience Portal project. To debug the deployment, see the [deployment logs](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/manage-saas-deployments.md#deployment-logs) under the **Deployment history** section. #### Upload a deployment package using Xperience Portal API You can upload the deployment package programmatically by sending a POST request authenticated with your [Personal access token (PAT)](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md#xperienceportal-pat) to the _deployment_ Xperience Portal API endpoint: 1. Generate a [Personal access token (PAT)](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md#xperienceportal-pat) and store it in a local file. 2. Get your `PROJECT_GUID` in [Xperience Portal](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md) Dashboard, in the **Project info** section, or from any URL when accessing Xperience Portal, for example, _https://xperience-portal.com/\/dashboard_. 3. Send a POST request to the _deployment_ API endpoint. You can use the following PowerShell or cURL examples: ```powershell title="Upload using PowerShell" # Due to a PowerShell issue, we recommend disabling the progress bar to boost the performance significantly. # See https://github.com/PowerShell/PowerShell/issues/2138 for more information. # Disable the progress bar $ProgressPreference = 'SilentlyContinue' # Upload the deployment package $headers = @{ Authorization = "Bearer " } Invoke-RestMethod -Uri https://xperience-portal.com/api/deployment/upload//qa -Method Post -InFile -ContentType "application/zip" -Headers $headers # Enable the progress bar $ProgressPreference = 'Continue' ``` ```powershell title="Upload using cURL" curl -X POST -T -H 'Content-Type: application/zip' -H 'Authorization: Bearer ' https://xperience-portal.com/api/deployment/upload//qa ``` - Users in **DevOps Engineer** or **Tenant Administrator** [roles](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal/reference-xperience-portal-user-roles.md) can also upload deployment packages directly to other non-production environments, or even directly to the _PROD_ environment in extraordinary circumstances. See [Specialized SaaS deployment scenarios](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/specialized-deployment-scenarios.md#deploy-emergency-fixes-to-the-saas-environment). 4. Navigate to the **Deployments** application. 5. Allow a few minutes for the deployment progress to be displayed in the **Deployment history** section, where you can check the deployment progress. After the deployment finishes, your site is ready and running in the **QA** environment. Access the deployed application with the URL displayed under the **QA** environment section in the **Deployments** application in your Xperience Portal project. To debug the deployment, see the [deployment logs](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/manage-saas-deployments.md#deployment-logs) under the **Deployment history** section. ### Deploy data to the production environment Keep the following in mind when performing standard deployments to production: - Deployment packages are intended for deploying the project only with initial data and content: - Website/email/headless channels, content types representing the content model, page tree structure, basic emails, essential content items - Assets that are essential for the design and branding, such as a favicon, background images, graphics, icons, and company logos - Large binary files should be uploaded directly to the production environment: - All marketing assets, images, videos, large documents - If your deployment package would exceed 2 GB during initial deployments, use [custom restore](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/specialized-deployment-scenarios.md#deploy-a-large-amount-of-data-during-initial-deployments) to deploy the database and [storage](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/azure-blob-storage.md) assets. - If you use Xperience by Kentico to manage content imported from external sources, it is recommended to import the content directly to the production or staging environment. The [Content sync](https://docs.kentico.com/documentation/developers-and-admins/configuration/content-sync-configuration.md) feature allows you to set up content staging for SaaS environments. See [Content staging best practices](https://docs.kentico.com/documentation/developers-and-admins/configuration/content-sync-configuration.md#content-staging-best-practices) to learn which environments are suitable for staging. ### Zero-downtime deployments Zero-downtime deployments update your live site without service interruptions. SaaS deployments use Kentico-managed infrastructure (deployment slots, database replication, blob versioning) that automatically switches your application to [read-only mode](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md) to maintain data consistency. > **Info:** Zero-downtime deployments require a version of Xperience by Kentico 31.0.2 or higher, an updated infrastructure and [read-only mode](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md) support in your application code. Your application must be configured to handle read-only mode before zero-downtime deployments can be used. Without proper read-only mode implementation, zero-downtime deployments will not function correctly. > > See [Read-only deployments](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md) for detailed information about read-only mode behavior, required code changes, and disabled functionality. To enable zero-downtime deployments for your project: 1. Update your **Export-DeploymentPackage.ps1** script to the latest version that includes the `-ZeroDowntimeSupportEnabled` parameter. If your project was created before this feature was available, replace your existing script with the latest version: [Export-DeploymentPackage.ps1](https://docs.kentico.com/docsassets/documentation/deploy-to-the-saas-environment/Export-DeploymentPackage.ps1). 2. Configure your application code to support [read-only mode](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md). This is a mandatory prerequisite. Your code must: - Prevent custom write operations when read-only mode is active (check [required project changes](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md#required-project-changes) for details) - Handle [disabled functionality](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md#disabled-functionality) during read-only mode (forms, activity tracking, contact management, etc.) See [Read-only deployments](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md) for complete implementation instructions. 3. Mark your deployment package as zero-downtime ready when [creating the deployment package](#create-a-deployment-package) using the **Export-DeploymentPackage.ps1** script with the `-ZeroDowntimeSupportEnabled` parameter. 4. Deploy the package to an environment. Once an environment contains code supporting zero-downtime deployments, all subsequent deployments of packages marked as zero-downtime ready will be executed as zero-downtime deployments. Your project is now configured for zero-downtime deployments. When you deploy packages marked with the `-ZeroDowntimeSupportEnabled` parameter to an environment containing zero-downtime ready code, the SaaS infrastructure automatically executes the deployment in read-only mode, eliminating service interruptions during updates. > **Note:** **Notes** > > - The first deployment with the `-ZeroDowntimeSupportEnabled` flag enables zero-downtime infrastructure but uses standard deployment. Only subsequent deployments with the flag will be zero-downtime. > - When you deploy a package without the `-ZeroDowntimeSupportEnabled` flag to an environment with existing zero-downtime ready code, the feature is disabled and standard deployment is used. Subsequent deployments without the flag will also use standard deployment. > - For [private cloud](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-private-cloud.md) deployments, see [Read-only deployments](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md) for manual infrastructure setup and deployment process. ### Swap status validation As the final step of the deployment, the SaaS infrastructure performs a slot swap to replace the currently running application with the newly deployed version. During the swap, the deployment process sends a warmup request to the application and checks that it responds with one of the following allowed HTTP status codes: | Status code | Meaning | | ----------- | ----------------------------- | | 200 | OK | | 201 | Created | | 202 | Accepted | | 203 | Non-Authoritative Information | | 204 | No Content | | 301 | Moved Permanently | | 302 | Found | | 303 | See Other | | 304 | Not Modified | | 307 | Temporary Redirect | | 308 | Permanent Redirect | | 401 | Unauthorized | | 403 | Forbidden | If the application returns a different status code (for example due to a startup error or a middleware that returns an unsupported status), the swap fails and the entire deployment is marked as failed. > **Note:** If your application uses IP-based access restrictions (e.g., firewall rules, IP allowlists, or similar mechanisms), make sure that blocked requests return one of the allowed status codes listed above (typically **401** or **403**). If blocked requests return a different status code (e.g., **429** or **503**), the warmup check treats the application as broken and the deployment fails. ## Deploy the package to another deployment environment The following SaaS **deployment environments** are available, depending on your [service plan](https://docs.kentico.com/documentation/developers-and-admins/saas/saas-service-plans.md): - **QA** – A QA engineer tests the deployed application in the QA environment and deploys the deployment package to the UAT ([User Acceptance Testing](https://en.wikipedia.org/wiki/Acceptance_testing#User_acceptance_testing)) environment, if available. - **UAT** – A project manager tests the final functionality in the UAT environment and promotes the deployment package to the production (PROD) environment. > **Info:** The UAT environment is only available for **Custom** [service plans](https://docs.kentico.com/documentation/developers-and-admins/saas/saas-service-plans.md). - **STG** – An environment where editors and other staff can prepare content, and then transfer it to the production (PROD) environment using [content sync](https://docs.kentico.com/documentation/business-users/content-sync.md). Staging environments are designed to be nearly identical to production environments in most aspects, such as performance, availability, backup policies, and the option to set custom domains. See [Content staging best practices](https://docs.kentico.com/documentation/developers-and-admins/configuration/content-sync-configuration.md#content-staging-best-practices). > **Info:** The STG environment can optionally be purchased for any [service plan](https://docs.kentico.com/documentation/developers-and-admins/saas/saas-service-plans.md). - **CUST** – A custom production environment with a purpose agreed for your project, for example an additional staging environment. Like STG and PROD, custom environments support custom domains. > **Info:** The CUST environment is only available for **Custom** [service plans](https://docs.kentico.com/documentation/developers-and-admins/saas/saas-service-plans.md). - **PROD** – A live production environment. Use this environment to deploy a tested iteration of your application. After [deploying a deployment package](#deploy-with-a-deployment-package) to the QA environment, you can deploy it to another environment in [Xperience Portal](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md): 1. Navigate to the **Deployments** application. 2. Select **Deploy to**, located under the environment where the package is currently deployed. A drop-down menu is displayed. 3. Select the environment where you want to deploy the package. 4. Select whether you want to deploy the package immediately or [schedule a production deployment for a later date](#schedule-a-production-deployment-for-a-later-date). > **Info:** The SaaS environment checks if the production deployment causes downtime. Most deployments are seamless and incur no downtime, especially if the deployment package is marked as [zero-downtime ready](#zero-downtime-deployments). However, if the system discovers downtime would occur, you can [schedule a production deployment for a later date](#schedule-a-production-deployment-for-a-later-date). It is also recommended to define a custom [App Offline page](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md#define-a-custom-app-offline-file). 5. Allow a minute for the deployment process to be displayed in the **Deployment progress**. > **Note:** Repeating the procedure triggers a new deployment. 6. Check the **Deployment history** section to verify the package is deployed to the environment you selected. Note that the deployment may be queued and will begin once previous SaaS processes have finished. > **Info:** If you need to debug a failed deployment, see the [deployment logs](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/manage-saas-deployments.md#deployment-logs) in the **Deployment history** section. Your application is now deployed and running in the selected environment. ### Schedule a production deployment for a later date Deployment to a production or staging environment can cause application downtime, impacting the customer experience. [Zero-downtime deployments](#zero-downtime-deployments) minimize or eliminate downtime, but may not be suitable for all deployment scenarios. When you trigger a deployment with the **Deploy to** action, the SaaS environment reports if the deployment causes downtime. You can decide whether to proceed with the deployment, schedule the deployment, or cancel the deployment. Select the **Cancel scheduled deployment** button in the **Deployments** application to cancel the scheduled deployment. > **Note:** Scheduling the production deployment blocks instant production/staging deployment and additional scheduling. > > Cancel the existing scheduled deployment in the **Deployments** application to enable these actions. If the scheduled deployment fails to start, the project's **Tenant administrators** and the user that scheduled the deployment receive a notification email\*\*,\*\* and the production/staging environment is unaffected. > **Info:** If the scheduled deployment starts successfully, but the deployment pipeline fails, users will not receive a notification email. > > See the [deployment logs](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/manage-saas-deployments.md#deployment-logs) in the **Deployment history** section to debug the failed deployment. ## Specialized deployments Follow these specialized scenarios when you need to deploy a large amount of initial data or apply emergency fixes in the SaaS environment: - [Deploy a large amount of data during initial deployments](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/specialized-deployment-scenarios.md#deploy-a-large-amount-of-data-during-initial-deployments) - [Deploy emergency fixes to the SaaS environment](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/specialized-deployment-scenarios.md#deploy-emergency-fixes-to-the-saas-environment)