Setting up Xperience by Kentico on macOS Sonoma 🥲🥵

Step-by-step guide to set up the “Dancing Goat” project template.

7 min readMay 9, 2024

It was rather interesting setting up, and I found that the guides out there are not so complete or outdated. So, hope this help you to set up Kentico locally and try it out.

Before we being, a fun fact !

You will need a tool called cli-lab to uninstall the dotnet SDK and runtime from your Mac. I find it rather amusing why Microsoft made it sort of easy to install dotnet but made it a pain to uninstall 🙄

Please skip this part if not needed

https://learn.microsoft.com/en-us/dotnet/core/additional-tools/uninstall-tool?tabs=macos#install-the-tool

In the instructions, it says to run the following commands, which of course didn’t work.

mkdir -p ~/dotnet-core-uninstall
tar -zxf dotnet-core-uninstall.tar.gz -C ~/dotnet-core-uninstall
cd ~/dotnet-core-uninstall
./dotnet-core-uninstall -h

So I had to create the directory mkdir -p ~/dotnet-core-uninstall and download the tar.gz file manually and move it to the dotnet-core-uninstall directory.

You will need to give permissions for it to execute after running the command./dotnet-core-uninstall -h from the System settings > Privacy & Security tab.

Following are what I had in my local system.

To uninstall a SDK version ex: 6.0.29 SDK

sudo ./dotnet-core-uninstall remove 6.0.29 — runtime

To uninstall a Runtime version ex: 8.0.4

Lets Being

First start by installing the latest SDK in to our mac. At the time of writing, it is .NET 8.0 SDK (v8.0.204)

https://dotnet.microsoft.com/en-us/download/dotnet/sdk-for-vs-code?utm_source=vs-code&utm_medium=referral&utm_campaign=sdk-install

The following will be installed;

.NET SDK 8.0.204
.NET Runtime 8.0.4
ASP.NET Core Runtime 8.0.4

Step 1

Verify if you already have any previously installed packages.

$> dotnet new uninstall
Currently installed items:
(No Items)

Step 2

Install the project templates

$> dotnet new install kentico.xperience.templates
The following template packages will be installed:
   kentico.xperience.templates

Success: Kentico.Xperience.Templates::29.0.2 installed the following templates:
Template Name                                               Short Name                      Language  Tags
----------------------------------------------------------  ------------------------------  --------  ------------
ASP.NET Core MVC with Kentico Xperience                     kentico-xperience-mvc           [C#]      Boilerplate
Customization samples for Kentico Xperience administration  kentico-xperience-admin-sample  [C#]      Admin sample
Kentico Xperience with ASP.NET Core MVC sample site         kentico-xperience-sample-mvc    [C#]      Sample

To uninstall the project template;
dotnet new uninstall Kentico.Xperience.Templates
To uninstall the project database manager;
dotnet tool uninstall Kentico.Xperience.DbManager

Step 3

For the project to run, we must have a database service. For this, we have to use Microsoft SQL Server docker image or use an Azure SQL service. I’ll be using the docker image. Make sure you have docker application running locally first and then,

docker pull mcr.microsoft.com/mssql/server:2022-latest will pull it locally.

$> docker pull mcr.microsoft.com/mssql/server:2022-latest
2022-latest: Pulling from mssql/server
Digest: sha256:7f33bc7998644f7b106221ced5e75451830cd5d9c669e5888470ad72f8f8559b
Status: Image is up to date for mcr.microsoft.com/mssql/server:2022-latest
mcr.microsoft.com/mssql/server:2022-latest

What's Next?
  View a summary of image vulnerabilities and recommendations → docker scout quickview mcr.microsoft.com/mssql/server:2022-latest

Let’s start a new instance as a container,

docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=Pass@12345" \
   -p 1433:1433 --name sql2022 --hostname localhost \
   -d \
   mcr.microsoft.com/mssql/server:2022-latest

The database server connection details will be the following.

Server Name: localhost,1433 (SQL Server uses a comma instead of a colon to separate the host from the port number)
Username: sa (you can change this if you want)
Password: Pass@12345 (you can change this if you want)

Step 4

Now to creating the project and files.

In the terminal, navigate to the directory where you want the project files to be created.

Run the following command:

dotnet new <short_name> --cloud -n AcmeWeb

Replace <short_name> with the template short name of the project type you want to install. See Available project templates.
The -n parameter sets the name of the installed project. See the dotnet new reference to learn more about the command options.
It is not recommended to use non-alphanumeric (e.g. space ‘ ‘, dot’.’, or underscore ‘_’) characters in the project name.
The — cloud parameter installs a boilerplate project suitable for deployment to the SaaS environment. Omit this parameter if you wish to host a self-managed Xperience project.

Since I want to use the kentico-xperience-sample-mvc template;

$> dotnet new kentico-xperience-sample-mvc -n dancing-goat
The template "Kentico Xperience with ASP.NET Core MVC sample site" was created successfully.

Processing post-creation actions...
Restoring /Users/pasangamage/www/kentico-demo/dancing-goat.csproj:
  Determining projects to restore...
  Restored /Users/pasangamage/www/kentico-demo/dancing-goat.csproj (in 931 ms).
Restore succeeded.

Template is configured to run the following action:
Description: Restore tools required for this project configuration.
Actual command: dotnet tool restore
Do you want to run this action [Y(yes)|N(no)]?
y
Running command 'dotnet tool restore'...
Tool 'kentico.xperience.dbmanager' (version '29.0.2') was restored. Available commands: kentico-xperience-dbmanager

Restore was successful.
Command succeeded.


An update for template package 'Kentico.Xperience.Templates::29.0.2' is available.
To update the package use:
   dotnet new install Kentico.Xperience.Templates::29.0.3

Step 5

You must create a license key for self-managed Xperience deployments using the Kentico Client Portal and you must have a business email account for registration.

https://docs.kentico.com/developers-and-admins/installation/licenses#evaluate-xperience-by-kentico

Step 6

You will want to get a license key for Xperience by Kentico which you will put into a text file named license.txt in your project folder.

By this step if you open up the project in VS Code Editor it will look like this.

Execute following command. Make sure you change the username sa and password Pass@12345 according to what was provided in the Step 3

dotnet kentico-xperience-dbmanager -- \
  -d xk-27-00-01-01 \
  -u sa \
  -s "localhost,1433" \
  -p "Pass@12345" \
  -a "Pass@12345" \
  --license-file "license.txt" \
  --recreate-existing-database

The -p option is the password for the database and must match the password you provided when creating the container in the previous section.

The -a option specifies the password for the administrator login to the Xperience by Kentico application.

$> dotnet kentico-xperience-dbmanager -- \
  -d xk-27-00-01-01 \
  -u sa \
  -s "localhost,1433" \
  -p "Pass@12345" \
  -a "Pass@12345" \
  --license-file "license.txt" \
  --recreate-existing-database
Creating empty database...
Empty database created.
Creating database schema and default data...
Database schema and default data created.
Updating macro signatures...
Macro signatures updated.
Importing license from given file.
The license was successfully imported.
Updating application settings...
Application settings updated.
Installing template data...
Updating macro signatures...
Macro signatures updated.
Template data successfully installed.
Database 'xk-27-00-01-01' is ready to be used.

Step 7

Close and reopen VS Code Editor, You will notice a new tab called Solution Explorer on the left. And you will also notice that the arguments we passed in had updated the appsettings.json file