Running a Sitecore Docker instance is a game-changer for developers. It streamlines deployments, accelerates local setup, and ensures consistency across environments. However, performance can suffer – even on high-end laptops – if Docker resources aren’t properly optimized, especially after a hardware upgrade.

I recently faced this exact issue. My Sitecore XP0 instance, running on Docker, became noticeably sluggish after I upgraded my laptop. Pages loaded slowly, publishing dragged on forever, and SQL queries timed out.

The good news? The fix was surprisingly simple: allocate more memory to the proper containers using docker-compose.override.yml

What Went Wrong?

After the upgrade, I noticed:

• The Content Management (CM) UI was lagging.
• Publishing and indexing took ages.
• SQL queries and Sitecore services kept timing out.

At first, this was puzzling because my new laptop had better specs. However, I then realized that Docker was still running with outdated memory limits for containers. By default, these limits are often too low for heavy workloads, such as Sitecore.

Root Cause

Docker containers run with memory constraints either from:

• docker-compose.override.yml
• Docker Desktop global settings

When memory is too low, Sitecore roles such as CM and MSSQL can’t perform optimally. They need significant RAM for caching, pipelines, and database operations.

The Solution: Increase Memory in docker-compose.override.yml

To fix the issue, I updated the memory allocation for key containers (mssql and cm) in the docker-compose.override.yml file.

Here’s what I did:

Before

mssql: 
 mem_limit: 2G

After

mssql:
  mem_limit: 4GB

cm:
  image: ${REGISTRY}${COMPOSE_PROJECT_NAME}-xp0-cm:${VERSION:-latest}
  build:
    context: ./build/cm
    args:
      BASE_IMAGE: ${SITECORE_DOCKER_REGISTRY}sitecore-xp0-cm:${SITECORE_VERSION}
      SPE_IMAGE: ${SITECORE_MODULE_REGISTRY}sitecore-spe-assets:${SPE_VERSION}
      SXA_IMAGE: ${SITECORE_MODULE_REGISTRY}sitecore-sxa-xp1-assets:${SXA_VERSION}
      TOOLING_IMAGE: ${SITECORE_TOOLS_REGISTRY}sitecore-docker-tools-assets:${TOOLS_VERSION}
      SOLUTION_IMAGE: ${REGISTRY}${COMPOSE_PROJECT_NAME}-solution:${VERSION:-latest}
      HORIZON_RESOURCES_IMAGE: ${SITECORE_MODULE_REGISTRY}horizon-integration-xp0-assets:${HORIZON_ASSET_VERSION}
  depends_on:
    - solution
  mem_limit: 8GB
  volumes:
    - ${LOCAL_DEPLOY_PATH}\platform:C:\deploy
    - ${LOCAL_DATA_PATH}\cm:C:\inetpub\wwwroot\App_Data\logs
    - ${HOST_LICENSE_FOLDER}:c:\license
    - ${LOCAL_ITEM_PATH}:c:\items-mounted

How to Apply the Changes

1. Open docker-compose.override.yml.
2. Locate the mssql and cm services.
3. Update or add the mem_limit property:
   • mssql → 4GB
   • cm → 8GB
4. Rebuild containers:

    
    docker compose down
    docker compose up --build -d

5. Check updated limits:

  docker stats

Impact After Change

After increasing memory:

• CM dashboard loaded significantly faster.
• Publishing operations completed in less time.
• SQL queries executed smoothly without timeouts.

Why It Works

Sitecore roles (especially CM) and SQL Server are memory-hungry. If Docker allocates too little memory:

• Containers start swapping.
• Performance tanks.
• Operations fail under load.

By increasing memory:

• CM handles ASP.NET, Sitecore pipelines, and caching more efficiently.
• SQL Server caches queries better and reduces disk I/O.

Pro Tips

• Ensure Docker Desktop or Docker Engine is configured with enough memory globally.
• Avoid setting memory limits too high if your laptop has limited RAM.
• If using multiple Sitecore roles, adjust memory allocation proportionally.

Final Thoughts

A simple tweak in docker-compose.override.yml can drastically improve your Sitecore Docker instance performance. If your Sitecore CM is sluggish or SQL queries are slow, try increasing the memory limit for critical containers.

About eight years ago, I was introduced to Docker during a meetup at a restaurant with a coworker. He was so engrossed in discussing the Docker engine and containers that he barely touched the hors d’oeuvres. I was skeptical. 

I was familiar with Virtual Machines (VMs) and appreciated the convenience of setting up application servers without worrying about hardware. I wanted to know what advantages Docker could offer that VMs couldn’t. He explained that instead of virtualizing the entire computer, Docker only virtualizes the OS, making containers much slimmer than their VM counterparts. Each container shares the host OS kernel and often binaries and libraries. 

Curious, I wondered how AEM would perform inside Docker—a Java application running within the Java Virtual Machine, inside a Docker container, all on top of a desktop PC. I expected the performance to be terrible. Surprisingly, the performance was comparable to running AEM directly on my desktop PC. In hindsight, this should not have been surprising. The Docker container shared my desktop PC’s kernel, RAM, CPUs, storage, and network allowing the container to behave like a native application. 

I’ve been using Docker for my local AEM development ever since. I love how I can quickly spin up a new author, publish, or dispatch environment whenever I need it and just as easily tear it down. Switching to a new laptop or PC is a breeze — I don’t have to worry about installing the correct version of Java or other dependencies to get AEM up and running. 

In this blog, we’ll discuss running AEM author, publisher, and dispatcher within Docker and the setup process.

Setup Requirements

The AEM SDK, which includes the Quickstart JAR and Dispatcher tools, is necessary for this setup.  Additionally, Apache Maven must be installed. For the Graphical User Interface, we will use Rancher Desktop by SUSE, which operates on top of Docker’s command-line tools.  While the Docker engine itself is open source, Docker Desktop, the GUI distributed by Docker, is not. 

Step One: Installing Rancher Desktop

Download and Install Rancher Desktop by SUSE. Installing Racker Desktop will provide the Docker CLI (command line interface). If you wish to install the Docker CLI without Rancher Desktop, run the following command:

Windows

Install WinGet via the Microsoft store.

winget install --id=Docker.DockerCLI -e

Mac

Install Homebrew: 

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh) 

brew cask install docker

Step Two: Creating the “AEM in Docker” folder

Create a folder named “aem-in-docker”.  Unzip the contents of the AEM SDK into this folder.  Copy your AEM “license.properties” file to this directory. 

Step Three: Creating the subfolders to contain the Docker Image instructions

Make three subfolders within your “aem-in-docker” folder named “base”, “author”, and “publish”. 

Your “aem-in-docker” folder should look something like this: 

Step Four: Creating the Base Docker Image instruction (Dockerfile)

Create a file named “Dockerfile” within the “base” subdirectory.

Ensure the file does not have an extension.  Set the contents of the file to the following:

FROM ubuntu
# Setting the working directory
WORKDIR /opt/aem
# Copy the license file
COPY license.properties .
# Copy Quickstart jar file
COPY aem-sdk-quickstart-2024.8.17465.20240813T175259Z-240800.jar cq-quickstart.jar
# Install Java, Vim, and Wget.  Install Dynamic Media dependencies.
RUN apt-get update && \
    apt-get install -y curl && \
    apt-get install -y software-properties-common && \
    add-apt-repository ppa:openjdk-r/ppa && \
    apt-get update && \
    apt-get install -y openjdk-11-jdk vim ca-certificates gnupg wget imagemagick ffmpeg fontconfig expat freetype2-demos
# Unack the Jar file
RUN java -jar cq-quickstart.jar -unpack
# Set the LD_LIBRARY_PATH environmental variable
ENV LD_LIBRARY_PATH=/usr/local/lib

This file directs Docker to build a new image using the official Ubuntu image as a base. It specifies the working directory, copies the license file and the quickstart file into the image (note that your quickstart file might have a different name), installs additional packages (like Java, Vim, Wget, and some Dynamic Media dependencies), unpacks the quickstart file, and sets some environment variables.

Step Five: Create the Base Docker Image

Run the following command from within the “aem-in-docker” folder.

docker build -f base/Dockerfile -t aem-base .

It should take a few minutes to run. After the command has been completed run:

docker image ls

You should see your newly created “aem-base” image.

Step Six: Creating the Author Docker Image instruction (Dockerfile)

Create a file named “Dockerfile” within the “author” subdirectory.

Set the contents of the file to the following:

# Use the previously created aem-base
FROM aem-base

# Expose AEM author in port 4502 and debug on port 5005
EXPOSE 4502
EXPOSE 5005
VOLUME ["/opt/aem/crx-quickstart/logs"]
# Make the container always start in Author mode with Port 4502.  Add additional switches to support JAVA 11: https://experienceleague.adobe.com/en/docs/experience-manager-65/content/implementing/deploying/deploying/custom-standalone-install.  Add the Dynamic Media runmode.
ENTRYPOINT ["java", "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005", "-XX:+UseParallelGC", "--add-opens=java.desktop/com.sun.imageio.plugins.jpeg=ALL-UNNAMED", "--add-opens=java.base/sun.net.www.protocol.jrt=ALL-UNNAMED", "--add-opens=java.naming/javax.naming.spi=ALL-UNNAMED", "--add-opens=java.xml/com.sun.org.apache.xerces.internal.dom=ALL-UNNAMED", "--add-opens=java.base/java.lang=ALL-UNNAMED", "--add-opens=java.base/jdk.internal.loader=ALL-UNNAMED", "--add-opens=java.base/java.net=ALL-UNNAMED", "-Dnashorn.args=--no-deprecation-warning", "-jar", "cq-quickstart.jar", "-Dsling.run.modes=author,dynamicmedia_scene7", "-p", "4502", "-nointeractive"]

This file instructs Docker to create a new image based on the “aem-base” image. It makes ports 4502 and 5005 available (5005 for debugging purposes), sets up a mount point at “/opt/aem/crx-quickstart/logs”, and specifies the command to run when the image is executed.

Step Seven: Create the Author Docker Image

Run the following command from within the “aem-in-docker” folder.

docker build -f author/Dockerfile -t aem-author .

After the command has been completed run:

docker image ls

You should see your newly created “aem-author” image.

Step Eight: Creating the Publisher Docker Image instruction (Dockerfile)

Create a file named “Dockerfile” within the “publish” subdirectory.

Set the contents of the file to the following:

# Use the previously created aem-base
FROM aem-base
# Expose AEM publish in port 4503 and debug on port 5006
EXPOSE 4503
EXPOSE 5006
VOLUME ["/opt/aem/crx-quickstart/logs"]
# Make the container always start in Author mode with Port 4503.  Add additional switches to support JAVA 11: https://experienceleague.adobe.com/en/docs/experience-manager-65/content/implementing/deploying/deploying/custom-standalone-install.  Add the Dynamic Media runmode.
ENTRYPOINT ["java", "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5006", "-XX:+UseParallelGC", "--add-opens=java.desktop/com.sun.imageio.plugins.jpeg=ALL-UNNAMED", "--add-opens=java.base/sun.net.www.protocol.jrt=ALL-UNNAMED", "--add-opens=java.naming/javax.naming.spi=ALL-UNNAMED", "--add-opens=java.xml/com.sun.org.apache.xerces.internal.dom=ALL-UNNAMED", "--add-opens=java.base/java.lang=ALL-UNNAMED", "--add-opens=java.base/jdk.internal.loader=ALL-UNNAMED", "--add-opens=java.base/java.net=ALL-UNNAMED", "-Dnashorn.args=--no-deprecation-warning", "-jar", "cq-quickstart.jar", "-Dsling.run.modes=publish,dynamicmedia_scene7", "-p", "4503", "-nointeractive"]

Step Nine: Create the Publisher Docker Image

Run the following command from within the “aem-in-docker” folder.

docker build -f publish/Dockerfile -t aem-publish .

After the command has been completed run:

docker image ls

You should see your newly created “aem-publish” image.

Step Ten: Create the Adobe Network

Let’s set up a network to connect Docker containers and facilitate data sharing between them.

docker network create adobe

Step Eleven: Run the Author Docker Image

It’s time to run our Author Docker Image. First, create a local directory for the logs volume specified in the Dockerfile. Within the author subdirectory, create a directory named “logs.” Run the following command within the new logs folder:

Windows

docker run -d --name author -p 4502:4502 -p 5005:5005 --network adobe -v ${PWD}:/opt/aem/crx-quickstart/logs aem-author

macOS/Linux

docker run -d --name author -p 4502:4502 -p 5005:5005 --network adobe -v `pwd`:/opt/aem/crx-quickstart/logs aem-author

The command will return the ID of the new Docker container. It may take some time for the new AEM instance to start. To check its status, you can monitor the “error.log” file in the logs directory to check its status.

Windows

Get-Content -Path .\error.log -Wait

macOS/Linux

tail -f error.log

After AEM has finished starting up, check that everything is loading correctly by visiting: http://localhost:4502/aem/start.html.

Let’s stop the AEM container for the time being:

docker stop author

Step Twelve: Run the Publisher Docker Image

It’s time to run our Publisher Docker Image.  First, create a local directory for the logs volume specified in the Dockerfile. Within the publish subdirectory, create a directory named “logs.”  Run the following command within the new logs folder:

Windows

docker run -d --name publish -p 4503:4503 -p 5006:5006 --network adobe -v ${PWD}:/opt/aem/crx-quickstart/logs aem-publish

macOS/Linux

docker run -d --name publish -p 4503:4503 -p 5006:5006 --network adobe -v `pwd`:/opt/aem/crx-quickstart/logs aem-publish

The command will return the ID of the new Docker container. It may take some time for the new AEM instance to start. To check its status, you can monitor the “error.log” file in the logs directory to check its status.

Windows

Get-Content -Path .\error.log -Wait

macOS/Linux

tail -f error.log

After AEM has finished starting up, check that everything is loading correctly by visiting: http://localhost:4503/content.html.  You will see a “Not Found” page.  That is fine for now.

Let’s stop the AEM container for the time being:

docker stop publish

Step Thirteen: Start the Containers via Rancher Desktop

Open Rancher Desktop and go to the Containers tab in the left navigation pane. To start individual containers, check the box in the State column for each container you want to start, then click the Start button. To start all containers at once, check the box in the header row of the State column, and then click the Start button. Let’s go ahead and start all containers.

If you prefer using the command line, you can run:

docker start author
docker start publish

Step Fourteen: Create an AEM Project and install it on the Author and Publish instance

Since Docker’s mascot is a whale, I thought it would be fun to name our new AEM project after a famous fictional whale: Monstro from Pinocchio.

Run the following command from a command line (Note: you may have to run this command with elevated privileges):

mvn -B archetype:generate -D archetypeGroupId=com.adobe.aem -D archetypeArtifactId=aem-project-archetype -D archetypeVersion=50 -D aemVersion=cloud -D appTitle="Monstro" -D appId="monstro" -D groupId="com.monstro" -D frontendModule=general -D includeExamples=n

Once this project has been created, let us build and deploy it to our Author instance.

Run the following command from within the “Monstro” project:

mvn clean install -PautoInstallSinglePackage

Check that the project is installed by visiting the following URL to view the results: http://localhost:4502/editor.html/content/monstro/us/en.html.  You should see the following:

Now, let us build and deploy the project to our Publish instance.

Run the following command from within the “Monstro” project:

mvn clean install -PautoInstallSinglePackagePublish

Verify that the project is installed by visiting this URL: http://localhost:4503/content/monstro/us/en.html.  Installation may take up to five minutes. After this period, you should see the following:

Step Fifteen: Set up the Publish Agent on Author

It’s time to configure the publish agent on our author instance. Go to this URL: http://localhost:4502/etc/replication/agents.author/publish.html.

Click the “Edit” button (next to settings).

• Click the checkbox next to “Enabled”
• Enter “admin” in the “Agent User Id” field
• Navigate to the Transport tab and enter the following in the URI field:  http://publish:4503/bin/receive?sling:authRequestLogin=1
• Instead of using “localhost,” the hostname for our publish instance is our container’s name, “publish”
• In the “username” field, enter “admin,” and in the “password” field, enter the admin’s password
• Click the “OK” button to save the Agent settings
• Click the “Test Connection” link, and the replication test should be successful

Step Sixteen: Publish content from the Author

Go back to http://localhost:4502/editor.html/content/monstro/us/en.html. Edit the “Hello, World” component by changing the text from “lalala :)” to “Monstro is the enormous, fearsome whale from Disney’s 1940 animated film Pinocchio.” Verify the update and publish the page. Then, check http://localhost:4503/content/monstro/us/en.html to see your changes on the Publisher as well.

Step Seventeen: Create the Dispatcher Container

Make sure the publisher instance is running before proceeding. Extract the AEM SDK Dispatcher tools.

Windows

Expand-Archive .\aem-sdk-dispatcher-tools-2.0.222-windows.zip
Rename-Item -Path .\aem-sdk-dispatcher-tools-2.0.222-windows -NewName dispatcher-sdk-2.0.222

macOS/Linux

chmod +x ./aem-sdk-dispatcher-tools-2.0.222-unix.sh
./aem-sdk-dispatcher-tools-2.0.222-unix.sh

Since we’ve set up a custom network for our AEM containers, the docker run script won’t function correctly because it doesn’t recognize this network. Let’s modify the docker run script.

Windows

Open “dispatcher-sdk-2.0.222\bin\docker_run.cmd” in your favorite editor.

Add the “–network adobe” argument to the docker command inside the “else” statement.

macOS/Linux

Open “dispatcher-sdk-2.0.222/bin/docker_run.sh” in your favorite editor.

Add the “–network adobe” argument to the docker command inside the “else” statement.

Execute the docker run script with the following parameters. Be sure to replace the dispatcher source path with the path to your “monstro” source.

Windows

.\ dispatcher-sdk-2.0.222\bin\docker_run.cmd C:\Users\shann\Sites\monstro\dispatcher\src publish:4503 8080

macOS/Linux

./dispatcher-sdk-2.0.222/bin/docker_run.sh ~/Sites/monstro/dispatcher/src publish:4503 8080

Once the text stream in your terminal has stopped, go to http://localhost:8080/.  You should see the following:

Open Rancher Desktop and navigate to the Containers tab. Locate the container with an unusual name. If you stop this container, it won’t be possible to start it again. Please go ahead and stop this container. The dispatcher code running in your terminal will also terminate. We want this container to be more permanent, so let’s make some additional changes to the docker run script.

Windows

Open “dispatcher-sdk-2.0.222\bin\docker_run.cmd” in your favorite editor.

macOS/Linux

Open “dispatcher-sdk-2.0.222/bin/docker_run.sh” in your favorite editor.

Add the “–name dispatcher” argument to the “docker” command within the “else” statement. Also, remove the “–rm” switch. According to Docker documentation, the “–rm” switch automatically removes the container and its associated anonymous volumes when it exits, which is not what we want.

Windows

macOS/Linux

Run the docker run command in your terminal again:

Windows

.\ dispatcher-sdk-2.0.222\bin\docker_run.cmd C:\Users\shann\Sites\monstro\dispatcher\src publish:4503 8080

macOS/Linux

./dispatcher-sdk-2.0.222/bin/docker_run.sh ~/Sites/monstro/dispatcher/src publish:4503 8080

Open Rancher Desktop and go to the Containers tab. You should see a container named “dispatcher.” Stop this container. The dispatcher code running in your terminal will terminate, but the container will remain in Rancher Desktop. You can now stop and restart this container as many times as you’d like. You can also start and stop the dispatcher via the command line:

docker start dispatcher

docker stop dispatcher

Docker Provides Value and Flexibility

We have an author and publisher AEM instance running inside a Docker container. Additionally, we have a dispatcher container created using the source from the Monstro project. Although this dispatcher container isn’t very useful, the advantage of Docker is that you can easily delete and create new containers as needed.

I hope you found this blog helpful. I’ve been using Docker on my local machine for the past eight years and value the flexibility it provides. I can’t imagine going back to managing a local AEM instance or dealing with Apache configurations to get the dispatcher working. Those days are behind me.

That was a decent gap since 1.5 years ago Sitecore previously released a feature-full version of their XM/XP platform, namely 10.3 was released on December 1st of 2022. That is why I was very excited to look through the newest release of the vendor’s self-hosted platforms and familiarize myself with its changes.

First and foremost, the 10.4 platforms could be exclusively obtained from a new download page which has moved to its new home at Sitecore Developer Portal. I recommend bookmarking that for the current and all future releases.

Release Notes

There is a list of impressive 200 changes and improvements coming along with official Release Notes. I recommend going through it especially paying attention to the Deprecated and Removed sections.

So, what’s New?

From the important features and changes, I’d focus on a few:

• XM to XM Cloud Migration Tool for migrating content, media, and users from a source XM instance to an XM Cloud environment. This tool provides an aid for the routine and sometimes recurring back-end migrations, so our customers/partners can focus on migrating and developing new front-end sites.
• xDB to CDP Migration Tool for transferring site visitor contact facets to Sitecore’s CDP and Personalize products, and also via Sitecore Connect to external systems. This provides the ability to interwork with or eventually adopt other SaaS based innovations.
• New /sitecore/admin/duplicates.aspx admin folder page addressing the change in media duplication behavior (now, the blobs are in fact also duplicated) – run it upon the migration to 10.4 in order to change the media items accordingly.
• Added a new Codeless Schema Extension module, enabling business users to extend the xConnect schema without requiring code development. If that on was available earlier – it could significantly boost xDB usage by marketers. It will be generally available in mid-May 2024.
• Improved accessibility to help content authors with disabilities.
• Sitecore Client Content Reader role allows access into CM without the risk of breaking something – it was a frequently requested feature.
• It is now possible to extract data from xDB and transform the schema for external analytics tools such as Power BI.
• GraphQL is enabled by default on the CM container instance in the local dev – which totally makes sense to me.
• Underlying dependencies updated to the latest – SQL Server 2022, latest Azure Kubernetes Service, Solr 8.11, etc.

Containers

Spinning up Sitecore in local Docker containers used to be the easiest way of starting up. However, the most important fact you have to consider for a containerized setup is that base images are only available for ltsc2022 platform, at least for now. If you are a lucky one using a Windows 11 machine – you get the best possible performance running Sitecore in Process isolation mode. Otherwise, you may struggle with Hyper-V compatibility issues.

The other thing I noticed is that SitecoreDockerTools is simply set to pull the latest version which is 10.3.40 at the time of writing.

Also, Traefik image remains on one of the older versions (not versions 3.x of Traefik, but 2.9.8 which was even older before – v2.2.0) that do not support ltsc2022 and therefore still uses Hyper-V isolation. You can however fix that manually to have each and every image running fast in Process isolation mode. As always, it helps a lot to examine the list of available published images as your own exercise as some were standardized.

Compared to previous versions, this one seems to be lightweight, with no helpful PowerShell scripts for up  & down containers (so we use docker-compose directly) as well as clean-up scripts and others. As before, it supports all three default topologies – XP0, XM1 and XP1.

Sitecore Gallery Tips:

• Tip 1: Sitecore Gallery has recently moved from MyGet https://sitecore.myget.org/F/sc-powershell/api/v2 to Sitecore hosted NuGet https://nuget.sitecore.com/resources/v2.
• Tip 2: don’t forget to update the PackageManagement and PowerShellGet modules from PSGallery if needed, as below:

Install-Module -Name PackageManagement -Repository PSGallery -Force -AllowClobber
Install-Module -Name PowerShellGet -Repository PSGallery -Force -AllowClobber

If for some reason you cannot or are unwilling to use containers, there are other options: SIA and manual installations from a zip archive. Over the past years, I have created a tool called Sifon that is effectively better than SIA, because it can also install all the prerequisites, such as Solr and SQL Server of the required versions, along with downloading the necessary resources from the developer portal. I will add the support for 10.4 in the next few days or a week.

10.4 dashboard

Upon the installation, you will see the Sitecore Dashboard:

Version 10.4 now operates 010422 revision:

SXA

This crucial module comes in the correspondent version 10.4 along with a newer 7.0 version of Sitecore PowerShell Extensions module. The biggest news about this module is that it now supports Tailwind, in the same way as XM Cloud does:

Conclusion

In general, time will prove what I expect this version to be – the most mature version of Sitecore, working faster and more reliably with the updated underlying JavaScript-dependent libraries. I am impatiently waiting for the hot things such as AI integrations and the delayed feature set promised to appear later the month in May 2024 to explore and share about.

In the first part of this 3 part blog series, we did a deep dive in to the prerequisites required for upgrading Sitecore databases from 9.3.0 to 10.3.1 and steps needed to prepare for it.

In the second part, we went over the steps that need to be performed to do the actual upgrade of databases.

To conclude this series, we will take a look at steps that need to be executed after we have upgraded our Sitecore databases and code base to 10.3.1

Post Upgrade Steps

1. 1. Go to https://dev.sitecore.net/Downloads/Sitecore_Experience_Platform/103/Sitecore_Experience_Platform_103_Update1.aspx and execute the steps in the “Upgrade post-steps” section of the “Upgrade Container Deployment Guide” guide. We populated Solr managed schema and rebuilt the Indexes along with these steps.
   2. Module Upgrade – As part of the code/docker changes for the upgrade, my teammates had already updated the .env file in the solution to use latest(10.3.0) version of SPE and SXA modules. P.S:- As 10.3.1 assets were not present/released at that time so we used 10.3.0 assets.
      

      SPE and SXA image references in .env file

      • For SXA Module specifically, we performed the steps mentioned in the upgrade guide here , specially the steps in “Updating existing content” section.
      • While content was being updated, we got this error but we let the process run and monitored its progress via Sitecore logs.
        

        Error while updating existing content

      • Here is a screenshot of Sitecore logs reflecting progress being made by content upgrade script.
        

        Sitecore logs reflecting progress of content upgrade script

      • To confirm if the upgrade script executed successfully, look for log entry similar to “Job ended: SPE – “PowerShell script Results” – “Express Upgrade””.
        

        SPE express upgrade completed

      • After the content was updated, we made sure that the item “/sitecore/system/Settings/Foundation/Experience Accelerator/Upgrade/Current” contained the latest version number “11400” as expected.
        

        Experience accelerator version number validation

   3. Upgrade Sitecore Identity Server – As we had restored the upgraded databases to a vanilla 10.3.1 instance, latest 7.0.x version of Sitecore Identity Server was already installed. Do make sure that the latest 7.0.x images are being referred in the docker files as well.
   4. We also installed the latest cumulative hotfix for SXA mentioned here.

Deployment to higher environments

Our DevOps team had already set up Vanilla instance of 10.3.1 site on higher environments. We shared the 10.3.1 upgraded databases( via bacpac files) and 10.3.1 code base git branch with them so that they can restore the databases and set up CI/CD.

Post testing and validation on UAT, we had a brief code/content freeze on prod and re-executed these steps against latest database backups from prod.

That’s a wrap on this blog series. Hopefully the details mentioned in these blogs would help you with Sitecore upgrade projects.

Previously we did a deep dive in to the prerequisites required for Sitecore database upgrade and steps needed to prepare for it.

In this second part of the 3 part blog series, we will go over the steps that need to be performed to do the actual upgrade of databases.

Upgrade Steps

1. 1. Go to https://dev.sitecore.net/Downloads/Sitecore_Experience_Platform/103/Sitecore_Experience_Platform_103_Update1.aspx and review the steps in the “Prepare for the upgrade” section of the “Upgrade Container Deployment Guide” guide.
   2. Navigate to the directory C:\sitecoreupgrade\SitecoreContainerDeployment.10.3.1.009452.1448\compose\ltsc2019\upgrade\xp1
   3. Spot the upgrade.env file and open it for editing.
   4. Set the values of these environment variables in that file. Make tweaks as needed as per your solution set up.

      SQL_DATABASE_PREFIX=Sitecore
      SQL_SERVER=IPADDRESSORDOMAINNAMEOFYOURSQLCONTAINER
      SQL_USERNAME=sitecoreupgrade
      SQL_PASSWORD=sitecoreupgrade
      IS_ALWAYS_ENCRYPTED=False
      PROCESSING_ENGINE_TASKS_DATABASE_USERNAME=dbo
      DATABASE_UPGRADE_FROM_VERSION=9.3.0
      DATABASE_UPGRADE_TO_VERSION=10.3.1

   5. To convert and compress the Sitecore license to base 64 string, run the script present in “ConvertTo-CompressedBase64String” method present in the upgrade guide. Copy the output of the script and use it to set the value of “SITECORE_LICENSE” variable in the upgrade.env file.
   6. As we are upgrading from Sitecore 9.3.0, login to your local Sitecore instance, select control panel and in “Database” Section, select “Clean up databases”.
   7. Open powershell in Admin mode and change the directory to “C:\sitecoreupgrade\SitecoreContainerDeployment.10.3.1.009452.1448\compose\ltsc2019\upgrade\xp1”
   8. Run this docker command to create the SQL Upgrade Container. “docker-compose -f .\docker-compose.upgrade.yml –env-file .\upgrade.env up”
   9. As the SQL upgrade container starts executing the scripts inside it, you might get this error regarding SQL upgrade container not able to connect with SQL container. This is also mentioned in “Troubleshooting” section of upgrade guide.
      

      Error while connecting to SQL server

   10.  After some troubleshooting, we discovered that SQL container and SQL upgrade container were not on the same network.
       • To review the network for the SQL container, I ran the command “docker inspect ” in PowerShell and navigated down the to the Networks section where the network for sql container was “nat”.
         

         SQL container network details

       • So to force the SQL upgrade container to use the same network as SQL container, I added the following(highlighted) lines of code to “docker-compose.upgrade.yml” file present inside the C:\sitecoreupgrade\SitecoreContainerDeployment.10.3.1.009452.1448\compose\ltsc2019\upgrade\xp1 folder. Line 24-26 defines the network and line 21-22 tells the container to use that specific network.
         

         Network details added to docker-compose.upgrade.yml file

   11. After making these changes to docker-compose.upgrade.yml file, I re-ran this command “docker-compose -f .\docker-compose.upgrade.yml –env-file .\upgrade.env up” in powershell and this time it ran successfully. To verify that the upgrade script ran successfully, look for log entry similar to “INFO: Database upgrade from 9.3.0 to 10.3.1 version is completed.” Here are some screenshots for reference.
       

       Sitecore database upgrade in progress

       

       Sitecore database upgrade completed

        

By now, we had successfully upgraded the 9.3.0 databases to 10.3.1. To validate the database upgrade, we executed the following steps.

1. Start vanilla instance of 10.3.1 via docker compose.
2. Verify login to Sitecore.
3. Rebuild VS solution (By the time I got to this step, my teammates had already upgraded the VS solution to 10.3.1).
4. Take backup of Vanilla 10.3.1 databases on local.
5. Enable contained authentication.
6. Stop 10.3.1 SQL container.
7. Copy the mdf and ldf files for all upgraded databases from localhost volume of 9.3.0 SQL container to a temp folder.
8. Inside the temp folder rename the files with same name as the Vanilla 10.3.1 files and copy them to the localhost volume of 10.3.1 SQL container.
9. Restart the 10.3.1 SQL container.

At this point, our local website had been upgraded to 10.3.1 databases and code base.

The next step of upgrade was to split core db so that membership info is in a separate database and here are the steps we performed for it.

1. Take backup of core db.
2. Download the zip from https://dev.sitecore.net/Downloads/Scripts_for_Sitecore_Security_database.aspx and extract its contents to C:\sitecoreupgrade\move membership tables.
3. Review the readme and KCD Documentation file.
4. Update the parameters in the files as needed. I changed the default value for $server to the IP address of the SQL container.
5. Execute the scripts as mentioned in the documentation.
6. Make sure update the compose file for solution so that ${SQL_DATABASE_PREFIX}.Core is changed to ${SQL_DATABASE_PREFIX}.Security for the ‘Sitecore_ConnectionStrings_Security’ and ‘Sitecore_Sitecore__IdentityServer__SitecoreMemberShipOptions__ConnectionString’ connection string.
7. Validate login to Sitecore works.

This concludes the steps to be performed to upgrade Sitecore databases. In the last part of this blog series, we will take a look at steps that need to be executed after we have upgraded our Sitecore databases to 10.3.1.

Many people are starting to moving away from Docker Desktop.  It is important to remember that Docker Desktop is not Docker!  Docker is a standalone tool that allows you to run containers.  Docker Desktop is a separate tool that gives you some information about your images and containers in a nice GUI.  In this article, I’ll give you a few tips for using Docker without Docker Desktop and show you how to use other tools to get the same information you can get from Docker Desktop.

Installing Docker on Windows without Docker Desktop

If you haven’t done the manual install of Docker yet, check out Vikrant Punwatkar’s blog post. For the rest of this article, I’ll use the docker install path c:\docker as suggested.

After Uninstalling Docker Desktop

Restart your machine! This will help clear up potential issues when installing Docker manually.

Configuring Docker Daemon

You can use a json file to change the behavior of the docker engine

• Create a new folder c:\docker\config\
• Create a new file c:\docker\config\windows-daemon.json
  • Set the data-root
  • This is where docker will store the images and container data
  • Make sure the final part of the path does NOT exist. Docker will create it the last folder in the path.
    • {“data-root”: “c:\\docker\\Data”}

Docker Plugins

I wanted to keep everything nicely contained in the c:\docker folder.  But I discovered the compose plugin must be placed in C:\Program Files\docker\cli-plugins.

• It won’t work if you try to put it in c:\docker\cli-plugins
• There isn’t a config option to change the path to client plugins

You can verify the compose plugin is installed at the correct location by running “docker info”.

Compose is listed as a plugin with the correct path

Register the Docker Service

You can add optional flags to the dockerd command to register the service. This command mimics how docker desktop registers the docker service.

dockerd --register-service --service-name docker --group docker-users --config-file C:\docker\config\windows-daemon.json

Upgrading Docker Engine

You will want to periodically check the docker download page for new version of docker.  Follow these steps to upgrade to the new version.

• PS>Stop-Service docker
• Download the updated zip file
• Copy the updated exe files to c:\docker
• PS>Start-Service docker
• Verify the new version is installed by running “docker info”

Docker Desktop Alternative Tools

Like Vikrant mentioned in his post, you can use Visual Studio and VSCode to manage your containers.  If you want a GUI experience that is close to Docker Desktop, check out one of these tools below.  Keep in mind that these tools do not include the docker exe file.  You still have to install docker manually.

• Rancher Desktop by SUSE
  • The containers feature is still listed as experimental.
  • It lists all the containers with the ability to stop, start and delete
  • It lists all the images with the ability to delete
  • It does not have the ability to view container details

The containers tab of the Rancher Desktop ui

• Podman-Desktop
  • This tool more closely resembles the Docker Desktop UI
  • It lists all the containers with the ability to stop, start, delete
    • For each container you can inspect, view logs, and access a terminal (which is a little buggy)
  • It lists all the images with the ability to delete

The containers tab of the Podman Desktop ui

Using Docker Without a GUI Tool

You can of course use docker without any GUI tools through the command line.  Here are some common things you can do with a docker gui and the equivalent command with the cli.

• List containers
  • docker ps
    • Lists running containers
  • docker ps -a
    • Lists all containers
• View logs
  • docker logs -n 100 <container name>
    • Shows the last 100 lines from the log for <container name>
  • docker logs -f -n 100 <container name>
    • Shows the last 100 lines from the log for <container name> and updates the display as new logs are received.
• List container usage stats (memory/cpu)
  • docker stats
• Show container details (environment variables/ports)
  • docker inspect <container name>
• Interact with container
  • docker exec -it <container name> <command>
    • Command is usually powershell.exe or cmd.exe
    • Creates a terminal into the running container
• Stop a container
  • docker stop <container name>
• List images
  • docker image ls

Conclusion

If you are no longer using Docker Desktop, there are still plenty of ways to use Docker.  I hope this article helps you find the way that works best for you!

Configuring applications outside of Docker desktop environments needs to be done carefully. For seamless integration, we must know how to add the required configurations. In this article, we will explore the essential steps to successfully add configuration for a non-Docker desktop environment, ensuring efficiency and reliability in our development workflow.

As Vikrant Punwatkar explained in his “Sitecore Containers without Docker Desktop” article, running containers without Docker Desktop is possible. However, after successfully implementing this approach, it was observed that we could not debug the project source code.

Investigation

The default location of the configuration file on Windows is shown below. This “config” option allows us to set any configuration option for the daemon in a JSON format.

~\programdata\docker\config\daemon.json

We can see that the “config” folder is missing from the above-mentioned path. As a result, our solution was acting strangely, and we could not debug the container-based source code.

Solution

The issue can be resolved once we add the required “config” folder and the required “daemon.json” file with the necessary configurations. It can be accomplished by downloading and executing the “Create Config File Script” which will automatically generate the necessary “config” folder and “daemon.json” file in addition to the necessary configurations.

Note: Any “PowerShell” script that we download and attempt to execute on a “PowerShell” terminal will result in the error below.

The file "specific PowerShell script file name" is not digitally signed. You cannot run this script on the current system.

This problem can be fixed by executing the following command on a “PowerShell” terminal.

 Set-ExecutionPolicy Bypass -Scope Process 

Steps to Add Configurations Manually:

1. 1. Check the “~\programdata\docker” path and see if the “config” folder is present or not.
   2. Create a folder and name it as “config”, if it is not present.
   3. Create a “daemon.json” file inside the “config” folder.
   4. Add the following data in the “daemon.json” file.

{
    "debug":  true,
    "dns":  [
                "8.8.8.8"
            ],
    "experimental":  false
}

Note:

• These are the basic configurations, and they can be modified, or additional configurations can be added depending on the project and its requirements.
• “DNS” configurations can differ based on the project and its architecture.

Conclusion

The configuration file while using “Docker Desktop” is generated automatically once we add or modify the required configurations from the “Docker Desktop Settings” menu. But in this scenario, we have to create it manually, as the “daemon.json” file is crucial for customizing and configuring the Docker daemon to meet specific requirements, including security, network, and resource settings.

Happy learning!

1.  Upgrade database
2.  Upgrade VS solution
3.  Upgrade docker files.

Prerequisites for upgrading

1. You should know your local host Windows ltsc version and your Sitecore topology. For me ltsc version was 2019 and Sitecore topology was xp0.
2. Go to https://dev.sitecore.net/Downloads/Sitecore_Experience_Platform/103/Sitecore_Experience_Platform_103_Update1.aspx  and review the “Upgrade Container Deployment Guide”.
3. Download and extract the Sitecore Container Deployment package via the “Container Deployment Package” link present on https://dev.sitecore.net/Downloads/Sitecore_Experience_Platform/103/Sitecore_Experience_Platform_103_Update1.aspx  to a folder on your local, say C:/sitecoreupgrade.
4. Based on your ltsc version and topology, navigate to the corresponding folder and review its content.
   • In my case it was C:\sitecoreupgrade\SitecoreContainerDeployment.10.3.1.009452.1448\compose\ltsc2019\upgrade\xp1
     • As there was no folder for xp0, we decided to use the xp1 topology folder
     • We went with compose folder as we were using docker and not Kubernetes
   • Inside the xp1 folder review contents of docker-compose.upgrade.yml to identify what all databases (see lines 7-16 in screenshot below) backups you need from production(prod).

   services:
     mssql-upgrade:
       image: ${SITECORE_DOCKER_REGISTRY}sitecore-xp1-mssql-upgrade:${SITECORE_VERSION}
       environment:
         IS_ALWAYS_ENCRYPTED: ${IS_ALWAYS_ENCRYPTED}
         PROCESSING_ENGINE_TASKS_DATABASE_USERNAME: ${PROCESSING_ENGINE_TASKS_DATABASE_USERNAME}
         Sitecore_ConnectionStrings_Core: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Core;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
         Sitecore_ConnectionStrings_Master: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Master;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
         Sitecore_ConnectionStrings_Web: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Web;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
         Sitecore_ConnectionStrings_Experienceforms: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Experienceforms;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
         Sitecore_ConnectionStrings_Processing_Engine_Tasks: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Processing.Engine.Tasks;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
         Sitecore_ConnectionStrings_Messaging: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Messaging;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
         Sitecore_ConnectionStrings_Reporting: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Reporting;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
         Sitecore_ConnectionStrings_Xdb_Collection_Shard0: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Xdb.Collection.Shard0;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
         Sitecore_ConnectionStrings_Xdb_Collection_Shard1: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Xdb.Collection.Shard1;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
         Sitecore_ConnectionStrings_Marketingautomation: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Marketingautomation;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
         Database_Upgrade_From_Version: ${DATABASE_UPGRADE_FROM_VERSION}
         Database_Upgrade_To_Version: ${DATABASE_UPGRADE_TO_VERSION}
         Sitecore_License: ${SITECORE_LICENSE}
       isolation: ${ISOLATION}

    

5. Before taking the prod db backup you can create/verify a login on prod Sitecore that you can use to login to Sitecore on local host to clean up databases and perform post upgrade steps.

Upgrade Preparation Steps

1. Take backups of existing 9.3.0 prod databases on Azure.
   • These generally have bacpac extensions
   • We had saved the bacpac files in a Blob Container
2. Download and install “Microsoft Azure Storage Explorer”.
3. Open Azure storage explorer and connect to Blob Container via these steps
   • • • Navigate to “Storage Accounts” node in Azure Explorer and right click
       • Select “Connect to Azure Storage”
       • Select “Blob container or directory” as the Azure resource
       • Select your preferred connection method. As our DevOps team had shared the SAS URL of the Blob Container with me, I used that as the connection method. After connecting to Blob Container, download the bacpac files
     

     Select SAS as the connection method

4. On your local start all the containers in your 9.3.0 solution.
5. Connect to SQL server instance present inside the SQL container using SSMS on your local host. SQL Server name generally has this syntax – “127.0.0.1,port number”. E.g. 127.0.0.1,1433
6. Take backups of existing 9.3.0 databases from local via SSMS.
7. Enable contained database authentication by running this following command in SSMS.

   sp_configure 'contained database authentication', 1;  
   GO  
   RECONFIGURE;  
   GO

8. Import all the bacpac files from prod on local host via “Import Data-tier Application” functionality in SSMS. You may append the text “.Prod” to new database name so that you can differentiate between prod and local version of databases. E.g. “Sitecore.Master.Prod”. See screenshots below for reference.
   

   Import bacpac file in SSMS

   

   Append the text “.Prod” to new database name

   Note:- We observed that our SQL container volume was complaining about disk space at this location “C:\Program Files\Microsoft SQL Server\MSSQL14.MSSQLSERVER\MSSQL\DATA”. So we ended up changing that to “C:\Data” for both Data file path and Log file path. The reason being the path “C:\Program Files\Microsoft SQL Server\MSSQL14.MSSQLSERVER\MSSQL\DATA” was inside the container and had limited space. Hence changing it to “C:\Data” (which maps back to my local host via volume mount as mentioned in steps below) made it use my local host disk space.

9. Stop the SQL container via this command “docker stop <sqlcontainername>” E.g. docker stop my_container
10. Review the “sql” service section of your solution’s docker-compose file and observe the local host path set under volume. In my case it was data\sql folder(see line #7 in screenshot below) inside the docker folder of the solution.

    sql:
        image: ${REGISTRY}sitecore-xp-sxa-sqldev:${SITECORE_VERSION}-windowsservercore-${WINDOWSSERVERCORE_VERSION}
        isolation: ${ISOLATION}
        restart: ${RESTART_POLICY:-unless-stopped}
        hostname: ${SQL_HOST}
        volumes:
          - .\data\sql:C:\Data
        networks:
          default:
            aliases:
              - ${SQL_HOST}
        mem_limit: 2GB
        ports:
          - "1433:1433"
        environment:
          SA_PASSWORD: ${SQL_SA_PASSWORD}
          ACCEPT_EULA: "Y"
          SQL_HOSTNAME: ${SQL_HOST}
        # Allows for access to the database through traefik to support using database locally.
        # This should not be used in production.
        #
        # Since this is not http, but tcp traffic it does does not understand the concept of a "host".
        # so we must dedicate a port to it in traefik, and direct all traffic to this router: HostSNI(`*`).
        labels:
          - "traefik.enable=true"
          - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-sql.entrypoints=sql"
          - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-sql.rule=HostSNI(`*`)"
          - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-sql.service=${COMPOSE_PROJECT_NAME}-sql"
          ## Service for SQL requests
          - "traefik.tcp.services.${COMPOSE_PROJECT_NAME}-sql.loadbalancer.server.port=1433"

     

11. Go to the folder docker\sql\data in your solution and
    • Observe the names of the local 9.3.0 data and log files. Eg Sitecore.Master, Sitecore.Core etc.
    • Move all the mdf and ldf files related to the prod databases you imported in the steps above to a different folder say C:\sitecoreupgrade\proddbs
    • Rename the files in “C:\sitecoreupgrade\proddbs” folder to match the file names of local 9.3.0 files. E.g Rename “Sitecore.Master.Prod” to “Sitecore.Master”
    • Copy the files from “C:\sitecoreupgrade\proddbs” to “docker\sql\data” folder of your solution and replace the existing files
12. Restart the sql container via this command ” docker start <sqlcontainername>”. Note:- the Sitecore instance might take a few minutes to come up when you restart SQL container. Till then it might show SQL timeout error.
13. Build your VS solution.
14. Delete the databases having “.Prod” in their names to free up disk space.(Optional)
15. At this point, your local site is using 9.3.0 code base from local and production version of 9.3.0 databases. If you have a production Sitecore login, then you can try to login to your local Sitecore instance using that to verify that you are seeing the production content.
16. Connect again to SQL container via SSMS and create a new login say “sitecoreupgrade” and give it “db owner” membership role for all the Sitecore databases.

Troubleshooting image update issues in Sitecore can prove to be a complex task, as various factors could contribute to the problem. We recently encountered an issue where, after updating the “Sitecore Images,” our local project instance stopped working.

In order to resolve the issue, we attempted multiple possible solutions, including those available on the internet, but initially were not able to identify the root cause of the problem. To find the root cause of the problem, we chose to follow the following process:

Step 1: Setup Sitecore 10.2 – Non-Docker Instance

We downloaded and installed the “Sitecore 10.2” non-docker instance and integrated it with our project’s codebase. This step verified the proper functioning of our “Sitecore 10.2” non-docker instance along with our codebase, leaving no doubt that the issue did not occur because of the codebase.

Due to this reason, we also compared the bin folder of the “Sitecore 10.2” non-docker project instance along with the bin folder of the “Sitecore 10.2” docker project instance and discovered that the DLLs were mismatched.

To resolve this issue, we even tried to update the DLLs, but after updating one DLL, it presented another issue and continued to repeat.

Step 2: Troubleshooting the “Sitecore-xp0-cm” Image

Fortunately, one of my colleagues had a working “Sitecore 10.2” project instance with Docker on their machine. That is why we decided to debug the sitecore images to identify the root cause of the issue.

docker image inspect --format '{{json .}}' "Add your image id here" '. | {Id: .Id, Digest: .Digest, RepoDigests: .RepoDigests, Labels: .Config.Labels}'

The above PowerShell command generates the output in JSON format. A code snippet from the output file is below.

"Id": "sha256:55825c834be6aa053e9292c77f90cd64557cf5a5be21a8fb412f1b76074076aa",
"RepoTags": [
  "scr.sitecore.com/sxp/sitecore-xp0-cm:10.2-ltsc2019"
],
"RepoDigests": [
  "scr.sitecore.com/sxp/sitecore-xp0-cm@sha256:d2ac9c0b631ff23aae6915836123049ff6d714e01fc8af49eef69cc07cb7abf5"
]

Digest ID of sitecore-xp0-cm image

sha256:d2ac9c0b631ff23aae6915836123049ff6d714e01fc8af49eef69cc07cb7abf5

From the above code snippet, locate the “RepoDigests,” extract the “Digest Id,” copy it, and search for it in the “Sitecore Docker Images Details List“. You will find that the “Sitecore-xp0-cm” image is downloading the “10.2.1-ltsc2019” tag or versioned image.

Our project relies on the “10.2.0-ltsc2019” version, which is why the local project instance wasn’t functioning.

To resolve this issue, we modified our “.env” file, where Docker-related variables are located, and included the necessary “Sitecore Version” on which our codebase is set up.

SITECORE_VERSION=10.2.0-ltsc2019

After modifying the “.env” file, follow the below steps in order to get the local project instance up and running.

1. Remove all the Docker containers
2. Remove all the Docker images
3. Restart the system
4. Download all the images and build the containers
5. After this, we were able to get our local project instance up and running.

Conclusion:

Significant modifications were made to the “.env” file, and the “Sitecore Version” was changed to “10.2.0-ltsc2019”. Our codebase and other higher-level environments, such as the live site, had been set up for the “Sitecore 10.2.0” version, and that’s why we opted for this step. If we switch to the “Sitecore Version” of “10.2.1-ltsc2019,” which is the latest by default, we would have to upgrade our codebase in addition to other environments.

Hope this helps. Happy Sitecore and Docker learning!!!

As the IT industry has increasingly started embracing containerization, it has become a cornerstone of modern software development. Sitecore is not an exception. Sitecore announced official support for containers from the version 10 initial release. Since then all of us have started using Docker Desktop to run Sitecore’s containerized solution.

If you are new to Docker and Containers, You can go through Bootcamp on Docker by my friend Eric Sanner.

Docker Bootcamp Blog Series

But Docker Desktop is paid for commercial use. As I do not use its GUI much except for some nominal work, I thought of looking for its alternatives. Surprisingly, I learned that running Containers without Docker Desktop is possible.

This is roughly the composition of Docker Desktop. Under the hood, it utilizes Docker Engine. Additionally, it provides a decent Graphical interface to interact with Docker Engine.

It is good to have but not a necessity. All you need is a Docker Engine.

It is an open-source containerization technology for building and containerizing your applications.

Let us set up a Docker Engine on your machine to run Windows Containers.

Note : Though this article specifically targets Sitecore Containers, This Docker Engine setup process should be common for all those who wish to run Windows Containers.

There are a few really helpful articles about how to do it. Thank you for giving me a head start !!

• Jeremy Davis – Docker without the desktop (jermdavis.dev)
• Declaring Independence from Docker Desktop with Docker Engine | georgechang.io

Unfortunately, I already had Docker Desktop installed so I landed into a few issues. While fixing those I realized that it is better to pristine my machine. If you don’t, you may face weird issues due to unremoved files of the Docker Desktop.

Now let’s start with the action !!

Disclaimer – This will remove all your containers and images but eventually it will be downloaded when you run your instance.

• Clean up

  • Uninstall ‘Docker Desktop’ from your machine
    • You can try running ‘docker version’ after uninstallation which should throw an error saying ‘docker is not recognized’
  • Even after uninstallation, a few files remain buried in your drive. Let’s remove them if present at the following locations. (If you face problem while deleting files, especially windowsfilter folder inside docker, do check this blog.  If at worst nothing works, you can rename it like adding a ‘-old’ suffix, although it is not advisable.)
    • C:\docker
    • C:\ProgramData\docker
    • C:\Program Files\docker
    • C:\Users\{your-user}\.docker

Once this clean-up is done, we will be ready to set up the Docker Engine.

Below steps are outlined for your understanding. To execute them automatically, here is a link to scripts

• Setup Docker Engine

  • You need to download latest Docker Engine binary from here.
  • Extract it and register Docker Daemon as a Windows Service with this command
    • dockerd –register-service  (Note : there are two consecutive hyphens before register)
  • Add this path in Environment Variables
    • This bridges a gap between OS and Docker Daemon. Now you can run commands anywhere in your machine.
  • Test command – docker version

Your Docker Engine should be setup now. (Since we are focusing on Sitecore, we will setup Engine to support only Windows containers)

• Install Docker Compose Plugin

  • It is a tool for defining and running multi-container Docker applications.
  • Download the latest .exe from this archive
  • Rename it to docker-compose.exe
  • Place it in C:\Program Files\Docker\cli-plugins
  • Test command – docker-compose version

• Set Rights for Current user

  • This can be an optional step if the logged-in user has Admin Rights. Personally, I did this to rule out any future rights-related issues. (To execute this automatically, please refer to above scripts.)

Once this is all done, there is no harm to restart And finally, you should be ready to spin up containers.

But wait, it’s not over yet. I have a surprise for GUI lovers. You still have few alternatives,

• Use the Containers window in Visual Studio
  • It provides you a handy way to monitor Containers in Visual Studio. Check more details here
  • It is available in Visual Studio 2022 or Visual Studio 2019 version 16.4 or later
  • Make sure to run VS as admin, otherwise, you may see this error – Docker Desktop is not running. Please start Docker Desktop and try again.

• Docker in Visual Studio Code
  • A very similar extension for VS Code from Microsoft. Check more details here

And CLI lovers, here is a docker cheat sheet from Sitecore for you.

I am working on compiling the below information. Stay tuned!

• Troubleshooting guide for bugs faced while setting up Docker Engine
• Docker Engine update scripts

That’s all for now!  You are all set to work on your containerized Sitecore solution without Docker Desktop now.

As a Sitecore developer, you might have faced some errors while working with Sitecore, especially during the setup/installation process. In this blog post, we will discuss some of the errors I encountered during the Sitecore getting started template setup through docker on my local machine.

“Docker Desktop – WSL kernel version too low”

This is the very first error I encountered while installing the Sitecore with Docker. But this is purely a Docker-specific error and not related to Sitecore. It arises when Docker for Windows requires your Windows machine’s latest WSL kernel version. Docker has some configurations and features that depend on the WSL kernel and require the latest version. To resolve this error, we just need to run the below command.
'wsl --update'

After running this command, your Windows gets upgraded with the latest version of WSL. You can check the WSL logs to validate the above fix. For fetching the WSL logs, you need to download and run this PowerShell script collect-wsl-logs.ps1  with administrative rights.

“no matching manifest for windows/amd64 in the manifest list entries“

Another error I have received while running the docker-compose command shows the above error message in the console.

This is also not related to Sitecore and is purely Docker-specific. The root cause of this issue is your Docker for Windows running with Linux containers instead of Windows containers. If you see the “Switch to Windows Containers” option after right-clicking on the Docker icon, it means your Docker is running with Linux containers. So to fix this issue, we need to switch the containers to Windows.

After switching to Windows containers, follow the below steps to bypass it by running the Docker daemon.

1. Go to Setting
2. Select the “Docker Engine” Tab
3. Update the below params in the Docker Daemon – {“experimental”: true}
4. After making all the mentioned changes. DO NOT FORGET to Restart the Docker.

“a Windows version 10.0.20348-based image is incompatible with a 10.0.19044 host”

After resolving the above issue, which is specific to Docker, I have encountered one more error, and this time it’s specific to Sitecore. While running the same docker-compose up -d command, it shows the above error message in the console.

I received this error because the docker image and my host machine are incompatible. To resolve this error, first, we need to check if there is any Windows update on the host machine. Once we update the host machine’s Windows, we need to update a few parameters from the .env file.  Please open the .env file, which is available in your src folder, and update the below line according to your Windows and Sitecore versions.

SITECORE_VERSION=10.3-ltsc2019 -- line no 3
EXTERNAL_IMAGE_TAG_SUFFIX=ltsc2019 -- line no 36

Here you can check the compatible versions with your Windows,
Nano Server by Microsoft | Docker Hub

After making these changes in the .env file, I reran the docker-compose command, and this time it ran successfully without any error.

I hope this blog post helps you to solve the above error. Recently I installed the Sitecore 10.x instance with JSS and encountered a few errors, so I am going to share those errors and their fix in my next blogs. So STAY TUNED!

Happy Installation!

I have been working at Perficient for almost 8 years.  I have always enjoyed writing blogs and sharing my knowledge with others.  This is my 100^th blog post!  WOW!  I can’t believe I finally made it!  Come with me while I take a look back at 8 years worth of content.

Series

I write a lot of blog series.  I like to focus on a topic and share everything I can about it.  I have 9 different series with 77 posts.  This is obviously my preferred way of sharing content.

https://blogs.perficient.com/2017/10/30/sitecore-symposium-2017-sessions-review/ (7 posts)

https://blogs.perficient.com/2017/11/02/sitecore-bootcamp-for-developers/ (8 posts)

https://blogs.perficient.com/2018/05/22/choose-a-sitecore-placeholder-name-instead-of-typing/ (4 posts)

https://blogs.perficient.com/2018/10/23/sitecore-symposium-2018-sessions-review/ (11 posts)

https://blogs.perficient.com/2019/05/21/going-multilingual-in-sitecore/ (4 posts)

https://blogs.perficient.com/2019/11/05/sitecore-symposium-2019-sessions-review/ (15 posts)

https://blogs.perficient.com/2021/02/23/docker-bootcamp-blog-series/ (17 posts)

https://blogs.perficient.com/2023/03/27/case-study-lift-and-shift-from-drupal-to-sitecore-sxa/ (3 posts)

https://blogs.perficient.com/2023/04/24/getting-to-know-sitecore-search/ (8 posts)

Accessibility

I have a passion for accessibility.  When I was in college, I worked in a computer lab that housed the adaptive technologies lab.  They had screen magnifiers, braille readers, screen readers, alternate methods of input.  It was fascinating to learn about these tools and the other ways people interact with computers.  After college, I worked for a small web design company.  Our focus was usability and accessibility.  I have shared my passion with other people at Perficient and ignited a passion for accessibility within them as well.  I have a whole series of posts that I would like to write someday about the WCAG guidelines and how to detect and remedy each requirement.  Until then, I’ve shared my screen reader blog and video with many people to show them how to use a screen reader as a native user would.

https://blogs.perficient.com/2022/07/18/digital-accessibility-using-a-screen-reader/

https://www.youtube.com/watch?v=-AvHYuhZd58

https://blogs.perficient.com/2023/08/22/making-sitecore-sites-more-accessible-and-screen-reader-friendly/

Content Migration

Almost every project needs some sort of content migration.  It is never a fun task!  I lead a project where we migrated from Drupal to Sitecore SXA.  I was very excited to come up with a way to do it super fast.  I found a tool called Merlin too late in the project to use, but I wrote a content import powershell suite that I’m still refining and hope to release/promote soon.

https://blogs.perficient.com/2023/03/27/case-study-lift-and-shift-from-drupal-to-sitecore-sxa/

https://blogs.perficient.com/2023/01/19/my-journey-with-sitecore-data-exchange-framework-def/

https://blogs.perficient.com/2023/06/13/using-merlin-to-migrate-your-site-to-sitecore/

https://blogs.perficient.com/2023/06/26/import-data-from-merlin-to-finish-your-migration-to-sitecore/

Docker

More of my projects are using Docker.  When I started, I kept running into problems.  I wanted to gain a deep understanding of the tool to know how to solve these problems.  I did not want to follow article after article of troubleshooting tips that may or may not solve the problem.  I really enjoyed writing this series.  I have become a “go-to-guy” when others have problems with Docker.  I jokingly started calling myself “Docker Doctor” ⁠(⁠).  Not all of these articles are Sitecore related, but the more you know about the tool, the easier it is to debug issues while using Docker to run a Sitecore project.

https://blogs.perficient.com/2021/02/23/docker-bootcamp-blog-series/

https://blogs.perficient.com/2023/02/06/using-docker-docker-index-exe-high-cpu-and-disk-usage/

https://blogs.perficient.com/2023/02/08/using-docker-multiple-virtual-machines/

https://blogs.perficient.com/2023/04/14/sitecore-ltcs2022-docker-vms-and-windows-11/

Sitecore

Most of my work at Perficient has been focused on the Sitecore platform.  When I joined Perficient in 2015, I was brand new to Sitecore.  I wrote my Sitecore Bootcamp for Developer series for myself as well as for others that had been in my position of having to learn Sitecore from scratch.  Before SXA, I wrote a Sitecore Module that would make the input box where you type the name of a placeholder into a dropdown.  That made it easier to get the placeholder name correct.  I have had a couple of opportunities to work on multilingual sites.  That presented a whole new set of challenges; languages, shared and versioned content, fallback languages, and more.  I was happy to update that series to include SXA this year.  As Sitecore moves to a composable platform, it is important to learn the new pieces.  I’ve spent several months learning Sitecore Search.  I look forward to learning personalize next and seeing how multiple composable tools work together.

https://blogs.perficient.com/2017/11/02/sitecore-bootcamp-for-developers/

https://blogs.perficient.com/2018/05/22/choose-a-sitecore-placeholder-name-instead-of-typing/

https://blogs.perficient.com/2019/05/21/going-multilingual-in-sitecore/

https://blogs.perficient.com/2023/03/27/case-study-lift-and-shift-from-drupal-to-sitecore-sxa/

https://blogs.perficient.com/2023/04/24/getting-to-know-sitecore-search/

https://blogs.perficient.com/2023/08/04/keeping-sitecore-content-authors-happy-and-productive/

https://blogs.perficient.com/2023/01/19/my-journey-with-sitecore-data-exchange-framework-def/

https://blogs.perficient.com/2023/06/13/using-merlin-to-migrate-your-site-to-sitecore/

https://blogs.perficient.com/2023/06/26/import-data-from-merlin-to-finish-your-migration-to-sitecore/

Sitecore Symposium

I was fortunate to attend Sitecore Symposium three times in my tenure at Perficient so far.  I always enjoy meeting people face to fact that I’ve been on calls with for projects.  These events are a great learning opportunity.  I’m a big note taker, I was excited to share my notes for each session I attended for the last two symposiums for those that weren’t able to attend.  I’m not able to make it to SUGCON NA this year, but I’m hopeful to connect with people in person at the next big Sitecore event!

https://blogs.perficient.com/2017/10/30/sitecore-symposium-2017-sessions-review/

https://blogs.perficient.com/2018/10/23/sitecore-symposium-2018-sessions-review/

https://blogs.perficient.com/2019/11/05/sitecore-symposium-2019-sessions-review/

To the next 100!

Thanks for taking a walk down memory lane with me!  I’d love to hear if any of these posts have helped you in past.  If you want to get notifications when I post new content, follow me on linkedin.