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:
- Get access to your Xperience Portal project.
- Prepare a .NET project for deployment to the SaaS environment.
- Develop and configure features in your project.
- Deploy your application to the SaaS environment.
- Manage your deployed application in Xperience Portal.
SaaS environments are not a substitute for staging
Be aware that different SaaS environments are not meant for staging your website content. Deploying packages with large volume of files and content between environments is not efficient.
- The maximum size of the deployment package is 2 gigabytes. Binary files and media libraries are bundled in the deployment package.
- 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 promoted to the Production environment.
- After promoting a build to the Production environment, production data can be added. Use the workflow feature to prevent incomplete data from appearing publicly.
- Only the latest deployed package can be promoted to the next environment.
- Backup policies are different for non-production enviroments and the Production environment. Using QA and UAT environments for staging poses a small but non-negligible risk that you lose your staged data.
Prepare a project for deployment to the SaaS environment
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.
- Use the
Build the project. Run the following command from the project’s root directory or build the project using Visual Studio.
CMDdotnet 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 beforeWebApplication.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.
You need to create and upload a new deployment package to update an existing deployment.
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.
The deployment package is limited by a maximum size of 2GB.
Follow the procedure to build your application and create a deployment package:
Use Continuous Deployment to serialize database objects to the file system:
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.
Prepare migration scripts for any database changes not covered by Continuous Deployment.
Run the CD store command from the project’s root directory:
PSdotnet run --no-build -- --kxp-cd-store --repository-path ".\$CDRepository"
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.
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# 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.\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.
- For example,
(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 theRestoreMode
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.
Uploading a deployment package to Xperience Portal is unavailable during scheduled Xperience Portal project maintenance and initial project creation.
Upload a deployment package from Xperience Portal
- Access your Xperience Portal project.
- Navigate to the Deployments application.
- Under the QA environment, select Upload deployment package.
- 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.
- 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:
Generate a Personal access token (PAT) and store it in a local file.
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.Send a POST request to the deployment API endpoint. You can use the following PowerShell or cURL examples:
PSUpload using PowerShell# 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 cURLcurl -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>
Navigate to the Deployments application.
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.