Sitecore Module with Docker

The adoption of containers with Sitecore for both development and production purposes has been growing rapidly over the past few years, and is now a fully supported option even with mainstream support from Sitecore. There are a number of benefits of using containers, more information is available in the documentation.

When using containers, the installation process for modules requires a different approach. The SearchStax for Sitecore Docker images have been built using the recommended format for Sitecore Docker modules, and follow the same structure as other asset type images (e.g. SXA, SPE).

You can find the details of the images in Docker Hub: https://hub.docker.com/u/searchstaxinc

Adding the SearchStax image layer

The module is layered in the same way as all other Sitecore modules and asset images. You must set the environment variables to match your SearchStax instance, update your Docker build files to layer in the module and configure the Docker compose files to utilize these.

Populate the environment variables

In your .env file set the following unassigned variables:

SEARCHSTAX_VERSION=2.2.0-10.2-ltsc2019
SEARCHSTAX_SXA_VERSION=2.2.0-ltsc2019
SEARCHSTAX_ROOT_ITEM=
SEARCHSTAX_INDEX_CORE_NAME=
SEARCHSTAX_DATABASE=
SEARCHSTAX_SEARCHSTUDIOUSERNAME=
SEARCHSTAX_SEARCHSTUDIOPASSWORD=

Please update all the required values for your configuration for your SearchStax instance.

Update your Dockerfiles

You can read more about the Sitecore runtime Dockerfiles in the Sitecore documentation. The SearchStax for Sitecore module follows the same set of basic instructions.

For the CM container modify the Dockerfile to match the following, the new lines have been highlighted (<–).

If you are not using SXA then you do not need to add the SXA layers below.

# escape=`
 
ARG BASE_IMAGE
ARG SXA_IMAGE
ARG SPE_IMAGE
ARG TOOLING_IMAGE
ARG SEARCHSTAX_IMAGE       <--
ARG SEARCHSTAX_SXA_IMAGE   <--
 
FROM ${TOOLING_IMAGE} as tooling
FROM ${SPE_IMAGE} as spe
FROM ${SXA_IMAGE} as sxa
FROM ${SEARCHSTAX_IMAGE} as searchstax          <--
FROM ${SEARCHSTAX_SXA_IMAGE} as searchstaxsxa   <--
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;
 
# Add SearchStax module
COPY --from=searchstax \module\cm\content .\      <--
COPY --from=searchstaxsxa \module\cm\content .\   <--

For Sitecore 10.1 and earlier, for the mssql container modify the Dockerfile to match the following, the new lines have been highlighted (<--)

# escape=`
 
ARG BASE_IMAGE
ARG SXA_IMAGE
ARG TOOLING_IMAGE
ARG SEARCHSTAX_IMAGE       <--
ARG SEARCHSTAX_SXA_IMAGE   <--
 
FROM ${TOOLING_IMAGE} as tooling
FROM ${SXA_IMAGE} as sxa
FROM ${SEARCHSTAX_IMAGE} as searchstax          <--
FROM ${SEARCHSTAX_SXA_IMAGE} as searchstaxsxa   <--
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 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;
 
# Add SearchStax module
COPY --from=searchstax \module\cd\content .\      <--
COPY --from=searchstaxsxa \module\cd\content .\   <--
For the mssql container modify the Dockerfile to match the following, the new lines have been highlighted (<--)
# escape=`
 
ARG BASE_IMAGE
ARG SXA_IMAGE
ARG SPE_IMAGE
ARG SEARCHSTAX_IMAGE       <--
ARG SEARCHSTAX_SXA_IMAGE   <--
 
FROM ${SPE_IMAGE} as spe
FROM ${SXA_IMAGE} as sxa
FROM ${SEARCHSTAX_IMAGE} as searchstax          <--
FROM ${SEARCHSTAX_SXA_IMAGE} as searchstaxsxa   <--
FROM ${BASE_IMAGE}
 
SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]
 
# Add SPE module
COPY --from=spe \module\db \spe_data
RUN C:\DeployDatabases.ps1 -ResourcesDirectory C:\spe_data; `
    Remove-Item -Path C:\spe_data -Recurse -Force;
 
# Add SXA module
COPY --from=sxa \module\db \sxa_data
RUN C:\DeployDatabases.ps1 -ResourcesDirectory C:\sxa_data; `
    Remove-Item -Path C:\sxa_data -Recurse -Force;
 
# Add SearchStax module                                                <--
COPY --from=searchstax \module\db \searchstax_data                     <--
RUN C:\DeployDatabases.ps1 -ResourcesDirectory C:\searchstax_data; `   <--
    Remove-Item -Path C:\searchstax_data -Recurse -Force;              <--
 
# Add SearchStax SXA module                                               <--
COPY --from=searchstaxsxa \module\db \searchstaxsxa_data                  <--
RUN C:\DeployDatabases.ps1 -ResourcesDirectory C:\searchstaxsxa_data; `   <--
    Remove-Item -Path C:\searchstaxsxa_data -Recurse -Force;              <--

For Sitecore 10.2, you should instead update the mssql-init container. The files only need to be copied to the resources directory, the PowerShell deploy script does not need to be run:

<pre class="wp-block-syntaxhighlighter-code"># Add SearchStax module                                                <--
COPY --from=searchstax c:\module\db  C:\resources\searchstax           <--
# Add SearchStax SXA module                                               <--
COPY --from=searchstax c:\module\db  C:\resources\searchstaxsxa           <--
</pre>

Docker Compose File

In your docker-compose.override.yml update the mssql container args to include:

SEARCHSTAX_IMAGE: searchstaxinc/searchstax-for-sitecore:${SEARCHSTAX_VERSION}
SEARCHSTAX_SXA_IMAGE: searchstaxinc/searchstax-for-sitecore-sxa:${SEARCHSTAX_SXA_VERSION}

Update the cd and cm containers args to include:

SEARCHSTAX_IMAGE: searchstaxinc/searchstax-for-sitecore:${SEARCHSTAX_VERSION}
SEARCHSTAX_SXA_IMAGE: searchstaxinc/searchstax-for-sitecore-sxa:${SEARCHSTAX_SXA_VERSION}

and the environment section to include:

SearchStax_RootItem: ${SEARCHSTAX_ROOT_ITEM}
SearchStax_IndexCoreName: ${SEARCHSTAX_INDEX_CORE_NAME}
SearchStax_Database: ${SEARCHSTAX_DATABASE}
SearchStax_SearchStudioUsername: ${SEARCHSTAX_SEARCHSTUDIOUSERNAME}
SearchStax_SearchStudioPassword: ${SEARCHSTAX_SEARCHSTUDIOPASSWORD}

Disabling the health check

For local development, the default Sitecore health check needs to be disabled to make sure that the Search Stax index doesn’t fail the health check. This is recommended anyway to getting meaningful messages due to any startup errors.

traefik:
    depends_on:
      cm:
        condition: service_started
 
  cm:
    healthcheck:
      test: ["CMD", "powershell", "-command", "exit 0"]

Upgrading to 2.0.0 from previous versions

If you are upgrading your Docker/Container instance from a previous version then you will need to reinitialize the databases, which will cause the latest updates to the Sitecore Items to correctly be installed.

The Sitecore containers scripts do not reinitialize or update databases when those database files already exist, so you must pass in the override parameter as an environment variable to the mssql-init container, which will force install the module updates to the database.

mssql-init:
    environment:
      DATABASES_TO_DEPLOY: searchstax

This process only needs to be run once.

Questions?

Do not hesitate to contact the SearchStax Support Desk.