Deploy 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, CloudFlare CDN, and Twilio SendGrid. 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.
2. Prepare a .NET project for deployment to the SaaS environment.
3. Develop and configure features in your project.
4. Deploy your application to the SaaS environment.
5. Manage your deployed application in Xperience Portal.

Prepare a project for deployment to the SaaS environment

1. Create an Xperience project and the project database.

   • Use the --cloud parameter when creating the Xperience project.
   • Set the value of the --hash-string-salt parameter to the one found in the Xperience Portal Dashboard when creating the project database.

2. Configure the Xperience application.

3. Build the project. Run the following command from the project’s root directory or build the project using Visual Studio.

   CMD

   Copy

   
   
    dotnet build
   
    

The project is now ready for further development and customization. You can add content to the project or extend the connected Xperience administration.

Deploy to the SaaS environment

Once you have your Xperience project prepared and configured in a local development environment, deploy the application to the SaaS environment by creating a deployment package and uploading it to your Xperience Portal project where it is automatically deployed into the QA environment.

Deployment process overview

It is important to understand, that deployment of a new package does not mean that all data is copied from the source to the target environment. The following steps describe in theory the entire lifecycle of a deployment.

1. You install, configure and develop an Xperience project from a template. 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) repository, used to deploy database objects.
   • The Export-DeploymentPackage.ps1 PowerShell script that creates a deployment package for the project.
   • StorageInitializationModule.cs class with methods mapping folders containing media library and binary files to Azure Blob storage and local storage for development. See Azure Blob storage.
2. You 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.
   • (Optional) $StorageAssets folder for media library files.
3. When you upload the deployment package to the SaaS environment, it is restored in the QA environment according to the specified CD configuration.
4. When you deploy the package to another environment, the same deployment package is applied to the selected environment and restored according to the CD configuration.
   • 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 action 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.
   • See Deploy data to the production environment to learn how to upload content to the production 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 media library files.

Follow the procedure to build your application and create a deployment package:

1. Use Continuous Deployment 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.

      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 for any database changes not covered by Continuous Deployment.

   3. Run the CD store command from the project’s root directory:

      PS

      Copy

      
      
       dotnet run --no-build -- --kxp-cd-store --repository-path ".\$CDRepository"
      
       

      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 Media library files and other unmanaged binary files used by the application to Azure Blob storage, as Continuous Deployment does not serialize these files.

3. Create the deployment package with the Export-DeploymentPackage.ps1 script.

   On Windows environments, the executing account must have permissions to run PowerShell scripts from external sources:

   PS

   Copy

   
   
    # Bypass all execution checks for the current user
    Set-ExecutionPolicy Bypass -Scope CurrentUser -Force
   
    

   See Set-ExecutionPolicy for other types of permission levels.

   • Refer to the list of parameters before running the script.

     PS

     Copy

     
     
       .\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 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:

       • 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.

         If your deployment package contains media library files, the StorageAssetsDeploymentMode value must match the RestoreMode element value in the CD configuration file. See Reference - CI/CD object types.

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

Once you have created a deployment package, trigger the deployment to the QA environment by uploading a deployment package to your Xperience Portal project directly from Xperience Portal or programmatically using Xperience Portal API.

Upload a deployment package from Xperience Portal

1. Access your Xperience Portal project.
2. Navigate to the Deployments application.
3. Under the QA environment, select Upload deployment package.
4. Choose a valid deployment package (a ZIP archive with a maximum size of 2GB) 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 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, you can download an archive with 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) to the deployment Xperience Portal API endpoint:

1. Generate a Personal access token (PAT) and store it in a local file.

2. Get your PROJECT_GUID in Xperience Portal Dashboard, in the Project info section, or from any URL when accessing Xperience Portal, for example, https://xperience-portal.com/<PROJECT_GUID>/dashboard.

3. Send a POST request to the deployment API endpoint. You can use the following PowerShell or cURL examples:

   PS

   Upload using PowerShell

   Copy

   
   
    # 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>" }
    Invoke-RestMethod -Uri https://xperience-portal.com/api/deployment/upload/<PROJECT_GUID> -Method Post -InFile <FILE_PATH> -ContentType "application/zip" -Headers $headers
   
    # Enable the progress bar
    $ProgressPreference = 'Continue'
   
    

   PS

   Upload using cURL

   Copy

   
   
    curl -X POST -T <FILE_PATH> -H 'Content-Type: application/zip' -H 'Authorization: Bearer <PERSONAL_ACCESS_TOKEN>' https://xperience-portal.com/api/deployment/upload/<PROJECT_GUID>
   
    

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, you can download an archive with deployment logs under the Deployment history section.

Deploy data to the production environment

Deployment environments are not a substitute for staging and cannot be used to prepare content for the production environment.

• 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 you use Xperience by Kentico to manage content imported from external sources, it is recommended to import the content directly to the production environment.

Deploy the application package to another deployment environment

The following SaaS deployment environments are available, depending on your service plan:

• QA – A QA engineer tests the deployed application in the QA environment and deploys the deployment package to the UAT (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.

  The UAT environment is only available for the Level 3 service plan.

• PROD – A live production environment. Use this environment to deploy a tested iteration of your application.

After deploying a deployment package to the QA environment, you can deploy it to another environment in Xperience Portal:

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.

   The SaaS environment checks if the production deployment causes downtime. Most small deployments are seamless and incur no downtime, however, if the system discovers a downtime would occur, you can schedule a production deployment for a later date. It is also recommended to define a custom App Offline page.

5. Allow a minute for the deployment process to be displayed in the Deployment history.

   Repeating the procedure triggers a new deployment.

6. Check the Deployments section to verify the package is deployed to the environment you selected.

   If you need to debug a failed deployment, see the 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 the production environment can cause application downtime and is critical for a seamless customer experience. 

When you trigger the production 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.

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 environment is unaffected.