Skip to content

Commit 1a223d0

Browse files
robearlamrobearlam
committed
Updated READMEs and docker init script
1 parent ffc65c9 commit 1a223d0

File tree

3 files changed

+89
-133
lines changed

3 files changed

+89
-133
lines changed

‎README.md‎

Lines changed: 34 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# 📝 Introduction
22
**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.
33

4-
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:
4+
This repository contains the codebase for a series of sites managed by Sitecore. You will find the following sites in this repository:
55
- [Sitecore MVP Site](https://mvp.sitecore.com)
66
- [SUGCON EU Site](https://europe.sugcon.events)
77
- [SUGCON ANZ Site](https://anz.sugcon.events)
@@ -17,94 +17,17 @@ This repository contains the codebase for a series of sites managed by the Techn
1717
# ✋ Prerequisites
1818
- [DotNet 8.0](https://dotnet.microsoft.com/en-us/download)
1919
- [NodeJS 16 LTS](https://nodejs.org/en/download/) (or greater)
20-
- [Docker](https://www.docker.com/) (Not required when running in Edge Development Mode without Docker)
21-
22-
## Docker Compose v2
23-
This repository uses Docker Compose v2. As of June 2023 v1 is no longer supported by Docker. You can read more about the differences between the two versions [here](https://docs.docker.com/compose/compose-v2/).
24-
25-
## Base Image Versions
26-
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](../../wiki/Changing-local-Docker-Image-Base-OS-Versions)
2720

2821
## Okta Account
2922
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](https://developer.okta.com/signup/)
3023

31-
## Auth0 Account
32-
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.
33-
34-
# ▶️ Initializing the repository
35-
36-
You first need to initialize the repository, which will configure how the different application elements will run. There are a series of parameters you can pass into the `init.ps1` script to achieve this, you can find the full list of parameters with their purpose here.
37-
38-
You must be in "administrator mode" to run the `init.ps1` script.
39-
40-
Examples of how to use them can be seen in the setup guides for the different running modes below .
41-
42-
| Parameter | Required for MVP Site | Required for SUGCON Sites | Required for full local | Required for Edge Mode | Purpose |
43-
|-------------------------------|-----------------------|---------------------------|-------------------------|------------------------|-----------------------------------------------------------------|
44-
| LicenseXmlPath | No | No | **Yes** | No | Used to specify the path to the license file |
45-
| AdminPassword | No | No | **Yes** | No | Used to specify the password for the Sitecore admin user |
46-
| InitEnv | No | No | No | No | Used to force a full initialization of the repository |
47-
| Edge_Token | No | No | No | **Yes** | Used to authenticate with XM Cloud, when running in 'Edge Mode' |
48-
| OKTA_Domain | **Yes** | No | No | No | Okta domain used by the MVP Rendering host |
49-
| OKTA_Client_Id | **Yes** | No | No | No | Okta Client Id used by the MVP Rendering host |
50-
| OKTA_Client_Secret | **Yes** | No | No | No | Okta Client Secret used by the MVP Rendering host |
51-
| MVP_Selections_API | No | No | No | No | URL for the MVP Selections API |
52-
| SUCGON_ANZ_CDP_CLIENT_KEY | No | No | No | No | CDP Client key for SUGCON ANZ Site |
53-
| SUCGON_ANZ_CDP_TARGET_URL | No | No | No | No | CDP Target URL for SUGCON ANZ Site |
54-
| SUCGON_ANZ_CDP_POINTOFSALE | No | No | No | No | CDP POS for SUGCON ANZ Site |
55-
| SUCGON_EU_CDP_CLIENT_KEY | No | No | No | No | CDP Client key for SUGCON EU Site |
56-
| SUCGON_EU_CDP_TARGET_URL | No | No | No | No | CDP Target URL for SUGCON EU Site |
57-
| SUCGON_EU_CDP_POINTOFSALE | No | No | No | No | CDP POS for SUGCON EU Site |
58-
| SUCGON_INDIA_CDP_CLIENT_KEY | No | No | No | No | CDP Client key for SUGCON India Site |
59-
| SUCGON_INDIA_CDP_TARGET_URL | No | No | No | No | CDP Target URL for SUGCON India Site |
60-
| SUCGON_INDIA_CDP_POINTOFSALE | No | No | No | No | CDP POS for SUGCON India Site |
61-
| SUCGON2024_EU_CDP_CLIENT_KEY | No | No | No | No | CDP Client key for SUGCON2024 EU Site |
62-
| SUCGON2024_EU_CDP_TARGET_URL | No | No | No | No | CDP Target URL for SUGCON2024 EU Site |
63-
| SUCGON2024_EU_CDP_POINTOFSALE | No | No | No | No | CDP POS for SUGCON2024 EU Site |
64-
| Edge_NoDocker | No | No | No | No | Used to initialize the repo for Edge Developer without Docker |
65-
66-
## Embedded Personalization
67-
Embedded Personalization is disabled locally by default. If you wish to enable it you will need to populate the different `xx_CDP_CLIENT_KEY`, `xx_CDP_TARGET_URL` & `xx_CDP_POINTOFSALE` parameters with valid values and change the `NODE_ENV` parameter from `development` to another value.
68-
69-
# 🏃 Running the Repository
70-
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
71-
- [Full local development Mode](#-running-in-full-local-development-mode)
72-
- [Edge development with Docker](#-running-in-edge-development-mode-with-docker)
73-
- [Edge development without Docker](#-running-in-edge-development-mode-without-docker)
74-
75-
The different parameters on the `up.ps1` script control which mode you want to select, along with some other options.
76-
77-
| Parameter | Required | Purpose |
78-
|---------------|-----------|---------------------------------------------------------------------------------|
79-
| UseEdge | No | Used to run the head applications against Edge, not against a local CM instance |
80-
| SkipBuild | No | Used to skip running the `docker build` command |
81-
| SkipIndexing | No | Used to skip indexing the content |
82-
| SkipPush | No | Used to skip pushing the local content into the CM |
83-
| SkipOpen | No | Okta to skip automatically opening the sites |
84-
85-
86-
## 🐋 Running in Full Local Development Mode
87-
Running in Local Mode will run all of the application elements required on your local machine using Docker
88-
89-
### Initialize your repository for Local Mode
90-
First initialize your repo using the `.init/ps1` script, you can see an example of how to init for 'Local Mode' below
91-
92-
```ps1
93-
.\init.ps1 -InitEnv -LicenseXmlPath "C:\path\to\license.xml" -AdminPassword "DesiredAdminPassword"
94-
```
95-
96-
### Bring up all the application elements for Local Mode
97-
Next, use the `up.ps1` script to bring up all of the containers required for Local Mode.
98-
99-
```ps1
100-
.\up.ps1
101-
```
102-
103-
## 🐋+🌏 Running in Edge Development Mode with Docker
104-
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.
24+
## 🏃‍♀️‍➡️ Running the repository
25+
To run this you will need to deploy this project to an XM Cloud environment.
10526

106-
### Create a new environment and deploy the codebase
107-
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.
27+
### Setting up an XM Cloud Environment
28+
This can be achieved using the CLI by following the steps below from within PowerShell:
29+
- Install the Sitecore CLI
30+
- `dotnet tool install`
10831
- Authenticate with the XM Cloud Deploy Application
10932
- `dotnet sitecore cloud login`
11033
- Create a new XM Cloud Project
@@ -116,64 +39,58 @@ You can follow these steps to create a new XM Cloud Project & Environment, then
11639
- Create a deployment and push the local codebase into XM Cloud
11740
- `dotnet sitecore cloud deployment create -id <<YOUR_ENVIRONMENT_ID>> --upload`
11841
- Access the CM instance that has been created and perform a "Site Publish" to ensure all content items have been pushed to the Edge.
119-
- Generate an Edge Token used to allow your Rendering hosts to authenticate with XM Cloud
120-
- `.\New-EdgeToken.ps1 -EnvironmentId <<YOUR_ENVIRONMENT_ID>>`
121-
- _Record the returned Edge Token, and Edge URL._
12242

12343
If you want more information about the Cloud plugin for the CLI then you access it on the [documentation site](https://doc.sitecore.com/xmc/en/developers/xm-cloud/the-cloud-deployment-command.html).
12444

125-
### Initialize your repository for Edge Development Mode with Docker
126-
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.
127-
128-
```ps1
129-
.\init.ps1 -InitEnv -LicenseXmlPath "C:\path\to\license.xml" -AdminPassword "DesiredAdminPassword" -Edge_Token "<<YOUR_EDGE_TOKEN>>"
130-
```
131-
132-
### Bring up all the application elements for Edge Mode with Docker
133-
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.
134-
135-
```ps1
136-
.\up.ps1 -UseEdge
137-
```
138-
139-
## 💻+🌏 Running in Edge Development Mode without Docker
45+
### Running the MVP Site
14046

141-
### Initialize your repository for Edge Development Mode without Docker
142-
First initialize your repo using the `.init/ps1` script, you will need to pass in the `-Edge_Token` & `-EdgeNoDocker` parameters to ensure that the repository is correct initialized.
47+
#### Populating the Application Settings
48+
To run the MVP site you will need to populate the `./headapps/MvpSite/Mvp.Project.MvpSite.Rendering/appsettings.json`. You will need to provide the following values:
14349

144-
```ps1
145-
.\init.ps1 -InitEnv -Edge_Token "<<YOUR_EDGE_TOKEN>>" -Edge_NoDocker
50+
```json
51+
"Sitecore": {
52+
"InstanceUri": "<<The domain for the CM instance you deployed earlier>>",
53+
"ExperienceEdgeToken": "B2F8A9B9-7203-4DCF-9314-8B28B043347E"
54+
},
14655
```
14756

148-
Running with the `-EdgeNoDocker` switch, will setup configuration files for each of the heads included in this repository. You can then manually run each of them using either NPM or DotNet.
57+
After completing the populate the `appsettings.json` above you will be able to run the MVP Site either directly from within Visual Studio, or by using the DotNet CLI.
14958

150-
### Running the MVP Site
151-
152-
After completing the init setup above you will be able to run the MVP Site either directly from within Visual Studio, or by using the DotNet CLI.
153-
154-
- To run from within Visual Studio, open the `src\XmCloudIntroduction.sln`, ensure that the `Mvp.Project.MvpSite.Rendering` project is set as your StartUp Project, then hit F5.
59+
- To run from within Visual Studio, open the `./headapps/MvpSite/XMC-Introduction-MVP.sln`, ensure that the `Mvp.Project.MvpSite.Rendering` project is set as your StartUp Project, then hit F5.
15560
- The site should then be started loaded in the browser automatically
156-
- To run from the DotNet CLI, open a new terminal window and navigate to the `src\Project\MvpSite\rendering` folder, then run `dotnet restore && dotnet run`
61+
- To run from the DotNet CLI, open a new terminal window and navigate to the `./headapps/MvpSite/Mvp.Project.MvpSite.Rendering` folder, then run `dotnet restore && dotnet run`
15762
- You can then access the site at `https://localhost:5001` or `http://localhost:5000`
15863

15964
### Running the SUGCON Sites
16065

16166
After completing the init setup above you will be able to run the SUGCON Sites directly using the NPM CLI, they are all built using SXA Headless so the process is the same for each of them.
16267

163-
1. **Start the Default Site**:
164-
- Open a new terminal window and navigate to the `src\Project\Sugcon2024\Sugcon` folder.
68+
- Log into the [XM Cloud Deploy Application](https://deploy.sitecorecloud.io/)
69+
- Locate the Project and Environment you created earlier
70+
- Choose the Site you wish to load from the dropdown, e.g. EU for the SUGCON Europe Site.
71+
- Copy the Environment variables that are displayed there
72+
- Create a new `.env` file in the root of the `./headapps/Sugcon2024` folder
73+
- Paste the Environment variables into the `.env` file you just created.
74+
- Start the Default Site
75+
- Open a new terminal window and navigate to the `./headapps/Sugcon2024` folder.
16576
- Run the following command to install dependencies and start the site:
16677
```bash
16778
npm i && npm run start:connected
16879
```
16980
- You can then access the default site at [http://localhost:3000](http://localhost:3000).
17081

171-
2. **Switching Between SUGCON Sites**:
172-
- The default site is set to the EU version. To switch to another SUGCON site, update the `JSS_APP_NAME` variable in the `.env` file.
82+
- Switching Between SUGCON Sites
83+
- To switch to another SUGCON site, update the `JSS_APP_NAME` variable in the `.env` file.
17384
- Available site options include:
17485
- `ANZ`
17586
- `EU`
17687
- `India`
17788
- `NA`
89+
- `Events`
17890

17991
Simply change the `JSS_APP_NAME` in the `.env` file to your desired site, save the changes, and restart the site using the steps above.
92+
93+
## Disconnected offline development
94+
It is possible to mock a small subset of the XM Cloud Application elements to enable offline development. This can allow for a disconnected development experience, however it is recommend to work in the default connected mode.
95+
96+
You can find more information about how setup the offline development experience [here](./local-containers/README.md)

0 commit comments

Comments
 (0)