π Introduction
This repository is not a Starter Kit or Template Solution, you should not clone this repository for the purposes of starting a new Sitecore project. This is intended as a reference example of a Sitecore XM Cloud implementation.
This repository contains the codebase for a series of sites managed by the Technical Marketing Team at Sitecore. You will find the following sites in this repository:
β
Build Status
β Prerequisites
- DotNet 6.0
- NodeJS 16 LTS (or greater)
- Docker
This repositories maintainers intend to keep this repository running against the latest Docker Windows Container versions as possible to reduce image size and increase performance. You may need to downgrade to an earlier Base OS version if you are running an older Host OS. You can read more about this on the Wiki
Okta Account
If you wish to run the MVP Site you will need to provide Okta configuration details. You can generate these values for yourself by Signing up for an Okta Developer Account
Auth0 Account
When you interact with XM Cloud you will be asked to authenticate with our Auth0 tenant. If you don't have an account already you can follow the registration flow provided by the Auth0 to create one.
βΆοΈ Initializing the repository
You first need to initialize your .env file which will configure how the different application elements will run. There are a series of parameters you can pass in to override the default behaviour of the application, you can find the full list of parameters with their purpose here.
Examples of how to use them can be seen in the different setup guides for both Local Mode and Edge Mode below.
Parameter | Required for MVP Site | Required for SUGCON Sites | Purpose |
---|---|---|---|
LicenseXmlPath | Yes | Yes | Used to specify the path to the license file |
AdminPassword | Yes | Yes | Used to specify the password for the Sitecore admin user |
InitEnv | No | No | Used to force a full initialisation of the repository |
Edge_Token | No | No | Used to authenticate with XM Cloud, when running in 'Edge Mode' |
OKTA_Domain | Yes | No | Okta domain used by the MVP Rendering host |
OKTA_Client_Id | Yes | No | Okta Client Id used by the MVP Rendering host |
OKTA_Client_Secret | Yes | No | Okta Client Secret used by the MVP Rendering host |
MVP_Selections_API | Yes | No | URL for the MVP Selections API |
π Running the Repository
After you have initialized the repository, you can run it using the up.ps1
script. There are 3 different ways you can run this repository
The different parameters on the up.ps1
script control which mode you want to select, along with some other options.
Parameter | Required | Purpose |
---|---|---|
UseEdge | No | Used to run the head applications against Edge, not against a local CM instance |
SkipBuild | No | Used to skip running the docker build command |
SkipIndexing | No | Used to skip indexing the content |
SkipPush | No | Used to skip pushing the local content into the CM |
SkipOpen | No | Okta to skip automatically opening the sites |
π Running in Full Local Development Mode
Running in Local Mode will run all of the application elements required on your local machine using Docker
Initialize your repository for Local Mode
First initialize your repo using the .init/ps1
script, you can see an example of how to init for 'Local Mode' below
.\init.ps1 -InitEnv -LicenseXmlPath "C:\path\to\license.xml" -AdminPassword "DesiredAdminPassword"
Bring up all the application elements for Local Mode
Next, use the up.ps1
script to bring up all of the containers required for Local Mode.
.\up.ps1
π +π Running in Edge Development Mode with Docker
Running in Edge Mode with Docker will run only run the Head applications and Traefik. To be able to run the sites in this repository locally against Edge, you will need to have access to an active XM Cloud Subscription with enough entitlements to be able to create a new Project & Environment to run against.
Create a new environment and deploy the codebase
You can follow these steps to create a new XM Cloud Project & Environment, then generate an Edge Token used to authenticate your Head applications with your Edge Tenant.
- Authenticate with the XM Cloud Deploy Application
dotnet sitecore cloud login
- Create a new XM Cloud Project
dotnet sitecore cloud project create -n <<YOUR_PROJECT_NAME>>
- Record the returned Project ID.
- Create an environment that you're going to deploy to:
dotnet sitecore cloud environment create --project-id <<YOUR_PROJECT_ID>> -n <<ENVIRONMENT_NAME>>
- Record the returned Environment ID.
- Create a deployment and push the local codebase into XM Cloud
dotnet sitecore cloud deployment create -id <<YOUR_ENVIRONMENT_ID>> --upload
- Access the CM instance that has been created and perform a "Site Publish" to ensure all content items have been pushed to the Edge.
- Generate an Edge Token used to allow your Rendering hosts to authenticate with XM Cloud
.\New-EdgeToken.ps1 -EnvironmentId <<YOUR_ENVIRONMENT_ID>>
- Record the returned Edge Token, and Edge URL.
If you want more information about the Cloud plugin for the CLI then you access it on the documentation site.
Initialize your repository for Edge Development Mode with Docker
First initialize your repo using the .init/ps1
script, you will need to pass in the -Edge_Token
parameter set to the value you generated in the previous step.
.\init.ps1 -InitEnv -LicenseXmlPath "C:\path\to\license.xml" -AdminPassword "DesiredAdminPassword" --Edge_Token "<<YOUR_EDGE_TOKEN>>"
Bring up all the application elements for Edge Mode with Docker
Once you have initialized the repository with your Edge Token, use the up.ps1
script, ensuring to pass the -UseEdge
parameter to bring up all of the containers required for Edge Mode.
.\up.ps1 -UseEdge
π» +π Running in Edge Development Mode without Docker
Coming soon...