dimmy Home Delivery

A few weeks ago, I released an open-source project called dimmy and blogged about some of the motivations behind why I started to build a tool. Today I will be sharing with you a walkthrough (warts and all) on how to start with dimmy from scratch. Even though dimmys ultimate aim is to be a tool to help with docker based development, it spawned from experimentations when applying a docker based development workflow to the Sitecore ecosystem. As such the first focus is on the Windows platform as Sitecore needs Windows Containers.

Before we begin, we need to select what Host OS version you are going to need to get the best performance, and this requires me to touch on container isolation. When using docker in the *nix platform, your only option (well as far as I am aware) is process isolation. Process isolation, unlike a virtual machine, allows docker to share the Host's Kernel along with the Kernel of other containers, this is achieved with a feature called LinuxNamespaces and results in the container having its own view of the system. Other parts of the system, like storage and networking, are isolated with similar mechanisms. How these work exactly is beyond the scope of this article and is a topic for another time.

In the land of Windows, we have another option Hyper-V isolation. The difference with Hyper-V isolation is that each container gets its own Kernel by running it in a small Virtual Machine.

Isolation Modes

Explanation of how Hyper-V isolation differ from process isolated containers.

Microsoft Docscwilhit

This brings us to Sitecore, at launch Sitecore shipped containers for version 10 with two flavours of the Windows Kernel:

1. 1909
2. ltsc2019

So what does this all mean? Well, when using process isolation, we learnt above the containers share the Kernel with the Host and other containers. One of the requirements of this is if a container requires a specific Kernel module that module needs to exist in the Hosts Kernel. In the case of Windows to allow for process isolation, the Kernel version needs to be the same; if it is not, Hyper-V isolation is required.

The above is not strictley true; "the container may start, but full functionality isn't guaranteed" when using different Kernel builds.

Windows Container Version Compatibility

How Windows can run build and run containers across multiple versions

Microsoft Docstaylorb-microsoft

TLDR; Even though Hyper-V isolation is useful, powerful and can be considered more secure, it is still a VM, and it will always be slower. So when picking the Kernel version for your Host think about the Kernel version of your container.

Also note that if you are using Windows 10 process isolation is only available from 2004, have a look at the Windows Container Version Compatibility page above for more information.

Once you have chosen your flavor of sauce, installing dimmy is straight forward as it's distributed as a dotnet tool. Before we can get to the meat of the post there are some prerequisites.

Prerequisites

• Docker
• Windows Containers feature enabled.
• .NET Core SDK
  • Currentley dimmy required this.

With the prerequisites out of the way fire up your favorite terminal emulator and issue

dotnet tool install dimmy --global

This will install the latest version of dimmy

Currently dimmy needs to be run from a terminal that has elevated privileges, make sure you run yours as Administrator. Why do you ask, well keep reading. :)

Next we lets explore the commands:

Project

This command is the heart of the current functionality and also one of the core concepts of dimmy. A dimmy project consist of two parts, a project and a project instance.

1. The project contains the template for your docker-compose *.template.yaml file, and a .dimmy.yaml that contains public developer settings, and some metadata about the project. This directory is intended to be your git repository so you can share dimmy configuration with other members of your team.
2. The project instance contains all the bits needed to run docker-compose up, bind mounts, the generated docker-compose.yaml, and non-public developer settings. This directory is not intended to be checked into source control but can be shared between team members.

attach - Allows you to exec into a a running container, but rather than having to mess around finding container ids you are just asked what role you wish to attach to.

initialise - Bootstraps a dimmy project.

pause - Equivalent to docker-compose pause

start - Equivalent to docker-compose up

stop - Euivalent to docker-compose down

Projects

This is currently incomplete but its planned that it will allow you to interact with all dimmy projects on a host.

Plugins

If project is the core of dimmy, plugins is the deep fryer that makes the dim sim edible. Using the power of NuGet you can install plugins that you or others may release

ls - Lists plugins you have installed (not yet implemented), but by adding the --remote flag you can see what plugins can be found on NuGet

install - allows you to install a plugin. You can provide the package id and version or just run dimmy plugins install and you will be presented with the same options as dimmy plugins ls --remote

Lets install Dimmy.Sitecore.Plugin

What has this given us?

A new project command sitecore-10.0.0

This houses a command to reset the admin password in a running Sitecore 10.0.0 docker-compose service collection. It is planned that more utility commands will be added.

A new command to initialise a Sitecore 9.3.0 or 10.0.0 project, this has some crafted docker compose templates to get you going quickly

There are a bunch of options you can include when initialising as Sitecore project but most of them should have sensible defaults and you won't need to worry about them, but they are there.

Ok lets just do it, copy your Sitecore licence file somewhere (in the blow example C:\)

dimmy project init sitecore-10.0.0 --license-path C:\license.xml --working-path C:\clients\SomeClient\ --source-code-path C:\projects\SomeClient\ --topology xm1 --name SomeClinet

dimmy project init - What happened?

Under the hood dimmy is doing the following:

• Copies a crafted docker-compose template to the source-code-path, based on the selected topology.
• Derives the isolation for the containers for all roles and adds it to the public settings.
• Adds in docker images for each of the roles into the public settings.

• Derives the docker image names for the containers for all roles and adds it to the public settings.
• The supplied licence file is encoded and adds into the non-public settings.
• Generates a SQL SA password and adds into the non-public settings.
• Generates a TelerikEncryptionKey and adds into the non-public settings.
• Generates a Sitecore Admin password and adds into the non-public settings.
• Generates a client secret for the identity server and adds into the non-public settings.
• Generates a Identity Server certificate and certificate password and adds into the non-public settings.
• Generates a Reporting WebAPI key and adds into the non-public settings.

Now we have the project generated we can start it:

dimmy project start

You can supply the --working-path option or you can navigate to the working path in the terminal, dimmy will pick the project context from the path if a .dimmy file is present.

dimmy project start - What happened?

Under the hood dimmy is doing the following:

• Generates a docker compose file from the template.
• Understands the bind mounts in that generates docker compose file and ensures they exist.
• Generates SSL certificates for the CD, CM and ID roles, and adds them to the Traefik bind mount.

• Generates a Traefik config file for the CD, CM and ID roles and adds it to the Traefik bind mount.
• Add in host entries for CD, CM and ID roles.

• Issues docker-compose up.

dimmy generates and installs (to the Trusted Root Certification Authorities) a certificate that can be used to issue other certificates.

終わり

Dimmy aims to be a tool that decorates a developers experience, support both Windows and Linux containers, be transparent in what it is doing and above all not bring lock-in. I want to ensure that everything that Dimmy does a developer can continue doing even without Dimmy but maybe a bit slower. This is not much more than a thought experiment currently but I have big plans. No official road map yet but you can see what enhancements may be on the way. If you wish to contribute, please, by all means, open a PR. Also goes for any bugs you may find open a new github issue.

Thanks