Kentico's Xperience Portal and SaaS: From Setup to Production

This article will guide you through the essential steps for a smooth and successful deployment using Kentico's SaaS and Xperience Portal, while also sharing my personal experiences and practical insights.

☁️ What is Kentico's SaaS and Xperience Portal?

Kentico's offering can be compared to the relationship between the Next.js framework and Vercel cloud platform. In this analogy:

• Xperience by Kentico is the application.
• Xperience Portal is the control panel for the SaaS—a cloud platform providing a tailored runtime environment for the application.

This setup resembles a Platform as a Service (PaaS) more than a traditional SaaS, as it offers a platform for developers to build, deploy, and manage Xperience by Kentico projects without handling the underlying infrastructure. The key features include:

• Simplified deployment
• Multiple environments (QA, UAT, Production)
• Runtime monitoring
• Domain management
• Managed infrastructure
• Enterprise-grade security
• Automated scalability

The official documentation provides a structured description of the service here. In this article, my goal is to share:

• My personal experience using Xperience Portal.
• Insights and observations from a development cycle of an Xperience by Kentico project.

❓ Evaluation Process

Apart from the SaaS, you can also opt for a self-managed environment as detailed here. However, as a small team, managing everything that the SaaS provides out-of-the-box would be overwhelming and would require hiring a DevOps specialist. Thus, we chose to subscribe to Kentico's SaaS.

After successfully delivering our project, I believe this was the right decision. The value is clear—it allows us to focus solely on project development while the service operates seamlessly in the background.

🔄 Project Development Cycle Using Xperience Portal

⚙️ Initial Setup

During the onboarding process, after you agree to subscribe, you'll receive an invitation email to the Xperience Portal. You'll create your credentials, set up Multi-Factor Authentication, and invite your teammates.

⚙️ Xperience Portal Setup

To prepare the Xperience Portal to host your project, you need to:

1. Mimic your Website and Email Channels as detailed here.
2. Sync the Hash string salt as described here.
3. Create a Personal Access Token if you're going to automate the deployment process using external tools.

⚙️ Xperience by Kentico Project Setup

Ensure your Xperience by Kentico project is ready to be hosted in the SaaS environment. The most crucial step is creating your project from a template using the --cloud parameter, which adds essential code to make your project compatible with SaaS. If you did not use this parameter, you'll need to create a new project with it and migrate your code as explained here.

Other configurations, such as SendGrid integration and CDN setup, are typically already configured, but it's wise to check your project against the documentation to ensure nothing is missing.

⚙️ Deployment Setup

To deploy your project to SaaS, you'll need to generate a deployment package containing database objects (defined through the $CDRepository/repository.config file) and your built application. The documentation is detailed, but I found the setup challenging. Here's what worked for me:

1. In your project's root folder, create a $CDRepository folder and a repository.config file inside it. Ensure the naming and location are exact.
2. Exclude the $CDRepository folder from your source control. 
3. In the repository.config file, create an XML structure defining which objects and object types to include or exclude from the final package. You can use the code provided here. During rapid development, I kept the XML skeleton empty to include all objects in the package, mirroring my development environment. Later, as the client got more involved, we removed test data from the deployed sites and adjusted the repository.config file to exclude environment-specific object types, such as content items, forms, users, roles, etc.

📤 Deployment

Once you've completed the setup you can repeat the following deployment steps whenever needed:

1. In PowerShell, run the CD store command from your project’s root directory: 

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

In my case for macOS with an absolute path:

dotnet run --no-build -- --kxp-cd-store --repository-path '/Users/milanlund/Documents/GitHub/<project-name>/$CDRepository'

2. Create the deployment package: 

.\Export-DeploymentPackage.ps1 -AssemblyName "<assembly-name>"

In my case for macOS with an absolute path:

/Users/milanlund/Documents/GitHub/<project-name>/Export-DeploymentPackage.ps1 -AssemblyName '<assembly-name>'

The <assembly-name> is the name of your .csproj file.

3. The DeploymentPackage.zip file should appear in the project root folder.

4. Go to Xperience Portal > Deployments and upload the package file to start the deployment.

👀 Deployment Insights and Observations

During my experience, I encountered several noteworthy aspects:

• Deployment Time: For our small to medium project, a single deployment to one environment takes 20-30 minutes.
• Downtime: Occasionally, there is a 5 or more minutes downtime towards the end of the deployment process.
• Deployment Sequence: In our tier, we have two environments—QA and PROD. To deploy a new project version, first deploy to QA and wait for completion before deploying to PROD. Deploying to PROD before QA finishes will result in deploying the previous package version to PROD.
• Package Contents: Currently, it is not possible to exclude specific files from the deployment package. Be cautious if your config files contain sensitive data.
• Environment Identification: Ensure that code meant for localhost remains there by using Environment Identification extension methods. I once failed to do this, resulting in a custom config file overriding the SaaS-injected connection string, causing inconsistencies and performance issues. Kentico's SaaS development team had to provide me with a clean SaaS instance to resolve it.
• Deployment Failure: Double-check everything to ensure you deploy a functional package. If the deployment fails, log files typically provide clues. However, I once experienced a silent failure where the deployment remained "In progress" with no logs available, requiring extensive support from Kentico's team.
• Backup Restore: The restore process may take even longer than deployments, causing the application to be down for the entire duration.
• Deployment of a project on a lower version of Xperience by Kentico that has already been deployed: This is not directly supported. The workaround might be to restore a backup on the lower version and then deploy the package.
• Event Log Errors: Even if your event log is clean in your local development environment, it’s a good idea to check the event log on your deployed application from time to time. You might discover issues related to your code or even problems tied to the SaaS environment. I was able to spot a few bugs this way that Kentico later resolved in a hotfix.
• Third-party integrations: Keep in mind that some integrations, even if officially supported, might not be fully compatible with SaaS. For example, I encountered an issue with the Kentico.Xperience.Lucene NuGet package where search indexes didn’t persist between deployments.

🚀 Going to Production

Before going live, I recommend checking the Monitoring section in the Xperience Portal, specifically the Exceptions and Event log. These sections will highlight potential issues with your project. The Event log is mirrored from the Event Log application in your Xperience by Kentico Admin, and issues caught by Application Insights may also appear here.

Finally, when switching from the temporary domain (*.xperience-sites.com) to your custom production domain, remember to update both the Website and Email channels as described here and here.

🛣️ Changelog and Roadmap

For ideas on new features or to see what’s in the pipeline, search for "SaaS" and "Xperience Portal" on the roadmap. To track changes, check out the changelog.

🙏 Wishes for the Future

Despite the somewhat challenging initial setup, we've had a smooth experience with Xperience Portal. With this guide, your journey should be even smoother. However, if I could wish for one improvement, it would be faster deployments.