THIS REPO IS NO LONGER MAINTAINED.

Sitecore XC Docker is now available here: https://github.com/Sitecore/docker-images.

Run Sitecore XP 9.2.0 and XC 9.2.0 using Docker for Windows.

Disclaimer

This repository contains experimental code that we use in development setups. We do not consider the current code in this repository ready for production. Hopefully this will help you to get up and running with Sitecore and Docker. By no means we consider ourselves Docker experts and thus expect these images to still contain a lot of bugs. Great help for creating this setup was provided by the sitecoreops and sitecore-nine-docker repos. Please feel free to provide feedback by creating an issue, PR, etc.

Requirements

• Windows 10 update 1809
• Docker for Windows (version 18.09.1 or better): https://docs.docker.com/docker-for-windows/
• Sitecore installation files
• Nuke.build
• A valid license.xml file

Build

As Sitecore does not distribute Docker images, the first step is to build the required Docker images.

Pre-build steps

For this you need to place the Sitecore installation files in the files directory. Which files to use are defined in the build configuration files:

• Base images build config
• XP images build config
• XC images build config
• Overall build config

The XP0 Sitecore topology requires SSL between the services, for this we need self signed certificates for the xConnect and SOLR roles. You can generate these by running the ./Generate-Certificates.ps1 script (note that this requires an Administrator elevated powershell environment and you may need to set the correct execution policy, e.g. PS> powershell.exe -ExecutionPolicy Unrestricted).

Build

Build all images using:

PS> nuke 

The build results in the following Docker images:

• Base

  • sitecore-base-sitecore: IIS + ASP.NET
  • sitecore-base-openjdk: Windows Server Core + OpenJDK
  • sitecore-base-solr-builder: sitecore-base-openjdk + Solr
  • sitecore-base-redis: Windows Server Core + OpenJDK

• XP0

  • sitecore-xp-sitecore: IIS + ASP.NET + Sitecore
  • sitecore-xp-mssql: MS SQL + Sitecore databases
  • sitecore-xp-solr: Apache Solr
  • sitecore-xp-xconnect: IIS + ASP.NET + XConnect

• XP0 with SXA installed

  • sitecore-xp-sitecore-sxa
  • sitecore-xp-solr-sxa
  • sitecore-xp-mssql-sxa

• XP0 with JSS installed

  • sitecore-xp-sitecore-jss
  • sitecore-xp-mssql-jss

• XC

  • sitecore-xc-commerce: ASP.NET
  • sitecore-xc-sitecore: IIS + ASP.NET + Sitecore
  • sitecore-xc-mssql: MS SQL + Sitecore databases
  • sitecore-xc-solr: Apache Solr
  • sitecore-xc-xconnect: IIS + ASP.NET + XConnect

• XC with SXA installed

  • sitecore-xc-sitecore-sxa
  • sitecore-xc-solr-sxa
  • sitecore-xc-mssql-sxa

• XC with JSS installed

  • sitecore-xc-sitecore-jss
  • sitecore-xc-mssql-jss

All images are contain a version tag that corresponds to the Sitecore commercial version number e.g. xp-sitecore-sitecore:9.1.1.

Build a selection of images

To build a certain Docker image or set of images run a specific Nuke.Build target, e.g to build only XP0 images:

PS> nuke xp

Each Docker image (or set of images, e.g. XP0 or XC) has a corresponding target definition in the build configuration.

Push images

Before pushing a Docker image you should have a Git tag associated with the current commit. If you don't have a Git tag associated the push target will be skipped. You can overwrite this behavior by using the --ForcePush build parameter.

To push the Docker images to your repository use the push build targets. e.g. to push all images:

PS> nuke push --RepoImagePrefix <YourRepoNameHere>

The BuildVersion parameter value is automatically determined from the associated Git tag. Git tags should have one of the following formats: <sitecore version>-<build version> or <build version>.

Optionally you can specify the build version manually:

PS> nuke push --RepoImagePrefix <YourRepoNameHere> --BuildVersion <YourVersionHere>

Run

Docker compose is used to start up all required services. Examples of docker compose files are present for each setup in their respective directories, e.g. example\xp and example\xc. Use your setup of choice as working directory for all docker-compose commands below.

Create the directories (logs, website, data) which are mounted in the Docker compose file:

PS> ./CreateDirs.ps1

Add your license file to both the example\xp\license and example\xc\license folders. This license files is mounted during runtime.

Place the Sitecore source files in the .\wwwroot\sitecore (and .\wwwroot\commerce for XC) directory.

To start Sitecore;

PS> docker-compose up

If you are using xc then you also have to install the root certificate:

PS> .\InstallRootCertificate.ps1

or to start Sitecore with SXA:

PS> docker-compose -f docker-compose.yml -f docker-compose.sxa.yml up

or to start Sitecore with JSS:

PS> docker-compose -f docker-compose.yml -f docker-compose.jss.yml up

Run-time parameters can be modified using the .env file:

Field	Description
SQL_SA_PASSWORD	The password to use for the SQL sa user
SITECORE_SITE_NAME	Host name of the Sitecore site
REPOSITORY	The Docker repository to use (must include ending slash )
IMAGE_PREFIX	The Docker image prefix to use
TAG	The version to tag the Docker images with

NB. these run-time parameters should match the used build parameters.

DNS

To set the Docker container service names as DNS names on your host edit your hosts file. A convenient tool to automatically do this is whales-names.

Post-run steps

Because we don't want online installations (i.e. a running instance for creating a Docker image) some steps are required after the services are started:

• Populate SOLR schemas
• Rebuild the search indexes
• Initialize the Commerce Engine: Bootstrap, Initialize Environment, etc. (for XC)

Known issues

Docker for Windows can be unstable at times, some troubleshooting tips are listed below.

Containers not reachable by domain name

Sometimes the internal Docker DNS is malfunctioning and containers (e.g. mssql) cannot be reached by domain name. To solve this restart the Docker daemon.

Clean up network hosting

In case it's no longer possible to create networks and docker network commands don't work give this a try: https://github.com/MicrosoftDocs/Virtualization-Documentation/tree/live/windows-server-container-tools/CleanupContainerHostNetworking

No internet connection inside Docker container

Sometimes it can occur that the Docker container has no internet access due to Windows network configuration. See following link for solving this: docker/for-win#1166 (comment)

Clean Docker install

In case nothing else helps, perform a clean Docker install using the following steps:

• Uninstall Docker

• Check that no Windows Containers are running (https://docs.microsoft.com/en-us/powershell/module/hostcomputeservice/get-computeprocess?view=win10-ps):

PS> Get-ComputeProcess

and if so, stop them using Stop-ComputeProcess.

• Remove the C:\ProgramData\Docker directory (and Windows Containers) using the docker-ci-zap tool as administrator in cmd:

PS> docker-ci-zap.exe -folder "c:\ProgramData\Docker"

• Install Docker

Docker build fails

Docker for Windows build can be flaky from time to time. Error messages like below can be solved by trying harder (i.e. more often) and making sure no other programs (e.g. file explorer) have the applicable directory open.

ERROR: Service 'solr' failed to build: failed to register layer: re-exec error: exit status 1: output: remove \\?\C:\ProgramData\Docker\windowsfilter\6d12d77235757f9e1cdd58216d104f0e51bc56e6021cf206a2dd6d97b0d3520f\UtilityVM\Files\Windows\WinSxS\amd64_microsoft-windows-a..ence-inventory-core_31bf3856ad364e35_10.0.16299.15_none_81bfff856a844456\aepic.dll: Access is denied.

Certificate issues with XConnect

There is an excellent describtion of how XConnect uses certificates here: https://kamsar.net/index.php/2017/10/All-about-xConnect-Security/

An issue we encountered lately was the Could not create SSL/TLS secure channel. one (mentioned in above describtion). To grant permissions in a Docker container you can use Carbon, e.g.

PS> Get-Permission -Identity sitecore -Path 'cert:\localmachine\my\9CC4483261B92D7C5B32239115283933FC5014C'

If none are returned for the xConnect.client certificate, you probably need to give permissions to the sitecore user. For example:

PS>  Grant-Permission -Identity sitecore -Permission GenericRead -Path 'cert:\localmachine\my\9CC4483261B92D7C5B32239115283933FC5014C4'

NB. Ensure that the signer certificate is present in cert:\localmachine\root.

Certificates issues with Commerce

Communication between services might fail when the certificates are not installed correctly. Verify what certificates are installed by:

PS> Get-ChildItem cert:\localmachine\my

The certificate thumbprint in <Your>.Commerce.Engine/wwwroot/config.json should match the one in Y.Commerce.Engine/Sitecore.Commerce.Engine.Connect.config. Note that when you have build new images the thumbprint in the <Your>.Commerce.Engine/wwwroot/config.json has to be manually updated.

To determine and set the root certificate to use for a HTTPS connection:

1. Determine certificate used for IIS: PS> Get-WebBinding | Select certificateHash
2. Determine root certificate used to sign the in step 1 obtained certificate: PS> Get-ChildItem cert:\localmachine\my\<certificateHash> | Select Issuer
3. Lookup thumbprint of the issuer: `PS> Get-ChildItem cert:\localmachine\root\
4. Export the root certificate: PS> Export-Certificate -Cert cert:\localmachine\root\<thumbprint> -FilePath <file>
5. Import the root certificate (on the client): PS> Import-Certificate <file> -CertStoreLocation cert:\localmachine\root

Commerce setup

• We have quite a lot of custom powershell scripts for trivial installation tasks. This is because the commerce SIF scripts contain hardcoded values. For example, it is not possible to use hostnames other than localhost. We should be able to remove this custom code when those scripts get fixed.
• During the installation of the commerce server instances, it tries to set permissions on the log folder. For some reason, this results in an exception saying the access control list is not in canonical form. This can be ignored, because the log folders are mounted on the host. However, it does cause an annoying delay in the installation.

Solr errors in Sitecore log

After a clean start Sitecore reports errors like:

ERROR: [doc=sitecore://master/{731cb645-faa3-4440-9511-a27556a63ad9}?lang=fr-fr&ver=1&ndx=sitecore_master_index] unknown field '_indexname_t_fr'

Populating the Solr managed schemas will solve this, e.g. do this via the Sitecore Control Panel.

Solr container not starting because of /data/solr folder rights and no error logs in /logs/xconnect and /logs/sitecore

When starting the Solr docker container the following error can show up:

solr_1      | SOLR_PATH=c:\\solr
solr_1      | SOLR_PORT=8983
solr_1      | INSTALL_PATH=c:\\clean
solr_1      | DATA_PATH=c:\\data
solr_1      | "### No Sitecore Solr cores found in 'c:\\data', seeding clean cores from 'c:\\clean'..."
solr_1      | Access denied
solr_1      | Unable to create directory - C:\data
solr_1      | 0 File(s) copied
solr_1      | "### Starting Solr..."
solr_1      |
solr_1      | ERROR: Solr home directory c:/data must contain solr.xml
solr_1      |
mssql_1     | ### Existing Sitecore databases found in 'c:/data/'...
mssql_1     | ### Attaching 'Sitecore_Core'...
xp_solr_1 exited with code 1

Make sure the /data/solr folder has the 'Users' group added with Modify, Read & Execute, List folder contents, Read and Write permissions.

For logging make sure the /logs/xconnect and /logs/sitecore folder has the 'Authenticated Users' group added with Modify, Read & Execute, List folder contents, Read and Write permissions.