Embarking on a journey with Docker and Sitecore can be an exciting venture, especially given the fascinating complexity and efficiency of Docker images. If you're intrigued by questions such as 'How are Docker images constructed?' or 'How can I integrate custom or hotfix packages into Sitecore?', then you're in the right place. This guide will help you leverage the power of Docker's containerization capabilities, focusing on creating a customized Docker image for your Sitecore module.
Understanding the Docker and Sitecore Environment
Contrary to the process on a traditional on-premises Sitecore setup, installing packages in a Sitecore Docker environment requires a unique approach. The key distinction stems from the inherent design of Docker itself. Docker images are crafted to be unchangeable, and instances are created with disposability in mind.
The Challenge with Docker Packages Installation
Sitecore has put stringent restrictions on runtime application access. For instance, the 'bin' folder (and potentially other folders) has been designated as read-only for the runtime user. This fundamental characteristic of Docker containers within Sitecore underscores the importance of adopting a tailored approach for package installation.
The Solution: Creating a Customized Image for Your Package
Wondering how to install packages for Docker or Kubernetes? The simple answer is to create a customized image for your package. In this blog, we will learn how to do it. I'll be using one of my custom packages for containerizing it.
Prerequisites for Containerizing Your Module
Before you begin containerizing your module, it is essential to ensure that your local machine is prepared with the following prerequisites.
Running instance of Sitecore 10.3 using Docker: Download the repository from Sitecore's official GitHub "Custom Images" template to set up a working instance of Sitecore 10.3 using Docker.
Other prerequisites for running Sitecore using Docker on your local machine
Sitecore custom package: Prepare a Sitecore custom package that will be used for containerizing your module.
Sitecore Azure Toolkit: Install the Sitecore Azure Toolkit, which is used for converting items to the dacpac format. Follow the official documentation for the Getting started with the Sitecore Azure Toolkit to complete the installation.
Azure account: For uploading the container image to Azure Container Registry
Install Sitecore Azure Toolkit (SAT) for Package Conversion
To use the Sitecore Azure Toolkit, you need to install specific prerequisites, which can be found in Sitecore's Official Documentation. Once you have successfully installed the prerequisites, you can then proceed with the following steps on converting Sitecore packages to image.
Converting Sitecore Package to scwdp file using SAT
Once you have finished installing the SAT prerequisites, you are ready to proceed with generating the scwdp package using the Sitecore package.
To create the scwdp package using the Sitecore Azure Toolkit, follow these steps:
Download the Sitecore Azure Toolkit from Sitecore's Download page.
Extract the files in your desired drive. For example, extract the files to D:\connector.
Copy the Sitecore Package you want to convert into the container. Ensure that the package contains the necessary config file, DLLs, JS, styles, and Sitecore items from both the Core and Master databases.
Open PowerShell as an administrator and navigate to the D:\connector directory using the following command: `cd D:\connector`.
Import the Package Converter and convert the Sitecore package to the scwdp package by running the following commands:
Import-Module .\tools\Sitecore.Cloud.Cmdlets.psm1
Import-Module .\tools\Sitecore.Cloud.Cmdlets.dll
ConvertTo-SCModuleWebDeployPackage -Path "D:\connector\{Name-of-your-sitecore-package}.zip" -Destination "D:\connector" Replace `{Name-of-your-sitecore-package}` with the actual name of your Sitecore package.
The above command will create the scwdp file in zip format in the D:\connector directory.
Note: If you encounter the exception "ConvertTo-SCModuleWebDeployPackage: The type initializer for 'DotNet.Basics.IO.SystemIoPath' threw an exception" when running the ConvertTo-SCModuleWebDeployPackage command, you can resolve it by using Windows PowerShell version 5.1 instead of version 7.
Converting SCWDP Files into a Docker Container Image
To convert the scwdp file into a container image, follow the steps below:
Followed Sitecore's official Image Structure recommendation and created folder structure accordingly.
Create a new folder at C:\Connector.
Folder structure to be created:
C:\Connector\module\cm\content
C:\Connector\module\db
Unzip the scwdp.zip file.
Copy all dacpac files from the root of the zip folder to C:\Connector\module\db. Rename them in the format Sitecore.<databaseName>.dacpac (e.g., Sitecore.master.dacpac, Sitecore.core.dacpac).
Copy the contents of {Unzipped scwdp folder}\Content\Website to C:\Connector\module\cm\content.
Creating a Docker image and pushing it to Azure Container Registry (ACR)
Create a DockerFile in the directory C:\connector\.
Copy the following content into the Dockerfile:
FROM mcr.microsoft.com/windows/nanoserver:ltsc2022 AS build
# Copy assets into the image, keeping the folder structure
COPY / ./To build the Docker image, open PowerShell in admin mode and navigate to C:\connector\. Then, execute the following command:
docker build --tag connector:1.0.0 .Note: "connector:1.0.0" represents the name and tag of the image.
Once the image is successfully built, run the following command to launch the image and verify that all your files are present:
docker run -it container_idNote: "container_id" refers to the ID of the container image you just created using the "docker build" command.
Before pushing the container to Azure Container Register, you need to create a repository. For detailed instructions, please refer to Microsoft's official documentation on Quickstart: Create an Azure container registry using the Azure portal.
Use the following commands to tag the image and push it to Azure Container Registry:
docker tag connector:1.0.0 connector.azurecr.io/connector:1.0.0
docker push connector.azurecr.io/connector:1.0.0Note: "connector:1.0.0" represents the name and tag of the image in the Azure Container Registry.
Add the image to your Sitecore instance
To verify the image and test its functionality, use Sitecore's Custom Image for Docker.
Clone the Sitecore Custom Image for Docker repository.
Make the following changes to add your custom module:
Create a custom module specifically for CM with items on both Core and Master DB.
Modify the docker-compose.override.yml and Dockerfile of cm and mssql-init.
In the docker-compose.override.yml file, add the custom module as follows:
cm:
image: ${REGISTRY}${COMPOSE_PROJECT_NAME}-xp0-cm:${VERSION:-latest}
build:
context: ./docker/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}
CONNECTOR: connector.azurecr.io/connector:1.0.0
volumes:
- ${LOCAL_DATA_PATH}\cm:C:\inetpub\wwwroot\App_Data\logs
- ${LOCAL_DATA_PATH}\devicedetection:C:\inetpub\wwwroot\App_Data\DeviceDetection
- C:\tools\entrypoints\iis\Development.ps1
mssql-init:
image: ${REGISTRY}${COMPOSE_PROJECT_NAME}-xp0-mssql-init:${VERSION:-latest}
build:
context: ./docker/build/mssql-init
args:
BASE_IMAGE: ${SITECORE_DOCKER_REGISTRY}sitecore-xp1-mssql-init:${SITECORE_VERSION}
SPE_IMAGE: ${SITECORE_MODULE_REGISTRY}sitecore-spe-assets:${SPE_VERSION}
CONNECTOR: connector.azurecr.io/connector:1.0.0Open the Dockerfile of CM and make the following changes:
# escape=`
ARG BASE_IMAGE
ARG SXA_IMAGE
ARG SPE_IMAGE
ARG TOOLING_IMAGE
ARG CONNECTOR
FROM ${CONNECTOR} as connector
FROM ${TOOLING_IMAGE} as tooling
FROM ${SPE_IMAGE} as spe
FROM ${SXA_IMAGE} as sxa
FROM ${BASE_IMAGE}
SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]
# Copy development tools and entrypoint
COPY --from=tooling \tools\ \tools\
WORKDIR C:\inetpub\wwwroot
# Add SPE module
COPY --from=spe \module\cm\content .\
# Add SXA module
COPY --from=sxa \module\cm\content .\
COPY --from=sxa \module\tools \module\tools
RUN C:\module\tools\Initialize-Content.ps1 -TargetPath .\; `
Remove-Item -Path C:\module -Recurse -Force;
COPY --from=connector \module\cm\content .\Open the Dockerfile of mssql-init file and make the following changes:
# escape=`
ARG BASE_IMAGE
ARG SPE_IMAGE
ARG CONNECTOR
FROM ${SPE_IMAGE} as spe
FROM ${CONNECTOR} as connector
FROM ${BASE_IMAGE}
SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]
COPY --from=spe C:\module\db C:\resources\spe
COPY --from=connector \module\db C:\resources\connectorTo verify your changes in Sitecore, open PowerShell in admin mode and execute the following command:
docker compose up -dNavigate to Sitecore, and you will be able to observe your changes reflected in the Sitecore Content Tree.
Congratulations, you've now successfully created a Docker asset image for your Sitecore module! You've learned how to navigate the unique environment of Docker and Sitecore, overcome the challenges of installing Docker packages, and create a customized image for your package. Remember to keep exploring and learning, and don't hesitate to revisit this guide as you continue your Docker and Sitecore journey!