This blog runs through the setup of a Sitecore v10.1.1 instance using Docker. To familarise with the steps outlined in this blog, refer to setting up docker in your local environment and getting started with a Sitecore instance of the Sitecore documentation.
In my walkthrough, I am simply leveraging on the instructions provided in Sitecore documentation links above. I assume you already have a valid licensed copy of Windows Version 10 Pro or Enterprise edition.
Please note you will not be able to run Docker Desktop for Windows on Windows Home edition as it does not support HyperV features.
Step 1: Check Firewall Rules
I am using VMWare Workstation Player 15 to run a version of Windows 10 20H2. If you are working behind any company firewall, be sure to free up these ports.
You may run Ctrl-R and hit wf.msc. This will open up the Windows Firewall properties and allow you to allow specific ports to be enabled.
If you are running Docker behind your company VPN, I suggest disabling the VPN connection as this can introduce interruption to starting up the connectivity between the containers or the container itself.
If you insist of running Docker whilst connected to your company VPN, refer to Sitecore Gabe’s post for more details on how to possibly make this work for you.
Step 2: Enable nested virtualization
This is a setting on your VMWare application will allow you to spin up VMs or containers within a guest VM. In this case, this setting was required by Docker Desktop to start up containers.
You can find this setting by navigating in to your Guest VM virtual machine settings > Hardware > Processors and ensuring the following is checked.
Step 3: Ensure you have the following enabled on Windows
- Virtual Machine Platform
- HyperV feature and sub-features
Refer to Microsoft article on how to go about enabling HyperV on Windows 10.
Step 4: Install Docker Desktop for Windows.
This will take a few minutes and once installation is completed, restart the Guest VM to ensure Docker is fully installed and configured appropriately.
Right click on the Docker icon, and ensure you switch to Windows Container.
Sitecore containers do not run in Linux containers.
Once restarted, you should be able to find the Docker whale icon loading and completing its startup. You should be notified in the tray icon at the bottom right of your screen when docker has fully started.
Click on the whale icon once, and the below should appear.
Optionally you can also open Powershell and run the following command to check the version of Docker that is running on your system:
Step 5: Clone the Getting Started repository
Go to Docker Examples repository and clone the repository to a suitable location in your hard-drive.
Step 6: Check the Sitecore Version property value.
Depending on you build version of your Windows installation, you must ensure that the correct and compatible Sitecore images are pulled onto the system. Otherwise, you will encounter issues in not able to start up containers.
Inspect the environment file (.env) file and ensure the correct SITECORE_VERSION property value is applied.
In my case, this is 10.1.1-20H2.
Step 7: Change the Isolation property value.
Change the default Isolation property value to process from the default value of ‘default’. Apparently this setting made a difference for me as it allowed my unhealthy containers to start healthy. According to conversations in Sitecore Slack, setting isolation=process allows docker to run in a more stable fashion.
Step 8: Copy over a valid Sitecore license file.
Place a valid copy of your license.xml file in the following directory path C:/License/license.xml. Ensure that the license is able to support the installation of Sitecore v10.1.1.
Step 9: Run the init.ps1 script
Open up Powershell in administrator mode, and run the following command to populate the correct variable values in the environment (.env file).
.\init.ps1 -LicenseXmlPath C:/License/license.xml
This will not overwrite the SITECORE_VERSION property value that was applied in Step 6.
The PS script will also create local self signed certificates for traefik (acts a reverse proxy role to securely transmit information from the client to the Sitecore roles), identity and cm roles.
Once the script is run successfully, you are ready to start up the containers.
Step 10: Start up the Sitecore containers
docker-compose up -d.
-d to detach log streaming of the docker process to the powershell session. Instead, the process is run in the background.
If you have not pulled down the Sitecore images to your local repository, docker will download all the necessary images based on specified properties outlined in environment file. The process takes 1-2 hours to complete all image downloads, depending on your network speed and virtual machine capacity.
You will be able to verify that all containers have successfully started once PS has returned you back to the prompt.
Run docker ps -a to view all running containers and its health status. All statuses must be healthy in order for the Sitecore topology to run on your system.
You can begin to start up the relevant pages and login to Sitecore.
Troubleshooting my installation
I realised when attempting to start up my containers (by running docker-compose up -d), I was consistently hitting the issue whereby the following four service containers failed to start.
Solution 1: If running on Windows 10 20H2, change the following properties in the environment file:
- Ensure the Sitecore version matches with your build version.
- Change the isolation value to process
If you are unsure about your version, type ‘Run’ in the windows search bar at the bottom left hand of your screen and hit ‘Enter’.
Type in ‘winver’.
This will display the build version of your Windows 10 Operation System
Solution 2: Turn off company VPN devices and client chats
If containers still continue to remain unhealthy or instable, I will recommend performing this step.
Solution 3: Stop all ports running in IIS
If containers will remain unhealthy, I will suggest performing an IIS reset and stopping all service to ensure there are no conflicting ports with Docker that are in use.
You can run the below command and repeating docker-compose up -d
Solution 4: SQL Password
SQL_SA_PASSWORD in the
.env could also solve the issue. It is Important to run the
clean.ps1 to clean up generated database files prior to running docker compose up again. Once done, rerun again
docker-compose up in case if you are using the Getting Started template.
Related documentation: https://containers.doc.sitecore.com/docs/troubleshooting
To resolve, change the SQL password in SQL_SA_PASSWORD to fit the default SQL Server policy. After changing the password in the .env file, remember to clear the mounted SQL data folder after running docker-compose down. You can manually delete its contents, or use a clean script (see the clean.ps1 example in the the Docker Examples repository).
I hope this article walkthrough helped you to get through setting up a first running instance of Sitecore v10.1.1.
In my next upcoming article, I will demonstrate how I went about troubleshooting issues with unhealthy Sitecore containers and what led me to make the next best decisions.