Nowadays, we can run Sitecore in Docker containers so that we don't need to use Sitecore SIF anymore - jus run docker-compose! Thanks to Sitecore Docker GitHub which made this possible! Nevertheless, you still need a Sitecore license to run Sitecore in Docker containers.

If you are reading this article because you are getting Sitecore license error - jump straight to "Setting Sitecore Licence for Sitecore 9.3.0 Docker Containers" section.



New Sitecore Licence Related Features in 9.3.0

In Sitecore 9.3 there were few changes made to the way how you can tell Sitecore where to read the license file content from. These oncoming changes were mentioned by Stephen Pope in his "The containerized mind - Working with Sitecore Containers" presentation at Sitecore Symposium 2019 back in November 2019 in Orlando.

In Sitecore 9.3 the license can be set using SITECORE_LICENSE_LOCATION or SITECORE_LICENSE environment variables which provide two new ways of supplying the licence to a Sitecore instance:

  1. SITECORE_LICENSE_LOCATION environment variable allows overriding the path to license.xml file.
  2. SITECORE_LICENSE environment variable allows setting the license value. This environment variable should be set with the content of license.xml. However, this content should be GZipped and converted to Base-64 string (as per slide above). The corresponding PowerShell code example can be found here: Set-LicenseEnvironmentVariable.ps1

Setting Sitecore Licence for Sitecore 9.2.0 Docker Containers

To set the license for Sitecore 9.2.0 Docker container you just need to mount a local workstation directory to the licence file to the docker container. This can be done using a docker-compose file where you mound the directory in volumes section. For example: 

   cm:
      image: ${REGISTRY}sitecore-xm-cm:${SITECORE_VERSION}-windowsservercore-${WINDOWSSERVERCORE_VERSION}
      entrypoint: powershell.exe -NoLogo -NoProfile -File C:\tools\entrypoints\iis\Development.ps1
      environment:
        - "ENTRYPOINT_STDOUT_IIS_ACCESS_LOG_ENABLED=false"
        - "ENTRYPOINT_STDOUT_IIS_ERROR_LOG_ENABLED=false"
        - "ENTRYPOINT_STDOUT_SITECORE_LOG_ENABLED=true"
      volumes:
        - ${LICENSE_PATH}:C:\license
      ports:
        - "44001:80"
      links:
        - sql
        - solr

Full docker-compose file example: docker-compose.xm.yml

In the volumes mounts ${LICENSE_PATH}:C:\license expression in the docker-compose file example, the last part C:\license represents the directory path on the cm container file system where your local workstation directory is mounted into. The first part is the actual directory path where the license.xml resides on your local workstation. However, in the example above it has ${LICENSE_PATH} value. This is expression refers to LICENSE_PATH environment variable, which you must set to your local workstation license.xml contained directory path.

There two ways to set the environment variable value which then can be used in the docker-compose file:

  • Using Windows Environment Variables on your local workstation:


    You can use this method on development workstations so that all your Sitecore Docker environments use the same development license file.
  • Using .env file which is usually placed in the directory where your docker-compose YML files reside:
    
  REGISTRY=
  WINDOWSSERVERCORE_VERSION=1909
  NANOSERVER_VERSION=1909
  SITECORE_VERSION=9.2.0
  LICENSE_PATH=C:\Sitecore\lic

    You can use this method to set different license files for Sitecore Docker environments which are created using a different set of docker-compose files located in separate directories or local Git repositories.

    Considerations:
    It is usual that .env file and docker-compose files are located in the same directory and represent a Sitecore Docker environment for a specific project, therefore, .env file and docker-compose files may need to be committed to the version control, In this case, you should consider setting LICENSE_PATH in .env file only when you are sure that the license directory path will be the same on all development workstations of your team.

Setting Sitecore Licence for Sitecore 9.3.0 Docker Containers

The default approach to set the license for Sitecore 9.3.0 Docker containers would be to run Set-LicenseEnvironmentVariable.ps1. For example:

.\Set-LicenseEnvironmentVariable.ps1` -PersistForCurrentUser -Path "C:\Sitecore\lic\license.xml"

The PowerShell call above will take the license.xml file's content, GZip it, convert to Base-64 string, and store the result in the current user's SITECORE_LICENSE environment variable. The idea is that once it is done you can just run docker-compose and get Sitecore environment up and running.

You may run into issues with this approach. The Sitecore container is not getting Base-64 string in full from your local SITECORE_LICENSE environment variable - it gets the truncated value. Therefore you are getting the corresponding licence loading error when Sitecore container runs.

Workaround/Alternative: Set SITECORE_LICENSE in .env File 

You can set SITECORE_LICENSE value in .env file which does not have issues with long environment variable values.

After you already executed Set-LicenseEnvironmentVariable.ps1 , run the following command in PowerShell to get proper Base-64 string license value in full: 

Write-Host $([Environment]::GetEnvironmentVariable("SITECORE_LICENSE", "User"))

The PowerShell console will print Base-64 string license so you can copy and paste it to .env file where you set it as SITECORE_LICENSE environment variable value.

Then it would be recommended to remove the current user's SITECORE_LICENSE environment variable value, which can be done with the following PowerShell command: 

[Environment]::SetEnvironmentVariable("SITECORE_LICENSE", $null, "User")

Now you can run docker-compose and get Sitecore environment up and running.

Good Old Way Alternative - use 9.2.0 physical license file path approach for 9.3.0

If you are more familiar with the license file path approach for Sitecore 9.2.0 Docker containers and you love it then there is some good news for you: you can still use the file path approach!

However, for 9.3.0 you will need to use SITECORE_LICENSE_LOCATION environment variable which should be set inside the container. This is not a problem - you can set in in environment section of the docker-compose file.

IMPORTANT!
Before we can get started with the license file path approach walkthrough, lets set a pre-requisite assumption that you already set LICENSE_PATH environment variable on your local workstation in Windows Environment Variables or in .env file to your local workstation license.xml contained directory path (as described earlier in this article).

Let's assume that you cloned Sitecore Docker repository and built all images. Now you would like to start XM instance with JSS module enabled from /windows/tests/9.3.x/ directory by running: 

docker-compose -f "docker-compose.xm.jss.yml" up

You will need to update the original docker-compose.xm.jss.yml file so that it instructs Sitecore container to use SITECORE_LICENSE_LOCATION instead of SITECORE_LICENSE .

For cm and cd Sitecore container's environment section, you need to replace SITECORE_LICENSE: $ {SITECORE_LICENSE} with SITECORE_LICENSE_LOCATION: C: \ license \ license.xml . This will tell Sitecore where the license file is located inside the container. C: \ license \ license.xml is a container's file system path!

In addition, for cm and cd Sitecore container's volumes section, you need to mount your local workstation license.xml contained directory in the same way you did it for 9.2.0:


   volumes:    
     - ${LICENSE_PATH}:C:\license:ro

As a result of your changes would get a modified version of the docker-compose.xm.jss.yml file which you can commit to you version control repository and share with your development team members. As long as your team members have LICENSE_PATH environment variable set they can just run docker-compose.xm.jss.yml file without taking any extra actions to set the license for Sitecore 9.3.0 containers.


The modified version of the docker-compose.xm.jss.yml may look as follows:

WARNING!

cm and cd Sitecore containers expect that SITECORE_LICENSE_LOCATION is set to the full path of the license.xml file on the container's file system:

SITECORE_LICENSE_LOCATION: C:\license\license.xml

All other Sitecore containers like, for example, xconnect-indexworker expect that SITECORE_LICENSE_LOCATION is set to the full path of the directory where license.xml resides on the container's file system:

SITECORE_LICENSE_LOCATION: C:\license

Please mind this aspect when you run Sitecore XP or XC topologies!


Sitecore XP Example: the modified version of the docker-compose.xp.jss.yml may look as follows: