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 – currently Microsoft Application Insights 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 Xperience Portal project.
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.

Project templates for deployment to the SaaS environment

Xperience provides the kentico-xperience-mvc and kentico-xperience-sample-mvc .NET project templates as a starting point for developing Xperience websites.

A project template for SaaS deployment (installed with the --cloud parameter) 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.
  • WebApplication.UseKenticoCloud must be called in the middleware pipeline before WebApplication.UseKentico. See Configure new projects.
• A configuration file for the Continuous Deployment 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.

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.

Create a deployment package

A deployment package is a ZIP archive with application libraries and static files, and a $CDRepository folder with serialized 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"
      
       

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. Allow a few minutes for the deployment to be displayed in the Deployment history section, where you can check the status of the deployment.

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:

   PSUpload 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'
   
    

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