Troubleshoot issues with Sitecore Docker containers

Using Docker containers with Sitecore can be challenging, especially when just starting. A lot has to do with the way we have been used to working in the IIS world, still getting used to the container intricacies and feeling lost or overwhelmed by the new ways of working. In this blog, I will try to help overcome these issues.

The Basics: Prevention is Better than Cure

To run a Sitecore environment in Docker containers, there are some fundamental steps/actions that should always be adhered to. These are generic for all the projects and imperative for a Sitecore environment to load.

1. Having Docker installed and running: Whether Sitecore or not, to run Docker containers, you need to have Docker installed and running.

2. Ensuring Windows containers are enabled: Sitecore containers use Windows containers so it is imperative that when you right-click on the Docker icon in the Windows tray, you see Switch to Linux containers thus confirming that the Windows containers mode is active.

   

3. DNS entry is included in the Docker engine: For our Docker environment to have access to the Internet, it is important to have the DNS entry (usually [8.8.8.8]) in the Docker engine. An example of Internet usage in the Docker context is downloading Node.js in the frontend build of a Dockerfile. In some cases, this needs to be updated in the Deamon.json (path: C:\Users\[your username]\.docker\daemon.json) also otherwise it won't work.

   

4. IIS and Solr services are stopped: Traefik, the reverse proxy manager, does not run if the IIS is still running. So we need to ensure that it is stopped. Stopping Solr service is not a hard requirement. There is a way around it by using a different Solr port in Docker as compared to the one used in the locally configured Solr setup, if any.

5. No VPN running: Although there is a way to make the Docker containers work with VPN running, in most cases is better to ensure that VPN is disabled when running containers.

The Advanced: What to do when there is a problem?

Now that we have confirmed the above basics have been taken care of, what to do when there is an actual problem with a Docker container not starting up? How to resolve it?

1. Check the logs: As with most applications, the first thing to look at when debugging a problem is the log files. Based on the error received on starting the container, it might be useful to check the log files of the particular container.

   1. The log file path for the cm container on the local drive is configured using the volumes Docker keyword in the docker-compose override file. For us, generally, the log file path is solution folder\docker\data\cm

   2. Using Docker Desktop tools: Log files could be accessed directly in the Docker desktop itself. Along with the log files, there is an option to inspect the settings of the container and start a CLI if need be.

      

   3. Using Docker extension for Visual Studio Code: Docker extension for Visual Studio Code could also be leveraged to check the logs, attach the shell to a terminal, and restart the container if needed

      

2. Run Docker exec: The traefik container, which acts as a reverse proxy, intercepts all the requests coming to the cm containers. This has its advantages but the downside is that we do not see the actual errors occurring when there are any. The way around this is by using the docker exec command, which has the syntax:

   docker exec -it containerId powershell.exe The entire command stands for we want to execute the container containerId in an interactive mode via a powershell terminal. Once inside the container, we execute Invoke-WebRequest http://localhost -UseBasicParsing to execute a request from inside the container to see the actual error message.

3. Run clean Sitecore instance: Another way to troubleshoot issues with our Sitecore instance is by removing our custom code/solution and running a clean Sitecore instance. Once we confirm that the Sitecore instance is running without our code, we can add our custom code to find out which config or code is the culprit.

4. Removing the images: There are times when we will have to rebuild the images instead of just up. An example would be when a change is made in a Dockerfile file for one of the services. We can use the option --no-cache option in conjunction with the up command to ensure that Docker doesn't use local cache to build the image but a safer option would be to remove all the solution-specific images. Just removing the solution images means that only the images for the solution part are recreated while the stock Sitecore and Microsoft images remain intact. This approach is not only faster but also more efficient compared to removing all the images. However, if necessary, we could also opt for a more drastic measure and remove all the images using the system prune command.

5. Docker/system restart: In the realm of IT troubleshooting, when all else fails, we adhere to a well-known adage: "Have you tried turning it off and on again?" This holds true here as well. Either a Docker restart or a complete system restart frees up memory, and clears up network glitches to name a few.

Running Sitecore in Docker containers offers many benefits in terms of portability, scalability, and development speed. However, like any technology, it can present challenges. With the troubleshooting tips and solutions provided in this blog post, you'll be better equipped to address common issues and keep your Sitecore Docker environment running smoothly. Remember to consult the official Sitecore documentation and community forums for additional guidance on specific issues and configurations. Happy Sitecore containerization!