Over the past year and a half, the Sitecore Community has really embraced the use of Docker to simplify the installation and set up of local development environments, based on the scripts from the community contributed repository to create images for Sitecore.

Sitecore itself has recognised the ease this offers to vastly simplify a complex installation process, and since Sitecore 10 you no longer need to even create the Docker images yourself, instead they are made available on a publicly available container registry.

We here at Konabos have embraced and loved using Docker. However, (you knew this was coming right?) we felt like the example repositories and compose files are a little…. lacking 😔

In the Community Repository there is a plethora of example compose files for the different module combinations (for Sitecore 9.3 for example). If you are working with Sitecore 10, you need to set these up yourself. If you are familiar and comfortable with Docker then this is not an issue. But if you are just starting out on your Docker journey then trying to build these may end up taking you on a long initial journey.

To help you on your journey, you can find a number of Sitecore 10 Docker Examples here:

https://github.com/konabos/konabos-docker-examples

This repository contains example compose files and associated configuration that we use internally at Konbabos. It is loosely based on the original Docker Examples repo - be sure to look through that repo and read the documentation provided there.

The examples contained in this repo were designed to allow us to quickly get up and running on a project or just for personal hacking and intended mainly for local development purposes.

Some features of the examples in this repository:

• Folder-based license mount. Simply copy your license.xml file to the license folder
• The removed build of layers that were not changed from default images
• Generation of SSL certs for Traefik if they do not exist
• start.ps1 and stop.ps1 scripts to bring environments up/down, which allows tabbed completion in a Powershell terminal and to run other commands
• Allow user specific override of environment variables
• Modified clean.ps1 allowing you to remove files without deleting databases
• Removed the need to modify the hosts file by using a domain that provides a local loopback

Each topology is designed to work in isolation. To start using a topology on a project, we can simply copy the entire folder without having to worry about files in multiple folders.

The docker-compose.yml file in each folder is the exact one provided by Sitecore, and all edits are made to the override file. This helps keep the changes isolated and upgrades easier in the future.

Getting Started

1. Copy your license.xml file to the ./docker/license folder of the topology of your choice
2. Run start.ps1
3. The first time you may be prompted to install a root certificate authority (CA) certificate. This is required by mkcert to allow local SSL certs to be used without warnings and errors. Click yes to install the certificate.

Yes, that really is it. Obviously, make sure that prerequisites for Docker have been installed.

Custom Settings

We default a bunch of settings and environment variables. For hacking purposes, you probably don't care what these are locally and by checking them into source control we can get up and going really quickly. If your some reason you don’t want to use Konabos domain name (boo!) then you can regenerate all the settings using the following command, passing in the additional parameters if required:

./docker/tools/init.ps1 -HostName myhost

| Parameter             | Alias | Default       |  | ---------             | ----- | -------       |  | HostName              | h     | -             |  | HostSuffix            | s     | localho.st    |  | SitecoreAdminPassword | a     | b             |  | SqlSaPassword         | sa    | Password12345 |  We default the host suffix to localho.st, which provides a local loopback to 127.0.0.1 and means that no modifications are required to your host's files, either manually or using additional containers such as Windows Hosts Writer or whales-names.

In our experience, modification of the hosts files can also be an issue in certain organisations which prevent due to group policy or mandatory use of certain virus scanners such as Symantec Endpoint Security which prevent modification for security reasons.

Use of this domain will require an active internet connection, and if you want to be hacking offline (on the plane?) then you may want to revert back to using WHW. An example is included in the repository.

Local deployment

The setup is for simplicity, for local development. Deploy your files to ./docker/data/cm/website folder.

This is very similar to how the Sitecore 9.3 Community Repository was configured. We do not have volume mounts for XConnect, feel free to add them if you them.

For more complex deployments the build using a solution container makes a lot of sense, but for simple solutions or for local hacking purposes we find the simplicity or simply deploying to a known folder much easier and provides a simpler upgrade process for most projects – simply switch your deploy location from Inetpub to the data folder.

Clean up of deployed files

The clean.ps1 is a modified version from the original repo and uses git clean to remove files from the data folder.

By default, mdf/ldf database files are not removed. We find this extremely useful to clean our deployed files and start from a clean slate but not have to go and resync the databases again, which can be a timely process.

You can force deletion of the database by passing the “-IncludeDatabases” flag (alias -i).

Start / Stop Scripts

One of the things that get annoying pretty fast is having to type docker-compose up -d, usually forgetting to add the detached the first time and having to down and then up again. Also assuming there wasn’t a typo as well.

Since we run these commands from PowerShell, it’s much easier to put the command in a script, and we can then take advantage of tabbed-completion. st-tab-enter is much easier.

Since we have the script, we can now add a few other helpers and checks in there to make our life easier. This script will:

• Add some cool Konabos ASCII art. We love that horse! 🐴
• Run a prune to clean up from previous dangling and unreferenced containers 🧹
• Check the license file is present 📜
• Create the SSL certs if they don’t already exist 🔐
• Load user specific variable overrides 👩‍💻👨‍💻
• Start your Docker instance 🐳
• Open the browser to the homepage 🏠 

User Specific Override of Environment Variables

You can override the variables from .env on a per user basis. Copy .env.user.example to .env.user and modify the values as required.

More on this feature in a post soon.

SSL Certificate Generation

Since Sitecore 9.3, the use of SSL certificates is enabled by default. This is an industry best practice, and many browser features will not work without a valid SSL certificate (such as the GeoLocation API for example).

The start script will check if the certificates exist, if not it will generate them using mkcert. If this is the first time you are running mkcert then you will be prompted to install a root certificate authority (CA) certificate. This is required to allow you to generate local trusted self-signed certificates and not get errors in your local browser.

If you want to change the HOST name (in the .env file) then either run init.ps1 or manually change it and delete the PEM cert files from the Traefik folder, they will be correctly generated the next time based on the setting from the .env file.

Sitecore Container Registry

The Sitecore 10 examples use the official Sitecore Container Registry.

The Sitecore 9.3 example requires you to build your own images from the Community Repository. The default Registry setting in the .env files is pointing to an internal Konabos container registry. This will not work for you (since it is a private repository). Update the value as required after you have built the Sitecore 9.3 images.

Examples provided in the repository

The following examples are currently available in the repository.

• Sitecore 10 XM: Includes SPE, ID Server disabled, CD instance scaled down.
• Sitecore 10 XP: Includes SPE, CD instance scaled down.
• Sitecore 10 XP + SXA: Includes SPE and SXA. CD instance scaled down.
• Sitecore 10 XP + JSS: Includes SPE and JSS. NodeJS is also installed on the CM instance. CD instance scaled down.
• Sitecore 10 XP + SXA + JSS: Includes SPE, SXA and JSS. NodeJS is also installed on the CM instance. CD instance scaled down.
• Sitecore 10 XP + Windows Hosts Writer: Includes SPE and CD instance scaled down. Also provides an example of using Windows Hosts Writer by Rob Ahnemann.
• Sitecore 9.3: An example of Sitecore 9.3 SPE or SXA running using Traefik and SSL (i.e. the same as Sitecore 10). Note that ID Server is disabled. We've tried to backport the pattern used in the current compose files to 9.3, using Traefik and overrode compose files for consistency.

We’ll probably add more over time but get in touch if you can think of other useful topologies.

Yes, there is a lot of duplication of the files between the folders. We could have been really smart and put everything in a single folder and then had multiple different compose files. But this structure allows us to copy/paste an entire folder to a new project, run init.ps1 to set up the project-specific variables, and getting easily up and running. It also makes it very easy to compose down and switch to a different topology. You can diff the folders to quickly see the difference between them.

We hope you enjoy the setup and find them useful.