XM Cloud series: Setting up you local development machine (the easy way)
By Derk Hudepol on 11/06/2022
Introduction
Now that XM Cloud is out, no doubt a lot of developers are eager to get started. Luckily XM Cloud has a developer setup included in the starter kit and this is the easiest way to get everything setup. This blog post will go into details on how to get your dev environment setup for XM Cloud development leveraging the SXA Starter template from Sitecore.
Preparing your setup
To start setting up your development instance there are a couple of things you need to do upfront:
Setup Docker with windows containers enabled
Ensure Hyper-v is enabled
Have the latest stable Node.js version
Have the .Net core 6.0 SDK installed
Have the .net framework 4.8 installed
Have a git client installed
And last but not least have the latest version of the sxastarter templated cloned to your local machine. The repository with templates can be found here: https://github.com/sitecorelabs.
The template we will be using is https://github.com/sitecorelabs/xmcloud-foundation-head as this is the templates required by Sitecore. To clone it to your local machine simply run:
1git clone https://github.com/sitecorelabs/xmcloud-foundation-head-staging.git sxa-starterInitializing the local setup
Now that your development machine has been prepared you can actually start setting up your machine. Browse to the folder you have cloned the template into, and you should see a init.ps1 in the folder. We will need to run that script before we can start the sitecore instance. To do that open up a powershell console , cd to the right folder and then run the following:
1.\init.ps1 -AdminPassword <your-password-here> -InitEnv -LicenseXmlPath "<path-to-your-sitecore-license>"The outcome of the script should be similar the the output below:
1Preparing your Sitecore Containers environment!
2Importing SitecoreDockerTools...
3WARNING: The names of some imported commands from the module 'SitecoreDockerTools' include unapproved verbs that might
4make them less discoverable. To find the commands with unapproved verbs, run the Import-Module command again with the
5Verbose parameter. For a list of approved verbs, type Get-Verb.
6 \ + / /`\
7 \ | /
8 \ | / /`\
9 \ / \ /
10 \ /______\ /
11 / |___|___| \
12 / |;| |;| \
13 / \\. . / \
14 / ||: . | \ /`\
15 / ||: | \
16 ||: |
17 ||: .|
18 || |
19 |: |
20 ||:__ . | ------------------
21___________ _ ||_| |_.| |________________| |___________________
22......................................... | | ..................
23.............................. -------------------------------------- .........
24........ _________ .......... | | | .........
25 / | | | |
26 / / ------------------------------------------------------
27 | | | | | |
28 | | | | | |
29------ ---------------------------------------------------------------
30\ _____ _______ ________ ______ ______ _____ ________ _____ /
31 \ / ____|__ __|__ __| ___/ / ____/ ___ | __ \ | ___| /
32~~\ | (___ | | | | | |__ | | | | | | |__) || |__ /~~
33~~~\ \____\ | | | | | __| | | | | | | _ / | __| /~~~
34~~~~\ ____| )__| |__ | | | |___| |___ | |___| | | \ \ | |___ /~~~~
35~~~~~\ |_____/|________| |_| |____ / \_____/\____/ |__| \_ \_____| /~~~~~
36~~~~~~\ /~~~~~~
37~~~~~~~\ /====~~~
38~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
39Downloading and installing mkcert certificate tool...
40Generating Traefik TLS certificate...
41Using the local CA at "C:\Users\derk.hudepol\AppData\Local\mkcert" â¨
42The local CA is already installed in the system trust store! đ
43
44Using the local CA at "C:\Users\derk.hudepol\AppData\Local\mkcert" â¨
45
46Created a new certificate valid for the following names đ
47 - "*.sxastarter.localhost"
48
49Reminder: X.509 wildcards only go one level deep, so this won't match a.b.sxastarter.localhost âšī¸
50
51The certificate is at "./_wildcard.sxastarter.localhost.pem" and the key at "./_wildcard.sxastarter.localhost-key.pem" â
52
53Using the local CA at "C:\Users\derk.hudepol\AppData\Local\mkcert" â¨
54
55Created a new certificate valid for the following names đ
56 - "xmcloudcm.localhost"
57
58The certificate is at "./xmcloudcm.localhost.pem" and the key at "./xmcloudcm.localhost-key.pem" â
59
60Adding Windows hosts file entries...
61Populating required .env file values...
62Done!
63
64###########################################################################
65To avoid HTTPS errors, set the NODE_EXTRA_CA_CERTS environment variable
66using the following commmand:
67setx NODE_EXTRA_CA_CERTS C:\Users\derk.hudepol\AppData\Local\mkcert\rootCA.pem
68
69You will need to restart your terminal or VS Code for it to take effect.
70###########################################################################Be aware that the last part of the output is very important, as without your local NodeJs setup will not be able to communicate with the Sitecore instance. So now run the command:
1setx NODE_EXTRA_CA_CERTS <you rootCA here>Starting your environment for the first time
Now that you have got your environment initialized you should be able to start your Sitecore development instance. The sxa starter template offers a powershell script for this as well : up.ps1. Now go ahead and run it in your powershell window. This command will take a while but keep your eye on it because at the end of the script it will ask you to login to the sitecorecloud to install some items into your local Sitecore instance and if it times out the first startup will not be succesfull. If you do not have an account when requested to login , just create one.
1.\up.ps1If all went well at some you will be requested to login and then to authorize your local instance in a screen like this:
And the script should end similar to the text below:
1[master] [U] /sitecore/system/Settings/Services/Rendering Hosts/Default (dffee92b-0441-45a4-9207-67810b72bd46)
2
3[master] Discovered 1 changes after evaluating 1 total items.
4
5[master] Applying changes...
6[master] Changes have been applied to Sitecore endpoint default (Host: https://xmcloudcm.localhost/, DB: master).
7Pushing sitecore API key
8Pushing sitecore api key to Sitecore...
9
10[master] [A] /sitecore/system/Settings/Services/API Keys/xmcloudpreview (cc41ece7-58c6-4b33-ab75-5fb030c350b1)
11
12[master] Discovered 1 changes after evaluating 1 total items.
13
14[master] Applying changes...
15[master] Changes have been applied to Sitecore endpoint default (Host: https://xmcloudcm.localhost/, DB: master).
16Opening site...
17
18Use the following command to monitor your Rendering Host:
19docker-compose logs -f renderingAnd the Sitecore XM Cloud content editor landing page should open up, important note here is that all the tools are available except for pages. Pages does not work locally and will redirect you to the online xmcloud environment:
Setup your first XM Cloud SXA Site
Before we can actually start developing, editing or previewing anything we still need to create a site. Because the sxastarter template assumes we use a site called "sxastarter" we will be creating a site called sxastarter for now.
Start of by opening up the content editor by clicking the button on the landing page. And when the content editor has opened up right click the "Content" item and select "Insert->Headless Tenant":
After clicking the headless tenant option a dialog should show up. In this dialog give the tenant the name "sxastarter" and leave the other setting as is before clicking "Ok":
Now that the tenant is created, right click it again and select "insert->headless site" give the site the name "sxastarter" and done change anything but the modules. in this case select all modules before clicking "ok":
Now the site will be created and we are able to open the experience editor and edit it:
Now by default the rendering host is a bit broken on public viewing so browsing to "www.sxastarter.localhost" is not very useful as image links are broken. Next to that for development the nicest flow of working is still just leveraging the local machine in combination with a local nodejs server. Lets get that setup now.
Setting up the local nodejs setup
Now that everything in docker is working we can get started with setting up our local Jss/NextJS project. This is a project that comes with the sxastarter template and we can find it in "src/sxastarter". Before we go into consideration first install all npm packages. do this by using "cd <path-to-src/sxastarter>" and then running npm install:
1npm installAfter this is finished we will need to configure our project. My preferred way of doing this is by creating a ".env.local" file containing all the environment variables that are needed to run the application. The reason I prefer this above the jss cli setup command options is because the environment variables are also what you will be using on you eventual hosting setup.
To create this ".env.local" file, copy the ".env" file found in the "sxastarter" folder and then pasting it in the same folder under the name ".env.local" so it will eventually look like:
now before we open up the file you will need to have the following ready:
JSS_EDITING_SECRET
This value we can find in the ".env" file located in the root of your code base, so the folder where you also run ".\up.ps1" from. The value can be found in the file:
1JSS_EDITING_SECRET=yaeDZfcjY03jrbjHGW66xldeGJ3CPDfWHsXfuRoywoC7gx29VHoVf36YLWFAHYO2SITECORE_API_KEY
This value can also be found in the ".env" file located in the root of your code base, so the folder where you also run ".\up.ps1" from. The value can be found in the file:
1SITECORE_API_KEY_xmcloudpreview=cc41ece7-58c6-4b33-ab75-5fb030c350b1Now that we have these, we can configure the ".env.local" file. You should fill it in, in the following way:
1# For development purposes, note Next.js supports a .env.local
2# file, which is already configured to be git ignored.
3# Read more about Next.js support of environment variables here:
4# https://nextjs.org/docs/basic-features/environment-variables
5
6# The public URL to use for absolute URLs, which are required when
7# the Next.js app is run within Sitecore editors.
8# This should match the `serverSideRenderingEngineApplicationUrl`
9# in your Sitecore configuration (see \sitecore\config\sxastarter.config).
10# Be sure to update these values accordingly as your public endpoint changes.
11# See https://jss.sitecore.com/docs/fundamentals/services/view-engine
12PUBLIC_URL=http://localhost:3000
13
14# To secure the Sitecore editor endpoint exposed by your Next.js app
15# (`/api/editing/render` by default), a secret token is used. This (client-side)
16# value must match your server-side value (see \sitecore\config\sxastarter.config).
17# We recommend an alphanumeric value of at least 16 characters.
18JSS_EDITING_SECRET=<Your secret here>
19
20# Your Sitecore API key is needed to build the app. Typically, the API key is
21# defined in `scjssconfig.json` (as `sitecore.apiKey`). This file may not exist
22# when building locally (if you've never run `jss setup`), or when building in a
23# higher environment (since `scjssconfig.json` is ignored from source control).
24# In this case, use this environment variable to provide the value at build time.
25SITECORE_API_KEY=<Your api key here>
26
27# Your Sitecore API hostname is needed to build the app. Typically, the API host is
28# defined in `scjssconfig.json` (as `sitecore.layoutServiceHost`). This file may
29# not exist when building locally (if you've never run `jss setup`), or when building
30# in a higher environment (since `scjssconfig.json` is ignored from source control).
31# In this case, use this environment variable to provide the value at build time.
32SITECORE_API_HOST=https://xmcloudcm.localhost
33
34# Your GraphQL Edge endpoint. This is required for Sitecore Experience Edge.
35# For Sitecore XM, this is typically optional. By default, the endpoint is calculated using
36# the resolved Sitecore API hostname + the `graphQLEndpointPath` defined in your `package.json`.
37GRAPH_QL_ENDPOINT=
38
39# Your default app language.
40DEFAULT_LANGUAGE=en
41
42# The way in which layout and dictionary data is fetched from Sitecore
43FETCH_WITH=GraphQL
44
45# Indicates whether SSG `getStaticPaths` pre-render any pages
46# Set the environment variable DISABLE_SSG_FETCH=true
47# to enable full ISR (Incremental Static Regeneration) flow
48DISABLE_SSG_FETCH=
49
50# Sitecore JSS npm packages utilize the debug module for debug logging.
51# https://www.npmjs.com/package/debug
52# Set the DEBUG environment variable to 'sitecore-jss:*' to see all logs:
53#DEBUG=sitecore-jss:*
54# Or be selective and show for example only layout service logs:
55#DEBUG=sitecore-jss:layout
56# Or everything BUT layout service logs:
57#DEBUG=sitecore-jss:*,-sitecore-jss:layout
58
59# Your Sitecore CDP API target (specific to your data center region)
60NEXT_PUBLIC_CDP_TARGET_URL=https://api-engage-eu.sitecorecloud.io
61
62# Your Sitecore CDP client key
63NEXT_PUBLIC_CDP_CLIENT_KEY=dummyvaluefornow
64
65# Your Sitecore CDP point(s) of sale
66# Can be provided as a single value (mypoint.com) or a multi-value JSON with locales ({"en":"en.mypoint.com","fr":"fr.mypoint.com"} etc)
67NEXT_PUBLIC_CDP_POINTOFSALE=
68
69# Timeout (ms) for Sitecore CDP requests to respond within. Default is 250.
70PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT=400
71
72# Timeout (ms) for Sitecore Experience Edge requests to respond within. Default is 250.
73PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT=400
74Now you can run "npm run start:connected" and you should see the project start running:
1npm run start:connected
2
3> sxastarter@21.0.1 start:connected
4> npm-run-all --serial bootstrap --parallel next:dev start:watch-components
5
6
7> sxastarter@21.0.1 bootstrap
8> ts-node --project tsconfig.scripts.json scripts/bootstrap.ts
9
10Writing runtime config to C:\src\sxa-starter\src\sxastarter\src\temp\config.js
11Registering JSS component CdpPageView
12Registering JSS component ColumnSplitter
13Registering JSS component Container
14Registering JSS component ContentBlock
15Registering JSS component Image
16Registering JSS component LinkList
17Registering JSS component Navigation
18Registering JSS component PageContent
19Registering JSS component PartialDesignDynamicPlaceholder
20Registering JSS component Promo
21Registering JSS component RichText
22Registering JSS component RowSplitter
23Registering JSS component Title
24Writing component factory to C:\src\sxa-starter\src\sxastarter\src\temp\componentFactory.ts
25Registering sitemap-fetcher plugin graphql-sitemap-service
26Writing sitemap-fetcher plugins to C:\src\sxa-starter\src\sxastarter\src\temp\sitemap-fetcher-plugins.ts
27Registering middleware plugin personalize
28Registering middleware plugin redirects
29Writing middleware plugins to C:\src\sxa-starter\src\sxastarter\src\temp\middleware-plugins.ts
30Registering page-props-factory plugin component-props
31Registering page-props-factory plugin error-pages
32Registering page-props-factory plugin normal-mode
33Registering page-props-factory plugin personalize
34Registering page-props-factory plugin preview-mode
35Writing page-props-factory plugins to C:\src\sxa-starter\src\sxastarter\src\temp\page-props-factory-plugins.ts
36Registering next-config plugin graphql
37Registering next-config plugin robots
38Registering next-config plugin sass
39Registering next-config plugin sitemap
40Writing next-config plugins to C:\src\sxa-starter\src\sxastarter\src\temp\next-config-plugins.js
41
42> sxastarter@21.0.1 next:dev
43> cross-env NODE_OPTIONS='--inspect' next dev
44
45
46> sxastarter@21.0.1 start:watch-components
47> ts-node --project tsconfig.scripts.json scripts/generate-component-factory.ts --watch
48
49Debugger listening on ws://127.0.0.1:9229/7f15f4ba-59be-4dcb-8264-4a877f696247
50For help, see: https://nodejs.org/en/docs/inspector
51ready - started server on 0.0.0.0:3000, url: http://localhost:3000To see if it worked you can now browse to "http://localhost:3000" and see the site:
Hopfully you were able to follow all the steps and setup the environment. Happy developing!
Bonus: Setting up a site with a name different than "sxastarter"
Now, I can image you do not want your site to be called "sxastarter". So lets change that: first go into the content editor and create a tenant & site with the name you want (per example "awesomesite") by following the steps outlined earlier in this post.
The editing functionality in the experience editor will work right away and the only thing you will need to do now is make your local development environment work. We can do that by opening up the ".env.local" file again and then add the environment variable called "JSS_APP_NAME". Lets add that to the ".env.local" file:
1JSS_APP_NAME=<your sitename here>Now restart your local development site by doing ctrl+c and running "npm run start:connected" again.