This article discusses on how you can go about setting up a running Sitecore 9.3 with SXA and JSS installed onto a simple xp0 topology setup. It attempts to detail some walkthrough steps which can help you get started with an instance and prepare it for a JSS local development in Sitecore connected mode.
It is a Part 1 out of 2 series in setting up a JSS SXA vanilla instance in Sitecore and subsequently deploying a JSS app into the running instance.If you have one that is already running in Sitecore docker, you can go straight to Part 2 of my next article.
I am using a Windows 10 20H2 Build version to host my docker containers. As such, please be sure to target your Sitecore versions to 20H2. As Windows requires the host OS version to match the container OS version.
This article assumes you have the pre-requisites setup to run Sitecore containers using Docker in a Windows environment. If you have not gone through the pre-requisites on setting up your environment for Docker, I suggest you follow Sitecore’s well documented article on setting up the environment before proceeding further.
STEP 1: setup vanilla sITECORE 9.3 SXA AND JSS INSTANCE
Clone the Sitecore Docker Images repository from https://github.com/Sitecore/docker-images
Once downloaded, you will have a working directory with the source files as below.
Browse to the build folder. Open up Windows Powershell in ‘Administrator’ mode and initialize the environment with the license path variable setup. In my case, I stored my valid Sitecore license file in a specific folder path.
.\Set-LicenseEnvironmentVariable.ps1 -Path E:\License\license.xml -PersistForCurrentUser
STEP 2: build sitecore images
In the same Windows Powershell session, run the following command to commence pulling down the Sitecore 9.3 base runtime images, JSS and SXA images.
.\Build.ps1 -SitecoreVersion 9.3.0 -OSVersion 20H2 -IncludeSxa -IncludeJss
The process will take a few hours to complete pulling and building the images onto your Docker station. Once the build completes successfully, you will be able to view the list of installed images.
Finally, browse to the windows/test/9.3.x folder (containing the various Sitecore topology docker compose files) within your working directory to stand up your a fresh vanilla 9.3 instance that comes installed with SXA and JSS! In my case, I chose the XP topology.
##Start up containers docker-compose -f .\docker-compose.xp.sxa.jss.yml up -d ##Stop all containers docker-compose -f .\docker-compose.xp.sxa.jss.yml down
Run docker ps -a to view the list of containers which are running and inspect their status. Ensure these are ready and in healthy state.
Once all containers have started and are in a healthy state, you are ready to browse to the Sitecore CMS instance.
At this point, you have successfully setup a running Sitecore instance with SXA and JSS installed.
In the next step, we setup the hostnames and self signed certificate for our CM container so that we can prepare this for local development with our sample JSS Angular app.
STEP 3: SETUP HOSTNAME with self signed certificate for cm container
In this section, we will aim to setup a custom hostname – jss.dev.local.
First, we will aim to create a wildcard self signed certificate that captures subdomains suffixed with *.dev.local.
Michael West has an incredible article which describes how to go about setting up a self signed certificate with Docker with HTTPs. Follow the instructions outlined in his article.
A quick summary below:
- Clone Michael West’s repository: https://github.com/michaellwest/docker-https.git
- Open the folder Startup and with an elevated PowerShell console run the following command: `.\createcert.ps1 -certificatename cert -dnsNameList “*.dev.local”
- Copy the 4 generated `cert.*` files in the `startup` folder in this Sitecore Docker Images cloned repository (`\build\windows\tests\9.3.x\startup`).
See below figure.
Next, we configure our hostname for your CM container.
As a pre-requisite for Docker to be able to standup IIS hostnames which map to our running containers, there is this amazing module which was written by Rob Ahnemann – Windows Host Writer which allows Docker to handle updating of running container hostnames onto your host file. Thank you Rob for this nifty service and thank you to Rock Paper Sitecore’s article for pointing out Rob’s service.
Open up the docker-compose yaml file which will be used to start up the containers.
Add this new service as part of the services collection.
monitor: image: rahnemann/windows-hosts-writer:1.1 volumes: - C:\windows\system32\drivers\etc:C:\driversetc - source: '\\.\pipe\docker_engine' target: '\\.\pipe\docker_engine' type: npipe
You do not need to manually download anything. In your next run of docker-compose up -d, Docker will be smart to pull and build this image onto your Docker station and subsequently listen for host headers configured for other running containers.
Add the following to the cm service.
The code snippet below replaces the entrypoint with the the startup powershell script that comes with cloned Sitecore Docker repository. This script will be responsible in retrieving the environment host header configured for the container service and subsequently add the host header as an HTTPs binding. This binding is then attached to the certificate thumbprint of the generated wildcard self signed certificate in the trusted root store. Once the above is done, the script subsequently runs the Development.ps1 script.
Replace entrypoint: powershell.exe -Command "& C:\\tools\\entrypoints\\iis\\Development.ps1" with entrypoint: powershell.exe -NoLogo -NoProfile -File c:\startup\\startup.ps1
The snippet below adds port bindings for HTTPS:44022:443 so that the container can run with the HTTPS protocol.
ports: - "44001:80" - "44002:443" networks: default: aliases: - jss.dev.local
Step 4: Add volume section for CM Container
Next we will require to setup the volume for the container so that we can map the location of the startup script stored in our working directory to the folder stored inside the container. This allows the container to pick up the startup script and execute it on a docker compose up.
volumes: - .\deploy\website:c:\src - .\startup:c:\startup - .\deploy\serialization:c:\Serialization - .\data\cm:c:\inetpub\wwwroot\App_Data\logs
At this point, save the updates made in Step 3 and Step 4 in the docker-compose yaml. In my case again, this is the docker-compose.xp.sxa.jss.yml file.
step 5: run docker compose up
Run a docker-compose up again.
You will notice that the host file gets updated automatically when the containers are in a ready and healthy state.
Next, open up a browser and key in https://jss.dev.local and VOILA. You will notice the browser now displays the page successfully with the valid self signed certificate setup.
The above was a simple host header and binding setup for a CM container.
You can also add host headers to further containers. Typically you will setup the same for your CD container which you can repeat with the same steps as the above. You will provide appropriate host header names to differentiate your CM and CD urls.
Special thanks again to the Sitecore community for showing the way!
In my next article, I will show you how you can go about creating and deploying a basic sample Angular JSS app to an SXA JSS site instance hosted on this running Sitecore Docker xp0 topology.