Add Sitecore modules

If you have not already done so, clone the Docker Examples repository to a location on your machine, such as C:\sitecore\docker-examples\ (the example uses this folder). We use the custom-images folder in the example.

Sitecore provides officially supported module asset images that contain the required files and scripts you need to install a Sitecore module when you build your custom Sitecore images. Similar to your your solution, these asset images are intended as a source during build and they are not used at runtime.

There is a single asset image for each Sitecore module for each topology. Refer to the Sitecore module reference for a list of all modules available.

Note there are no xp0 images. For a Sitecore Experience Platform - Single (XP0) instance, you use the xp1 images (for example, sxa-xp1-assets).

Each module asset image contains resources with this file structure:

Although you never run an asset image as a container, you can still explore the file system if you run the image with an interactive shell. The Sitecore Docker cheat sheet explains how.

To install a given Sitecore module, use these resources to deploy files, database, and index changes to the base Sitecore runtime images during your custom image build process by adding the required Dockerfile instructions to your Sitecore runtime Dockerfiles.

The following example shows the configuration for adding the Sitecore PowerShell Extensions (SPE) and Sitecore Experience Accelerator (SXA) modules to a Sitecore Experience Platform - Single (XP0) topology.

Add Dockerfile instructions

To add Dockerfile instructions for each role:

• Content Management (CM) role

  Open the Sitecore runtime Dockerfile for the cm service (for example C:\sitecore\docker-examples\custom-images\docker\build\cm\Dockerfile). You can see the module asset images for SPE and SXA are brought in at the start with ARGs (configured in Docker Compose), and then initiated as named build stages spe and sxa to be used later on.

  RequestResponse

  Copy

  ARG SXA_IMAGE
  ARG SPE_IMAGE
  [...]
  FROM ${SPE_IMAGE} as spe
  FROM ${SXA_IMAGE} as sxa

  The required cm Dockerfile instructions are added for both SPE and SXA, just after the WORKDIR instruction.

  RequestResponse

  Copy

  COPY --from=spe \module\cm\content .\
  
  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;

  Notice the COPY instructions have been adjusted to:

  • Use the actual named build stages of spe and sxa for the source --from

  • Use a relative path .\ for the destination, because the preceding WORKDIR sets the working directory to C:\inetpub\wwwroot

  Tip

  To optimize caching, add module instructions before any solution instructions, following the Dockerfile best practice of ordering steps from least to most frequently changing.

• Microsoft SQL Server (mssql-init) role

  Now open the Sitecore runtime Dockerfile for the mssql-init service (for example, C:\sitecore\docker-examples\custom-images\docker\build\mssql-init\Dockerfile). The same ARG and build stages are declared, and then the required mssql-init Dockerfile instructions are added for both SPE and SXA.

  RequestResponse

  Copy

  COPY --from=spe \module\db \spe_data
  

• Apache Solr Init (solr-) role

  Finally, open the Sitecore runtime Dockerfile for the solr-init service (for example, C:\sitecore\docker-examples\custom-images\docker\build\solr-init\Dockerfile). The same ARG and build stages are declared, and then the required solr-init Dockerfile instructions are added, in this case only for SXA.

  RequestResponse

  Copy

  COPY --from=sxa C:\module\solr\cores-sxa.json C:\data\cores-sxa.json
  

  Note

  The SXA module is also included in the cd Sitecore runtime Dockerfile (for example, C:\sitecore\docker-examples\custom-images\docker\build\cd\Dockerfile), for use in XP1 and XM1 topologies.

Configure in Docker Compose

To see how you configure this in Docker Compose:

• Open the docker-compose.override.yml file at the root of the custom-images folder (for example, C:\sitecore\docker-examples\custom-images\docker-compose.override.yml). The cm service is configured as follows:

  RequestResponse

  Copy

  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}spe-assets:${SPE_VERSION}
        SXA_IMAGE: ${SITECORE_MODULE_REGISTRY}sxa-xp1-assets:${SXA_VERSION}
        TOOLING_IMAGE: ${SITECORE_TOOLS_REGISTRY}sitecore-docker-tools-assets:${TOOLS_VERSION}
        SOLUTION_IMAGE: ${REGISTRY}${COMPOSE_PROJECT_NAME}-solution:${VERSION:-latest}
    [...]

The SPE_IMAGE and SXA_IMAGE values are configured to use the Docker image repositories for each module according to the Sitecore module reference. There are no xp0 images, so SXA uses sxa-xp1-assets.

The specific module image tag or version is defined with dedicated SPE_VERSION and SXA_VERSION variables. These are defined in the environment file (.env).

The remainder of the services (mssql-init and solr-init) are configured in a similar way.

To run the Docker Examples: