Introducing Docker to your Team

Over the course of several months I have had the opportunity to introduce the use of docker within development teams as an alternative approach for developing with Sitecore. Developing with Sitecore on Docker requires a bit of a mind shift from your normal way of working with Sitecore. But if offers many benefits like the ability to stand up a fully scaled instance of Sitecore in seconds rather than hours. This blog provides a introduction to docker and getting started developing with Sitecore on Docker.

What is Docker

Docker is a platform that enables you to develop, ship, and run applications as containers. The Docker Daemon process (or engine) runs on your host OS which manages images and containers.

The Command Line Interface (CLI) communicates with the docker daemon via rest API.

Containers vs VMs

Containers are an abstraction at the app layer that packages code and dependencies together. Multiple containers can run on the same machine and share the OS kernel with other containers, each running as isolated processes.

take up less space.
more portable and efficient.
require fewer VMs and Operating systems.
reduce cost as fewer licenses are required.
start in seconds.
are ephemeral – treated like cattle in your DevOps service model.

VMs are an abstraction of physical hardware turning one server into many servers. The hypervisor allows multiple VMs to run on a single machine.

includes a full copy of an operating system, the application, necessary binaries and libraries – are much larger in size.
VMs can also be slow to boot.
start in minutes
tend to hang around longer – treated more like pets in your DevOps service model.

By combining Containers and VMs in your infrastructure provide a great deal of flexibility in deploying and managing your application.

Sitecore Docker Repo

The Sitecore Docker Repo contains docker files for a plethora of Sitecore versions and their variants including: JSS, SXA, SPE. Also necessary scripts, tools and supporting documentation to help you build Sitecore Docker images and ultimately run a containerized instance of Sitecore.

dockerfiletocontainer Lets backup for those of you that may not be familiar with some of these terms:

Dockerfile – is a text document that contains all the commands you would normally execute manually in order to build a Docker image.
Docker can build images automatically by reading the instructions from a Dockerfile.
Docker Images – are the basis of containers. An Image is an ordered collection of root filesystem changes and the corresponding execution parameters for use within a container runtime. An image typically contains a union of layered filesystems stacked on top of each other. An image does not have state and it never changes.
Docker Container– is a runtime instance of a docker image.

Thanks to the hardwork and dedication to the individuals in our community that contribute to the Sitecore Docker repo. Which is continually evolving.

Install & setup Docker for Windows

Docker is a way for you to represent, configure, manage, and run all the infrastructure required to spin up a dockerized instance of Sitecore XM or XP.

Windows 10 Pro build 1903 or greater.
Enable Hyper V services in Windows. You need Virtualization enabled in your BIOS
chocolatey
A valid Sitecore license
Visual Studio 2019
Azure CLI (Windows Installer or choco install azure-cli)

Download and install docker desktop for windows (https://docs.docker.com/docker-for-windows/install/ )

Alternatively Open Powershell:
PS> Set-ExecutionPolicy -ExecutionPolicy UnRestricted
PS> choco install docker-desktop -y

Switch to Docker for Windows – We need to tell Docker to switch mode from it’s default of Linux containers. Find Docker Desktop in your taskbar and make it switch to Windows containers. Docker will restart.

Items

Steps to Build Sitecore Docker Images

The following steps are all you need to build latest Sitecore version and its variants for Window LTSC

Clone the repo
Run the following command:
.\Build.ps1 -SitecoreUsername “YOUR dev.sitecore.net USERNAME” -SitecorePassword “YOUR dev.sitecore.net PASSWORD”
Using you Sitecore credentials it will login to Sitecore and download all the files required to build the Sitecore images.

Sitecore credentials are used by the script to download all the necessary packages required to build the images. If you already have these residing locally you can provide the path as a parameter.

You can also be more prescriptive with the command by specifiying SitecoreVersion (9.3.0, 9.2.0, 9.1.1, 9.0.2), Topology (xm, xp), WindowsVersion (1909, 1903, ltsc2019), IncludeSpe, IncludeSxa, IncludeJss, IncludeExperimental (Publishing Service). This feature has been added more recently.

PS> .\Build.ps1 -SitecoreUsername “YOUR dev.sitecore.net USERNAME” -SitecorePassword “YOUR dev.sitecore.net PASSWORD” -SitecoreVersion 9.3.0 -Topology xm -WindowsVersion ltsc2019 -IncludeSpe

Before you start building images you might want to familiarize yourself with the Windows Version Compatibility for virtualization. As I’ve ran into situations where the companies IT hardware policy doesn’t yet support virtualization required to run the Sitecore docker containers. Your team might be running different versions of Windows so you want to ensure the images you build will run on their machine.

Sharing Container Images

What if you have built Sitecore container images and they reside locally and you want to share them with your team.

The recommended approach is a private registry and there are a few services available. Like DockerHub. However, Azure Container Registry (ACR) allows you to store docker images in repositories while allowing you to take advantage of azure pipelines to automatically rebuild these images when they need to be updated. It is also relatively inexpensive.

If you have built images and they reside locally and you later decide you want to host them on a private registry you can easily push them to a repository like ACR.

Docker Compose

docker-compose

Once you have built your Sitecore images you’ll want to stand up your instance of Sitecore.

A Sitecore instance contains multiple containers: SQL, SOLR, xConnect, CD, CM

While you can start containers individually you also need to setup:
Networks, Ports, Volumes etc

Docker Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure all your application’s services.

The Sitecore Docker Repo already contains the docker-compose.yml files you need to stand up your instance of Sitecore and you can modify these as required to suite your own requirements.

Then, with a single command, you create and start all the Sitecore services defined in your configuration. ps> docker-compose up -d

Persisting Data with Volumes

Containers are supposed to be light-weight.Adding unnecessary data will make it heavy to create and run. Docker provides several ways to mount storage from the host machine to containers.

This enables you to persist application data, or even share data between multiple containers as well. If you examine the example compose files you will see volumes mounted for Solr and SQL (.\data\solr & .\data\SQL) these persist indexes and database data between starting and stopping containers.

You can clean this data up with PS provided or manually move files if you need a vanilla instance. If the databases or indexes do not exists in these directories when you start your container thenthey are automatically recreated, otherwise the existing databases and indexes are used.

Deploying your Solution to a container

Map a Volume on your local directory for example c:\myproject\data\web to c:\src in the Sitecore CM/CD containers.
A Script Watch-Directory.ps1 running in the container watches for changes in c:\src and copies them to c:\inetpub\wwwroot
Now all you need to do Publish your changes using MSBuild, Gulp or Cake to the mapped directory. The script will detect the changes and copy them to your running instance of Sitecore in the container.

NOTE: If a file gets deployed to a container and you later want to remove it, if you remove it from your local mapped volume does not remove it from the container. You can either revert to a vanilla instance (see below), alternatively you can powershell into the specific container and remove the file(s) manually.

Reverting to a Vanilla Instance

Often times we make a mistake or deploy something and we need to recover our instance of Sitecore. With Docker this becomes a relatively easy and fast process.

run docker-compose down
remove any files you have deployed to mapped volumes
run Clean-Data.ps1
run docker-compose up

If you want to persist your Sitecore Content but revert the files system then you simply skip step 3.

Debugging your solution in a container

The Entrypoint script starts MSVSMON.exe
Run: docker container ls
Run: docker container inspect [container id]
In VS open Debug Diag
Change the connection type to Remote
Paste the container IP address in Connection Target along with Port:4024

Set License Environment Variable

Open Powershell as Administrator
Navigate to the cloned directory

PS> .\Set-LicenseEnvironmentVariable.ps1 -Path <sitecore license file path> -PersistForCurrentUser

Note: if this fails with “not digitally signed” error. Run “.\Set-ExecutionPolicy Bypass -Scope Process” first.
Note: use the PersistForCurrentUser switch to persist the license for future sessions.

This will gzip and base64 encode the license file content and save it in $env:SITECORE_LICENSE

Managing your containers

In a previous post I provided some useful tips and commands for working with containers. However, something I have found myself doing more regularly is accessing the actual container file system or wanting to executing an application within the container.

For your containers that are based on windowsservercore you can access via powershell:

PS> docker exec -it <container name/id> powershell

For your containers that are based on nanoserver you can access via powershell:

PS> docker exec -it <container name/id> %windir%\system32\cmd.exe start

Useful Utilities

Whales-Names – is a simplistic solution of why can’t I reach my docker containers by name? problem. Continuously update hosts file (/etc/hosts) with docker container names and aliases and watch for changes.

Install: PS> npm install -g whales-names

To run open Powershell in Administrator as we are going to be editing hosts file entries and need elevated permissions

PS> whales-names

Now you will be able to browse to the hostname/alias for your container(s) specified in the docker-compose file without editing the host file manually.

Additional Info

Happy Docker’ing!!

Neil Killen

Asp.Net, C# & Sitecore MVP