How to create a Docker asset image for your Sitecore Module

Hello all, Today I’m bringing a not so short tutorial about to create a Docker asset image for your Sitecore module, how to publish it to Docker Hub and how to include in your solution. Please note, and I don’t have so much experience in Docker, so if you find something to improve in this post, please share with me. I’m not sure if this is the best way, but it worked for me. :)

This blog post assumes you have gone through the official Sitecore Devex Containers documentation.

In this tutorial, I will create an asset image for my SPEAK3 based XPATH builder module. This module has some files and some Sitecore items which should be deployed.

Preparations

You should download the Sitecore Azure Toolkit from dev.sitecore.net. I’m going to use this tool to get the .dacpac file for the core database which has some items (shortcut) related to this module.

Unzip the Toolkit zip and move your module’s Sitecore package to somewhere on your local drive. I created a new folder, called WDP, and copied the zip file’s content and my XPATH module’s Sitecore Installer Package there.

If it is ready, run the following commands in PowerShell:

Import-Module .\tools\Sitecore.Cloud.Cmdlets.psm1
Import-Modul˛˛e .\tools\Sitecore.Cloud.Cmdlets.dll
ConvertTo-SCModuleWebDeployPackage -Path "c:\wdp\Sitecore.XPathBuilder-1.0.zip" -Destination "C:\WDP"

If it was successful, you should see the scwdp package in the same folder. Now, I will create a new folder, called xpathassets and I will create the following folder structure there: (You can read more about this structure here)

• C:\xpathassets\module\cm\content — Content to overlay base Sitecore images
• C:\xpathassets\module\db — dacpac files with changes to databases required by the module

Now, I will copy the contents from the scwdp file in the following way:

• Copy core.dacpac into the c:\xpathassets\module\db folder with the Sitecore.core.dacpac name. (You should follow the Sitecore.<databaseName>.dacpac format!)
• Copy everything from the Content\Website folder from the scwdp file into the c:\xpathassets\module\cm\content folder

Just to verify, your folder structure and files should look like this:

We will move these files into our new Docker Image.

Docker Hub

It’s time to open the Docker Hub and log in. (If you don’t have an account there, you should register first.) After you logged in, click on the Create Repository button and fill the name and description fields.

If you are not logged in on your PC to Docker Hub, then type the following command in CMD and login with your credentials

docker login

Creating the asset image

We have just prepared the module files and created a repository on Docker Hub. It’s time to create a new Docker image, add some files, and push it.

In order to do the previous steps, let’s place a DockerFile in the c:\xpathassets folder

FROM mcr.microsoft.com/windows/nanoserver:1809 AS build
# Copy assets into the image, keeping the folder structure
COPY \ .\

It will pull a Windows Nano server image. It’s super small, only 254MB. It’s enough for us because we only want store files in the image, we don’t want to run anything special there. After the image pull, it will copy everything from the current folder to the image’s root folder.

It’s time to build the image by running the following command in the c:\xpathassets folder. Pay attention to the “.” at the end of the command, which sets the context for the docker build and will use our defined DockerFile

docker build --tag mitya88/xpathbuilder:1.0.0.0-1809 .

In our case, the tag contains the module version, which is 1.0.0.0

If you call docker image ls command, you should see the following images.

docker image ls command

We can run our image now in a container with the following command:

docker run -it mitya88/xpathbuilder:1.0.0.0-1809

• The -it runs Docker interactively (so you get a pseudo-TTY with STDIN).

In the meantime, a command prompt opened, which runs in the image’s filesystem. Now you can verify if your assets exist in the image. (c:\modules) folder.

It’s time to push it to DockerHub. If you try to convert an official Sitecore module into an asset image, you should not publish it to a public registry. Publishing of any Sitecore assets and the use of the Sitecore brand/trademark is not allowed.

docker push mitya88/xpathbuilder:1.0.0.0-1809

If you open the Docker Hub site, you should see that your repository got updated. You’ve just uploaded your asset image to Docker Hub, so it is ready to be used on your Sitecore project.

How to use the image

• Add the XPATH_VERSION variable to your .env file

XPATH_VERSION=1.0.0.0-1809

• In the compose override files, add the image to the arguments (cm + mssql)

XPATH_IMAGE: mitya88/xpathbuilder:${XPATH_VERSION}

docker-compose.xm1.override.yml

• Update the cm DockerFile with the following lines:

ARG XPATH_IMAGE
......
FROM ${XPATH_IMAGE} as xpath
......
# Add Xpath module
COPY --from=xpath \module\cm\content .\
......

CM docker file, usually located under .\docker\build\cm

• Update the mssql DockerFile too

ARG XPATH_IMAGE
......
FROM ${XPATH_IMAGE} as xpath
......
COPY --from=xpath \module\db \xpath_data
RUN C:\DeployDatabases.ps1 -ResourcesDirectory C:\xpath_data; `
Remove-Item -Path C:\xpath_data -Recurse -Force;
.....

MSSQL docker file, usually located under .\docker\build\mssql

That’s all. If you build and compose, your module should be available in your containerized solution!