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.
This brings us to Sitecore, at launch Sitecore shipped containers for version 10 with two flavours of the Windows Kernel:
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.
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.
- 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:
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.
- The project contains the template for your docker-compose
*.template.yamlfile, and a
.dimmy.yamlthat 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.
- 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
This is currently incomplete but its planned that it will allow you to interact with all dimmy projects on a host.
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
What has this given us?
A new project command
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-pathoption 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.