Docker might not like your Sitecore secrets

I quite often clone Sitecore's Docker Examples repo and spin up a Sitecore instance to experiment with. It's a quick way to create a disposable site which I can easily configure and deploy little bits of test code to. But recently I did this and noticed some odd warnings. So here's what happened and why, to help you avoid the same issue...

The Issue

I wandered over to the Github repo and cloned the latest (which was this at the point I was doing it - it will likely change in the future) to my local machine. (This fun may well have existed prior to that point in the commits though - this is just when I noticed it) I made sure Docker Desktop was running (This was v4.34.1) and I ran the init.ps1 script as usual:

.\init.ps1 -LicenseXmlPath "\somefolder\license.xml" -SitecoreAdminPassword "b"

					

That ran without error, so I followed that with some tweaks to the compose files (making XM the default, and removing the CD, Redis and solution images from the process because I didn't need them) and then I tried to start the containers. Sitecore ran, but it also produced some unexpected output:

For the internet's search crawlers, the unexpected bit is that docker compose up shows some warnings:

time="2024-09-12T20:40:44+01:00" level=warning msg="The \"vE\" variable is not set. Defaulting to a blank string."
time="2024-09-12T20:40:44+01:00" level=warning msg="The \"vE\" variable is not set. Defaulting to a blank string."
time="2024-09-12T20:40:44+01:00" level=warning msg="The \"vE\" variable is not set. Defaulting to a blank string."
time="2024-09-12T20:40:44+01:00" level=warning msg="The \"vE\" variable is not set. Defaulting to a blank string."

					

So what's up there?

Working towards an answer

That "vE" didn't seem like something that would be a variable name in this setup. But I did some searching to check, and confirmed it was not a variable in the compose files, nor was it a declaration in the environment file.

As part of that searching what I noted was that while no variable is declared called vE there were some instances of $vE in the values of variables in the .env file. So as an experiment I tried adding a new declaration to the file:

MY_TEST=BlahBlah$Something

					

And when I ran docker compose up again, the warnings had changed:

time="2024-09-12T21:04:23+01:00" level=warning msg="The \"Something\" variable is not set. Defaulting to a blank string."
time="2024-09-12T21:04:23+01:00" level=warning msg="The \"vE\" variable is not set. Defaulting to a blank string."
time="2024-09-12T21:04:23+01:00" level=warning msg="The \"Something\" variable is not set. Defaulting to a blank string."
time="2024-09-12T21:04:23+01:00" level=warning msg="The \"vE\" variable is not set. Defaulting to a blank string."
time="2024-09-12T21:04:23+01:00" level=warning msg="The \"Something\" variable is not set. Defaulting to a blank string."
time="2024-09-12T21:04:23+01:00" level=warning msg="The \"vE\" variable is not set. Defaulting to a blank string."
time="2024-09-12T21:04:23+01:00" level=warning msg="The \"Something\" variable is not set. Defaulting to a blank string."
time="2024-09-12T21:04:23+01:00" level=warning msg="The \"vE\" variable is not set. Defaulting to a blank string."

					

So adding $Something into the value of a variable seems to cause this issue - which seems to confirm that it's the $vE strings I'd seen that were the cause of my original issue.

Looking at documentation it suggests that .env files allow you to do variable substitutions directly. And $someName is part of the syntax for "put the value of the someName variable here". That seems to explain why we see the warning though. Docker is really saying "you've asked me to substitute in the value of the vE variable here, but there's no actual declaration for that variable in this file".

So why were there $vE values in the .env file in the first place then?

Well, looking at the file, they're part of generated security keys that have been set. (Hence an important point here is that you might see entirely different warnings if if your .env file contains different values for these keys) In my file this was part of the TELERIK_ENCRYPTION_KEY definition, but it looks like it might also be an issue for the MEDIA_REQUEST_PROTECTION_SHARED_SECRET. These two variables seem to have a wider range of characters allowed in the "random password generation" function from the .\init.ps1 script.

And if you look in the init script you'll see that for both of the problem variables here, you see statements like:

# TELERIK_ENCRYPTION_KEY = random 64-128 chars
Set-EnvFileVariable "TELERIK_ENCRYPTION_KEY" -Value (Get-SitecoreRandomString 128)

# MEDIA_REQUEST_PROTECTION_SHARED_SECRET
Set-EnvFileVariable "MEDIA_REQUEST_PROTECTION_SHARED_SECRET" -Value (Get-SitecoreRandomString 64)

					

That's setting variables in the .env file to generated values. But when you look at one of the variables where this isn't a problem you see something like:

# SITECORE_IDSECRET = random 64 chars
Set-EnvFileVariable "SITECORE_IDSECRET" -Value (Get-SitecoreRandomString 64 -DisallowSpecial)

					

So it's using a different set of allowed characters for some variables, and the "problem" ones have the wider scope. That -DisallowSpecial flag seems to be keeping the random values to alphanumeric values. You can see the effect clearly by running these commands yourself:

And if you look carefully, you can see the less-restricted string includes $ here - so could trigger this issue.

Conclusion

Watch out for your environment settings!

If you want to get rid of these warnings, remove the $ characters from these variables' values. Either manually by editing the file, or by adjusting the init script to generate secrets without those values in them.

But be aware that in doing this you're reducing the "randomness" of your secrets. That's probably not a huge issue for my disposable search instances, but might be more of an issue in other scenarios.

Edited to add: After posting this, Michael West pointed out a thing I'd missed here. If you enclose your .env file variables in single quotes you shouldn't see this warning no matter the content of your variables. Using a pattern like MY_TEST='BlahBlah$Something' will avoid causing confusion.

So probably the easiest fix is to do that for the two variables mentioned above...

↑ Back to top