The PLAY! Summit demo comes with a Docker compose environment for a Sitecore XM1 topology.
The included docker-compose.yml
is a stock XM1 environment from the Sitecore Container Support Package. All changes/additions for this solution are located in the docker-compose.override.yml
file.
The environment has some extra containers:
- rendering: A Next.js rendering host container to render the main website. It runs the website in development mode with hot reloading.
- init: An initialization container that runs some startup jobs (mostly when deployed to AKS and Vercel) and warms up the main website.
- headstart-middleware, headstart-seller, cosmos, and headstart-storage: Set of containers to run the OrderCloud Headstart seller UI when demoing PLAY! Shop.
Do these prerequisites before you start the main website or the kiosk projects.
Ensure you have installed and followed the global prerequisites.
Docker Desktop must be installed.
- Ensure you are running Windows containers:
- From the Docker Desktop taskbar icon contextual menu (right click), you can toggle which daemon (Linux or Windows) the Docker CLI talks to. Select "Switch to Windows containers..." to use Windows containers.
- Ensure that Docker Compose V2 is enabled:
- From the Docker Desktop taskbar icon contextual menu (right click), choose "Settings".
- In the left tab group, navigate to the "General" tab.
- Ensure that the "Use Docker Compose V2" option is checked.
- Click the "Apply & Restart" button to restart your Windows Docker engine.
You must use an elevated/Administrator Windows PowerShell 5.1 prompt for these commands, PowerShell 7 is not supported at this time.
In an elevated PowerShell terminal:
-
If your local IIS is listening on port 443, you'll need to stop it.
iisreset /stop
-
Before you can run the containers, you will need to run a script to prepare the following for the Sitecore container environment:
- A valid/trusted wildcard certificate for
*.edge.localhost
- Hosts file entries for
edge.localhost
- Required environment variable values in
.env
for the Sitecore instance
The provided
init.ps1
will take care of them.You must use an elevated/Administrator Windows PowerShell 5.1 prompt for this command, PowerShell 7 is not supported at this time.
.\init.ps1 -InitEnv -LicenseXmlPath "C:\path\to\your\license.xml" -AdminPassword "DesiredAdminPassword"
⚠ WARNING: Never commit the changes to the
.env
files unless they are changes you manually made while working on a feature/fix. - A valid/trusted wildcard certificate for
-
If this is your first time using
mkcert
with NodeJs, you will need to set theNODE_EXTRA_CA_CERTS
environment variable. This variable must be set in your user or system environment variables. Theinit.ps1
script will provide instructions on how to do this.- Be sure to restart your terminal or VS Code for the environment variable to take effect.
In an elevated PowerShell terminal:
-
Ensure you have run the prerequisites above.
-
After completing this environment preparation, run the startup script from the solution root:
.\up.ps1
-
A browser tab will open after the containers are started for the script to get an Identity Server token.
- You must log in using the
superuser
admin account and the password you choose previously. - Then you must click the
Yes, Allow
button to confirm the authorization request. - You can close the browser tab.
- You must log in using the
In an elevated PowerShell terminal:
.\down.ps1
A script can be used to "reset" the state of your containers. It clears all mounted data and deployed/copied build output. In an elevated PowerShell terminal:
-
Ensure you have stopped the containers.
-
Run the script:
.\clean.ps1
If you have trouble with Docker, it is recommended to run the Sitecore containers prerequisite checker script by Gabriel Streza.
If you have issues building Docker images or if that prerequisite checker identifies a conflicting driver, it might be caused by the "Box.com" software. If it is installed on your system and you are not using it, try uninstalling it.
When starting the containers, you might encounter an error mentioning open \.\pipe\docker_engine_windows: The system cannot find the file specified.
Docker Desktop v4.14 and 4.15 have an issue with Windows containers.
There are a few solutions available:
- Rollback to Docker Desktop v4.13.
- Running a few commands and creating a few files.
- Creating a registry key.
For more details about the problem, causes, and solutions, read Jeremy Davis' blog post.