Tips for Local Development with Sitecore Containers

Navigating the intricacies of Sitecore development in the Container world can be both rewarding and challenging. To ensure a smooth and efficient development process, I've curated a list of tips that will help make this journey easier and more productive. Keep reading to find out how.

1. Don't run containers you don't need: Heard of the term Keep It Simple, Stupid (KISS)? It is a design principle stating wherever possible, a system should be kept as simple as possible, avoiding unnecessary complications. This principle holds true when running Sitecore in local containers too. A fully scaled-out XP1 Topology runs 19 containers with separate containers for each of the XConnect roles. This is not required at all, opting for XP0 Topology instead is much better. If there's no xDB (Sitecore Experience Databases) or Sitecore Analytics, consider running XM1 Topology. The optimization doesn't end here. I use a further trimmed-down XM0 Topology where even CD and Redis containers are excluded. The idea is really simple, the fewer containers we load/run, the fewer resources get utilized, making our environment simple, efficient, performant, and stable.

2. 

   Using Powershell scripts for bringing containers up/down: Instead of manually running docker compose commands, it might be more useful to create wrapper Powershell scripts around it. This has several advantages. Powershell scripts allow us to automate menial tasks such as stopping IIS, stopping Solr service, clean up old log files. It also helps streamline the development process so that everyone is using the same script to up and down the Docker containers. We could also parameterize the script if needed, for example, we could include a -Topology parameter to decide at runtime whether we want to start up an XM instance or an XP one.

3. Using a separate optimized solution Dockerfile for local development: The Dockerfile we use in the local environment is almost empty, it only contains some mkdir steps, as can be seen below, while for the higher environments, we use a separate one that actually has the frontend and backend build steps to create the solution image. The idea is to make the solution image locally as lean as possible because we want the code to essentially run from the path .\docker\deploy\website\ which is the Visual Studio build/publish path. Since Visual Studio already performs a build locally, we do not want to do that again in the solution image making our development loop shorter and faster.

   

4. Creating a Docker compose override file: The docker-compose.overriding.yml file is a separate configuration file that allows us to extend the settings defined in the main docker-compose.yml Each Sitecore Topology compose file should have its own override file. For example, docker-compose.xm1.yml should have it's own docker-compose.xm1.override.yml where only additional settings pertaining to the XM1 Topology should be defined. Override files enable you to change properties like ports, volumes, environment variables, and more without altering the main configuration. For example,

   • You could use an override file to set up an upper limit on the memory that the SQL container could use using mem_limit,

   • Define a different local port that will get mapped to the Solr container,

   • Setting environment-specific variables like Sitecore_AppSettings_role for the CM container.

5. Using an .env-default file: In a Docker Compose context, the .env file is used to store environment variables that can be used within your Compose file and referenced in the services defined there. Environment variables are often used to customize and configure containers in your Docker Compose setup without hardcoding values directly in the Compose files. It should be personal for each developer and should be excluded from the code repository. This file should be added in the .gitignore and an additional file .env-default should be created and committed to the code repository. If there are new changes (for example, a new certificate, or a hostname) added to the .env file then that change should be included in the .env-default file, committed to the code repository and the developers should be made aware that they need to update their respective .env to include the changes.

6. Using a pinned Sitecore image version: Docker Version Pinning is a concept where we use a specific Sitecore image version instead of the general one. For example, let's say we want to start up Sitecore 10.2 in local Docker. There are multiple images for this in the Sitecore Container Registry. Now, if we use 10.2.0-ltsc2019 tagged image, the probability of it getting modified is way more than let's say 10.2.0.006766.1804-10.0.17763.4377-ltsc2019 making our environment unstable. Version pinning ensures that your Sitecore containers are always based on a specific version of the image. This consistency makes it easier to reproduce the exact same environment for the entire team and across different stages of development, testing, and production. As newer versions are released. it's wise to closely monitor release notes, conduct thorough testing, and have a rollback plan in place before deciding on the next pinned version.

   

7. Not updating Docker Desktop: As with Version Pinning, consistency and stability are two aspects of development everyone desires. Docker Desktop is wonderful but with Windows, it is not always consistent or stable, especially when running Sitecore containers. But luckily we've found our pinned Docker version (4.12.0 for now). This works well for the team, reducing unwanted risks, inconsistencies and letting us focus on our work. It relieves us from resolving "why Sitecore is not running on my system" issues. Similar to version pinning, there should be a strategy to go to the next "stable" version after thorough testing, checking breaking changes, and critical security fixes released with the option to revert to the current one if it doesn't work out well.

   

8. Using the Docker extensions for Visual Studio Code: The Docker extension for Visual Studio Code (VS Code) is a powerful tool that enhances the Docker container development experience by integrating Docker-related tasks directly into the VS Code editor. It provides a great overview of the running containers, checking the files deployed to the container, and also an option to attach the container shell directly so much so that I don't use the Docker Desktop at all.

   

9. Using the Docker exec command to troubleshoot: If the container is not starting up, the first thing to do is to verify if the files deployed are correct. If that is okay, then we proceed with opening a terminal in Windows PowerShell (in admin mode) and run the command docker exec -it "containerid" Then once inside the container, we can run the command Invoke-WebRequest http://localhost -UseBasicParsing This has helped me in finding out the exact cause of why the container (mostly cm container) is not starting up properly. There is a great article written on this topic by Jeremy Davis.

As with developing any application on any system, the major goals are always to have a smooth, fast, stable, consistent, and robust developer experience so that the entire focus can be on building the next greatest feature and not on fixing the local environment.