---
title: Specialized SaaS deployment scenarios
related:
  - https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment.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/deployment/read-only-deployments.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.1.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. Existing projects are not affected, but we recommend updating them to the latest version.

This page covers specialized SaaS deployment situations: [deploying a large amount of data during initial deployments](#deploy-a-large-amount-of-data-during-initial-deployments) using custom restore and [deploying emergency fixes](#deploy-emergency-fixes-to-the-saas-environment). See [Deploy to the SaaS environment](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment.md) for common deployment scenarios.

## Deploy a large amount of data during initial deployments

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), you can use custom restore to deploy a large amount of data without being restricted by the 2 GB [deployment package](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment.md#create-a-deployment-package) limit.

Custom restore enables you to transfer 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#azure-blob-storage-for-kenticos-saas) files directly to the selected environment. It is required to upload both the database and storage files. Custom restore does not provide a way to deploy application libraries, so it needs to be used in combination with a [deployment package](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment.md#deploy-with-a-deployment-package).

During the process, you first upload the data to automatically created containers in Azure Storage that are separate from your SaaS environments. When you apply the custom restore, all existing data in the target environment's database and storage is overwritten with the uploaded data, and the target environment is unavailable while the restore itself runs.

The changes introduced by a custom restore are not propagated between environments with the deployment package. Transferring them to other environments requires a custom restore for each environment.

### Perform a custom restore

> **Info:** Only **Tenant administrator** and **DevOps** roles can manage custom restore sessions (create and close sessions, revoke access) and restore to all environments.  **Developers** can restore to non-production environments (QA, UAT) and access the restore containers.

To perform a custom restore:

1. Back up your data.
   1. 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) for the target environment before starting.

2. Create a restore session.
   2\. Navigate to **Data Management** → **Custom restore**.
   3\. Select **Create session**.

   ![Create restore session](https://docs.kentico.com/docsassets/documentation/specialized-deployment-scenarios/create_restore_session.png "Create restore session")

3. Get access to restore containers.
   1. Select **Get access**.
   2. If you want to restrict access to the restore containers, specify an allowlist by entering an IP address or an IP address range and confirm with **Get access**. Otherwise, select **Get access** without entering any values.
   3. Copy both [SAS URLs](https://learn.microsoft.com/en-us/rest/api/storageservices/delegate-access-with-shared-access-signature) for the database and storage containers.

      > **Info:** **SAS URLs**
      >
      > You can't retrieve the same SAS URLs again. However, you can get new SAS URLs with **Get access**. The previously existing SAS URLs are still valid. To revoke all current SAS URLs, select **Revoke access** under **Current session**.
      >
      > Within a session, the SAS URL pairs provide access to the same containers.

4. Upload the database.
   - You can use [Azure Storage Explorer](https://azure.microsoft.com/en-us/products/storage/storage-explorer) to connect to the container:

     1. In Azure Storage Explorer, connect to the restore Azure Storage (select the type _Blob container or directory_).
     2. Select the connection through _Shared access signature URL (SAS)_.
     3. Enter the SAS URL for the database container and connect to the resource. The display name does not matter.
     4. Upload the database exported as a _bacpac_ file to the database container.

     > **Note:** **Requirements**:
     >
     > - The file must be named `db.bacpac`.
     > - The database to be restored must have the **same version** as the one currently in the environment.
     > - The database upload is required even if you only intend to update storage files (and vice versa).

5. Upload storage files.
   1. Connect to the storage container using the second SAS URL (as in the previous step).
   2. Upload the files to be stored in Azure Blob Storage.

      - For each container used in your [Azure Blob Storage configuration](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/azure-blob-storage.md#azure-blob-storage-for-kenticos-saas), upload a folder with the same name. Within that container folder, recreate each path from the [storage path mapping](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/storage-path-mapping.md) configuration and upload the corresponding contents into those locations.
        - For example, if `~/assets/contentitems` is mapped to a container, its contents go under `<container-name>/assets/contentitems/`. If you're using the [default configuration](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) with the container named `default`, the structure would be `default/assets/…`.
      - You can also obtain this structure by downloading a **Storage and files** [export](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/manage-saas-deployments.md#restore-points-and-exports) once you have deployed with this Blob storage configuration.

      > **Note:** The names of files and folders uploaded to the storage container must be fully in **lowercase**.

      - Note that the uploaded files count toward the file storage limit, which you can view on the **Dashboard**.

6. Restore to an environment.

   1. Make sure you have a backup of the target environment. The custom restore process itself cannot be undone, but you can use [restore points](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/manage-saas-deployments.md#restore-points-and-exports) to revert the changes.
   2. Once you have uploaded both the database and the storage files to be restored, you can select **Restore to environment** under **Current session**.
   3. Select the target environment where the data should be restored. The environment will be unavailable during the restore process. The database in the target environment will be replaced with the uploaded one. All storage containers in the environment will be deleted and recreated based on the uploaded data.
   4. Select **Create** to start the custom restore process.

   > **Info:** **Tenant administrator** and **DevOps** roles can restore to any environment. **Developers** can restore only to non-production environments (QA, UAT).

7. Close the session.

   1. You can see the restore in progress under **Active restores**. Once finished, it will appear under **Last completed restores**.
   2. When the restore process is complete and you no longer need to keep the data (for example, to restore it to another environment), **Close** the session.

   > **Info:** Each session expires after a week. Once a session has expired, you can no longer upload data to the containers, but you can still restore the data you uploaded previously (up to 180 days from the session creation). Only one restore session can be open at a time.

## Deploy emergency fixes to the SaaS environment

Emergency deployments allow 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) to bypass the standard deployment flow and push critical fixes or version updates directly to environments other than _QA_.

The emergency deployment process is suitable for the following situations:

- The Xperience version deployed in your _PROD_ environment is, for example, 30.0.0. In the _QA_ environment, the deployed version is 30.1.0 with some new features you are currently testing. In version 30.2.0, Kentico releases a security advisory and you want to immediately update to this version. However, your _QA_ environment is "blocked" by the tested feature.
- You have recently released a new functionality that contains an issues that impedes the usability of your application. The fix for this issue is simple, but you need to promote it to the _PROD_ environment as soon as possible. However, your _QA_ environment is "blocked" by a new feature that is already tested in this environment.

> **Note:** **Handle deployments to Production with care**
>
> Do not use emergency deployments for fixes if you are not absolutely sure that you can deploy these changes to the _PROD_ environment without first testing them on any other SaaS environment. If you have any environment other than _QA_ and _PROD_ available (e.g., _UAT_, _STG_), it is safer to deploy directly to this environment, test the fix, and then [deploy](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment.md#deploy-the-package-to-another-deployment-environment)  to _PROD_ from there.
>
> **Product versions across different environments**
>
> Keep in mind that downgrading a product version is not possible. Consider the following setup:
>
> - Product version 30.1.0 is deployed in the _QA_ environment.
> - Product version 30.2.0 is deployed in the _PROD_ environment using the emergency deployment.
>
> It is not currently possible to promote the package from the _QA_ environment to the _PROD_ environment. You need to first update the package in _QA_ to an equal or newer version than _PROD_ (30.2.0 or newer in this example).

### Deploy emergency fixes from Xperience Portal

> **Note:** **Notes**
>
> - This action is available only for 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).
> - This action may cause downtime of the target environment unless the deployment package is marked as [zero-downtime ready](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment.md#zero-downtime-deployments) and the target environment already contains zero-downtime ready code.

1. [Create](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment.md#create-a-deployment-package) the emergency deployment package. Consider using the `-ZeroDowntimeSupportEnabled` parameter if your application supports it to minimize deployment downtime.
2. [Upload the package from Xperience Portal](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment.md#upload-a-deployment-package-from-xperience-portal). In the **Deployments** application, select the **Upload package** button under the desired environment.

### Deploy emergency fixes using Xperience Portal API

> **Note:** **Notes**
>
> - This action is available only for 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).
> - This action may cause downtime of the target environment.

1. [Create](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment.md#create-a-deployment-package) the emergency deployment package.
2. If you don't have one already, create a [Personal access token](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md#personal-access-tokens) with the required permissions for respective environments: _Deploy to production environments_ or _Deploy to non-production environments_.
3. [Upload a package using Xperience Portal API](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment.md#upload-a-deployment-package-using-xperience-portal-api). When sending the POST request to the _deployment_ API endpoint, modify or add the last path segment and set the value to the desired environment (e.g., `prod` for _Production_ or `stg` for _Staging_).

```powershell title="Upload to PROD environment"
# Due to a PowerShell issue, we recommended 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 <PERSONAL_ACCESS_TOKEN_WITH_REQUIRED_PERMISSION>" }
Invoke-RestMethod -Uri https://xperience-portal.com/api/deployment/upload/<PROJECT_GUID>/prod -Method Post -InFile <FILE_PATH> -ContentType "application/zip" -Headers $headers

# Enable the progress bar
$ProgressPreference = 'Continue'
```

## Deploy mapped binary files directly from private Blob storage to SaaS

Many private cloud projects use the `AzureStorageProvider` to [map binary files](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/azure-blob-storage.md#azure-blob-storage-for-private-cloud-deployments) to [Azure Blob storage](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction).

Xperience SaaS also uses Azure Blob storage, and those migrating from private cloud to SaaS must copy their files from their private storage container to that of the SaaS environment.

The container name in the destination SaaS storage **must match** what you have [configured for SaaS storage mapping](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/azure-blob-storage.md#azure-blob-storage-for-kenticos-saas). Additionally, these configurations should map the same directories as the private cloud version, to ensure the same files reside in the container.

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 your files between blobs without having to download them first_. You'll need the following:

- A SAS token and URL for the source container (existing Azure storage) with _read_ access and sufficient validity time for the file transfer. (Full Entra ID access will also work.)
- A SAS token and URL for the destination container (SaaS-provided storage) with _read/write_ access and sufficient validity time for the file transfer.

After the copy finishes, the binary files are in the SaaS environment’s Azure Blob storage and accessible to your deployed application.