Overview

Each year Valtech organises an internal Sitecore Hackathon to brainstrom, share the knowledge, ideate, work together and to bring something innovative. For this year’s hackathon 2022, we as a team have created an XM Cloud Vercel Integration Application that allows you to seamlessly perform deployments with just some button clicks.

In this blog, we are going to see the over all experience in creating the Vercel Integration Application for XM Cloud and the different tech stacks/apis used.

Architecture

The overall integration application architecture looks like this. We will be seeing this in detail shortly.

Application Flow

The below diagram explains the application flow.

Creating the Integration Application

You can checkout this example repo to learn about creating a basic integration application for vercel and it’s nextjs based.

We have created a custom integration application in the Vercel’s integration console dashboard, which is the actual XM Cloud Vercel Integration and it looks something like below.

This XM Cloud Vercel Integration application is,

• API Driven
• Dockerized and Hosted in the Azure Webapp as Container
• Built with NextJs
• Uses Pusher for live notifications

It uses different below APIs which we are going to see in detail.

Git APIs

We are using a forked version of the XM Cloud repository from Git. The integration application clones this repo locally from git. It also uses a github OAuth application to authorize and clone the repo from git.

When the user clicks the Authorize button ( which you can see from the demo video attached) , they are going to allow this VRaves OAuth application to create the repo in their github account. The github authorization logic will look like this,

On successful authorization, it response back with a ‘code’ in the query string which we will be using further to clone the repo locally in our web app like below. The folder name will be the project id of vercel.

The below piece of code is responsible to shalow clone the repo from git. It then returns the local folder path where the repo got cloned. The ‘nodegit’ module is used for this.

Now we have the repository cloned and we are going to use this to deploy to XM Cloud and vercel.

Before checking the other APIs, let us see a custom json setting file we used for this integration application.

Vercel Integration Custom Configuration File

In order to override certain configuration and setting in the XM Cloud, we came up with a custom json configuration file.

This json setting file needs to be at the root of the repo for our integration app to properly identify and apply certain configurations.

{
    "customSettings": {
        "jssEditingSecretConfigPath": "/src/Environment/platform/App_config/Include/zzz"
    },
    "renderingHosts": {
        "sugconanz": {
            "path": "./src/Project/Sugcon/SugconAnzSxa",
            "siteSettingItem": "/src/Project/Sugcon/items/content/Sugcon/SugconAnzSxa/Settings.yml",
            "siteUrlToReplace": "http://sugconanz:3000",
            "type": "sxa"
        },
        "sugconeu": {
            "path": "./src/Project/Sugcon/SugconEuSxa",
            "siteSettingItem": "/src/Project/Sugcon/items/content/Sugcon/SugconEuSxa/Settings.yml",
            "siteUrlToReplace": "http://sugconeu:3000",
            "type": "sxa"
        }
    }
}

• customSettings/jssEditingSecretConfigPath [JSS EDITING SECRET]: This setting is used to apply JssEditing secret. A config patch will be generated and move this path in order to override default editing secret.
• renderingHosts [RENDERING HOST URL SPECIFIC TO A SITE] : There can be multiple rendering hosts within a repository and each created in a different path and with a different host url. This setting is used to make it easier for integration app to process rendering host in different folders and apply vercel app url in site setting item instead of default docker service url Ex: http://sugconeu:3000 —> https://sugconeu.vercel.app/

We are also having one patch file to handle the jss editing secret. The patch file looks like below,

  
    
        
        
            YOUR_SECRET_TOKEN 
            
       
  

APIs to handle the XMCloud Deployment

To deploy to XM Cloud, we are using the sitecore cli commands together with full-powershell node module. You can refer this repo to get more details about it. We are using sitecore cli commands for XM Cloud, because currently Sitecore does not offer any Rest APIs for us to consume.

My friend Ramkumar has written a detailed article about the XMCloud cli commands. You can refer this blog to know more.

We are having the below different set of APIs in the integration application.

api/xmcloud/xm-cloud-login

We first have to login with Sitecore XM Cloud. The below set of code is responsible for this. Upon successful authentication, it creates the users.json file with the required access token.

The integration application supports two different flows to deploy to existing XM Cloud project and also to create a new one. So if the users wishes to deploy to existing XMCloud project, then we need to fetch the list of existing XMCloud projects and its corresponding different environments.

The below APIs are responsible for this.

api/xmcloud/fetch-xm-projects

This API fetches all the list of existing projects from XM Cloud. The below set of block is mainly for this.

api/xmcloud/fetch-xm-environments

Based on the project selected, this API will be fetching all its environment.

Now we have both the project and its environment to be used, the next step is to initiate the deployment using the below api.

api/xmcloud/create-xm-cloud-env

This api uses the below set of node modules internally and they are

• path
• fs
• full-powershell

It does the below one by one,

• Sets the path to the project folder where we cloned the repo
• Creates the .env file from the .env.template
• Based on the environmentid parameter, it chooses either to create a new one or to deploy to existing one.
• To create a new project, it uses below set of code,

• Next step is to create a new environment using the cli command. I have mentioned only the cli command which is responsible for this.

dotnet sitecore cloud environment create -n  --project-id 

• Next is to update the JSS Editing Secret in the .env file before triggering the XM Cloud deployment and the code looks like below,

• We also need to update the RH urls in the custom configurations file for this integration application and to update the JSS Editing Secret in the custom patch file. Please refer the section [Vercel Integration Custom Configuration File] to know more.
• The next step would be to trigger the deployment like below,

• Once the deployment is completed, we need to connect to the XM Cloud env and do the publish. The below set of cli commands are responsible for this,

dotnet sitecore cloud environment connect -id ${environmentId} --allow-write
dotnet sitecore publish --pt Edge -n ${req.query.environmentName}

• The final step is to create the Edge token. We are using the XM Cloud API for this like below,

We will be setting this JSS Editing Secrets, Edge Token to the Vercel projects using the Vercel APIs which we will be seeing in the next section.

Vercel APIs

api/vercel/create-xmcloud-env-variable-for-project

It updates the different environment variables like JSS Editing Secret, GraphQL Endpoint, Sitecore API Host, Sitecore API Key etc., to the current vercel project.

get-vercel-token

It requests for the vercel access token and store it as a reach context.

api/vercel/get-domain-by-projectid

It fetches the corresponding different domains of the current vercel project. We need this domain as we need to update the RH url in the XM Cloud Environment.

This API basically results the domains from here.

Pusher API

We are using Pusher to give the real time deployment notification back to user. And its easy to configure. You can refer this to know more about this module.

It creates channels based on the project id and pushes notification accordingly. The pusher api code looks like this,

This pusher api being consumed from the pusher lib to send the notifications to the different channels.

Wrap up and future plan

These are the different apis for Git, XM Cloud and Vercel used within the integration application. Do checkout the demo to see how the integration application works.

The future plans would be to,

• To get enlisted in the Vercel Integration [CMS]
• Define standarized approach to create Vercel templates for XM Cloud
• Currently as you might have seen, the integration application is heavily depend upon Sitecore XM Cloud Cli commands. The plan is to move from Cli towards API driven approach for XM Cloud Deployment ( it depends on Sitecore’s possibility of exposing some APIs for this)
• Custom Json Configuration file – More robust customization.

References:-

• https://github.com/vercel/example-integration
• https://github.com/daverickdunn/full-powershell
• https://github.com/Sitecore/XM-Cloud-Introduction