Building Sitecore Dianoga Docker Asset Image Using GitHub Actions

 This is a copy of my blog post originally posted here to keep all things in one place.

 We figured out with Sitecore Docker Asset Images. And we build our own ones for Dianoga. Now, it is time to automate it's buildind and push this image to Docker Registry.

I hate to build anything manually. Especially, I hate the moment when you just finished building everything, but you need to make one small change and rebuild everything. That is frustrating. Fortunately, there are many different tools for CI/CD. And many of them are free for open source. Previously I preferred to use Appveyor for my open-source projects. In my opinion, it is the most friendly CI system for .Net developers. I made and automation of building Sitecore packages. And I used it for a few my packages. But nowadays, GitHub Actions become much more powerful. That is why it is possible to keep everything on GitHub. And avoid zoo of services for different purposes.

There is an official GitHub Action to build and push Docker images. But it will not work for us. It doesn’t support the build of Windows-based images. Someday, it probably will support it, but taking into account that ticket was opened on the 23 of March 2020 year, there are quite small chances that it will happen someday.

But GitHub Actions have windows-2022 and windows-2019 runners that include Docker. It means that it should be possible to build Windows-based Docker images using Github actions. It could be done in 2 ways. Either run Docker commands by yourself. Or use Docker Build & Push Action from the community. I decided to select the usage of community action to save some time. But there are no limitations to running all Docker commands by yourself.

Dianoga has support of different .Net versions: 4.8, 4.7.1, 4.6.2, and 4.5.2. (You may say, that 4.5.2 is for the old Sitecore version and you will never use it with containers. And you will be absolutely right.) Also, there are 2 build configurations: Release and Debug. Combinations of .Net version and build configuration give us multiple Docker Asset Images. We definitely don’t want to build and push them manually. It is long and boring.

It gives us an understanding, that we need to introduce 2 variables ${{ env.BUILD_CONFIGURATION }} and ${{ env.DIANOGA_DOTNET_VERSION }}. But all other build logic could be shared ./.github/actions/publish-docker-hub

name: Dianoga Docker CI, .NET 4.8, Release
on:
  push:
    branches: [ feature/docker ]
env:
  BUILD_CONFIGURATION: Release
  DIANOGA_DOTNET_VERSION: net48
jobs:
  build:
    runs-on: windows-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Run custom action
        uses: ./.github/actions/publish-docker-hub
        with:
          build_configuration: ${{ env.BUILD_CONFIGURATION }}
          dotnet_version: ${{ env.DIANOGA_DOTNET_VERSION }}
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

And here is what common part will look like:

name: "Publish to Docker"
description: "Pushes built artifacts to Docker"
inputs:
  build_configuration:
    description: "Debug/Release"
    required: true
  dotnet_version:
    description: "net45/net46/net471/net48/etc"
    required: true
  username:
    description: "Docker registry username"
    required: true
  password:
    description: "Docker registry password"
    required: true
runs:
  using: "composite"
  steps:
  - uses: mr-smithers-excellent/docker-build-push@v5
    name: Build & push Docker image
    with:
      image: antonytm/dianoga-assets
      tags: 6.0.0-beta.2-${{ inputs.dotnet_version }}-${{ inputs.build_configuration }}-${{ github.run_number }}, latest-${{ inputs.dotnet_version }}-${{ inputs.build_configuration }}
      registry: docker.io
      dockerfile: Dockerfile
      username: ${{ inputs.username }}
      password: ${{ inputs.password }}
      buildArgs: |
        BUILD_CONFIGURATION=${{ inputs.build_configuration }}, DOTNET_VERSION_ARG=${{ inputs.dotnet_version }}

You man notice that we use 2 secrets DOCKERHUB_USERNAME and DOCKERHUB_TOKEN. They are configured at the setting of your GitHub project.

Now, everything is ready. We are able to build our Dianoga Docker Asset Image using GitHub action.

And we are able to see built images in the Docker registry.

Use Font Awesome or MUI as Sitecore Icons

This is a copy of my blog post originally posted here to keep all things in one place.

  If you read the title of the article, understand everything from the title, and you are impatient to try FA or MUI icons on Sitecore instance by yourself then you may download Sitecore packages on Github. But if you want the full story, grab a cup of tea and enjoy it below.

There are 8755 icons in the latest Sitecore version 10.2. But the major of icons was added a long time ago. They are still good and you can cover 95% of your needs. But when you need an icon for some brand(Azure, Amazon, Google), you are in trouble. Also if want an icon for something relatively new (NFT, Bitcoin, Coronavirus), you are also in trouble. There are no such icons. And sometimes, you just can’t find the right icon for your specific case and need to use another compromise icon.

I understand Sitecore. They need don’t violate property rights with brand icons. We, as website developers, don’t have so strict limitations as we implement the site on Sitecore and don’t sell it with brand icons. Also, Sitecore needs to keep backward compatibility. You, as a customer, don’t want to see an icon, that you used for your website, disappeared in the new version. Even if it is an icon for PCI Card Network. You should keep it, because someone may use it in their implementation. Also, adding a new set of icons increases mess. You already have almost 10k icons, almost for everything. Why do you need one more icon for a car? And it is impossible to make every customer happy. One set of icons will be suitable for a car dealer, but completely another for a hotel chain.

On the other hand, icon libraries become very popular in the last few years. If you are a web developer then you definitely had a project, where you used Font Awesome. Or if you make your website using Material UI, you probably used icons from this library. Why don’t use the same icons for the Sitecore backend? It will make content editors happy. All that we need is to convert icons from one format to another and make small Sitecore adjustments to be able to use new icons.

Sitecore icons are saved in PNG format, but all modern icon libraries have SVG format. The SVG format is a subset of XML, we can easily process these files, and change size and colors. And there are millions of tools for converting images from one format to another. I selected ImageMagick, it fully fits our needs.

Both FA and MUI icons are provided in one color. During processing, we are able to add as many colors as we need. I added 4 colors: blue, red, green, and black. But that could be easily changed. You may have fewer or more colors. You can use your brand colors as well to make everything look consistent.

How to use it?

1. Read the documentation on GitHub
2. Go to releases
3. Download latest release package
4. Login to Sitecore Desktop
5. Open Development Tools > Installation Wizard
6. Upload the package that you have downloaded
7. Install it and enjoy FA and MUI icons on your Sitecore instance.

And that is why I love open source. You can grab a free set of icons, process them using free open source tools, host everything on GitHub, automate everything using GitHub Actions and share your results with others. You take something, you give something. Everyone is happy.

And Special thanks to Viet Hoang, who back in 2017 wrote an article about changing Sitecore icons that is still actual in 2022.

Dianoga Docker Asset Image

 This is a copy of my blog post originally posted here to keep all things in one place.

Before reading this article, I do recommend you read about Sitecore Docker asset images. It will make understanding what is going on here much easier. Let's build our first Sitecore Docker Asset image.

Let’s create Dianoga Docker Image Asset for Sitecore.

Dianoga is a good candidate for start. It is well-known community module, which means that what we create will be used by others. It doesn’t have any items, it is easy to build the image. And it has many different configurations. Having the image may be used for integration testing and reproduction of bugs with non-standard configuration.

Each Docker image should have a base image. Let’s define what image will we use as a base. You need to remember that our image will be used only as a container of files. It makes sense to take the smallest image that is possible. It will be mcr.microsoft.com/windows/nanoserver:1809 for Windows images. (There is even a reserved scratch image in Docker, but that is designed for Linux images and it is a separate story)

ARG BASE_IMAGE=mcr.microsoft.com/windows/nanoserver:1809

But as the input to build the image, we will get only Dianoga sources. We need to compile them. And as we selected the base image smallest possible, we don’t have anything there to build C# project. That is why we need one more image: “build image”. It should contain all build tools that we need. For our case, it will be mcr.microsoft.com/dotnet/framework/sdk:4.8

ARG BUILD_IMAGE=mcr.microsoft.com/dotnet/framework/sdk:4.8
FROM ${BUILD_IMAGE} AS build-env

Dianoga could be built in 2 configurations: debug and release. Also, a different .Net version should be used depending on what Sitecore version, where we want to use it. It would be nice to put these values as arguments:

ARG BUILD_CONFIGURATION=
ARG DOTNET_VERSION_ARG=

Now, we are ready to build Dianoga project inside Docker containers.

First of all, we need to register Sitecore Nuget packages source

RUN dotnet nuget add source https://sitecore.myget.org/F/sc-packages/api/v3/index.json

Then copy all project and solution files and restore Nuget packages

COPY *.sln ./
COPY src/Dianoga/Dianoga.csproj ./src/Dianoga/
COPY src/Dianoga.Tests/Dianoga.Tests.csproj ./src/Dianoga.Tests/
RUN dotnet restore

After a successful package restoration, we may copy the whole project and build it

COPY src ./src
RUN dotnet build -c $env:BUILD_CONFIGURATION

After a successful build, we need to copy everything that we need from the “build image” into the “base image”.

RUN mkdir ./src/bin
RUN Copy ./src/Dianoga/bin/$env:BUILD_CONFIGURATION/$env:DOTNET_VERSION_ARG/Dianoga.* ./src/bin/
RUN Copy ./src/Dianoga/bin/$env:BUILD_CONFIGURATION/$env:DOTNET_VERSION_ARG/System.Threading.Tasks.Dataflow.dll ./src/bin/

FROM ${BASE_IMAGE}

# Copy Dianoga dll and pdb (if present)
COPY --from=build-env /src/bin/ ./module/cd/content/bin/
COPY --from=build-env /src/bin/ ./module/cm/content/bin/

# Copy Dianoga Tools
ARG src="/src/Dianoga/Dianoga Tools"
ARG target="./module/cm/content/App_Data/Dianoga Tools"
COPY --from=build-env ${src} ${target}

ARG src="/src/Dianoga/Dianoga Tools"
ARG target="./module/cd/content/App_Data/Dianoga Tools"
COPY --from=build-env ${src} ${target}

# Copy Configs
ARG src="/src/Dianoga/Default Config Files"
ARG target="./module/cm/content/App_Config/Include/Dianoga"
COPY --from=build-env ${src} ${target}

ARG src="/src/Dianoga/Default Config Files"
ARG target="./module/cd/content/App_Config/Include/Dianoga"
COPY --from=build-env ${src} ${target}

Dockerfile is ready and we can build the Dianoga Docker Asset Image

docker build . --build-arg DOTNET_VERSION_ARG=net48 --build-arg BUILD_CONFIGURATION=debug

Now we are ready to use the Sitecore Dianoga Docker image in our projects. It will be described in further articles.

Sitecore Docker Asset Images

 

This is a copy of my post originally placed here to keep all things in one place. 

There are many articles and quite a significant amount of documentation about Sitecore Docker Asset images. And there are discussed the complex things. But I haven’t seen a basic explanation, of what it is and what it is not. Let’s reveal the magic!

An asset image is an image that contains files that you want to use in other images. Website files are included as files. Sitecore items are included as files. Sitecore Solr cores are included as files. Service scripts are included as files. And asset image doesn’t do anything by itself. It is just a set of files.

Actually, you may achieve exactly the same goals by packaging everything to some archive, uploading it somewhere, and using it during the build or your images. But having an “asset image” is much easier and more containers-way to achieve what we need.

And you may build Sitecore Docker Asset Image in different ways. Matters the only one thing: it should contain files that you will need to use in your other images.

Docker Asset Image Structure

Internal Docker asset image structure is a convention. You may follow it, or you can ignore it. You should understand that you may put files inside your Docker image asset in any folders that you like. You can completely ignore conventions, everything still may work for you. But, it is only much better to place files in the same locations that Sitecore uses. It will make your image to be similar to other images. And usage of your image will be intuitive for other developers. They will expect files in some locations and you will justify their expectation.

You put files required on Content Management (CM) required to be on that role to module\cm\content. You put files required on Content Delivery (CD) required to be on that role to module\cd\content. If you have any other roles, you follow the same pattern. If you have any Solr cores, you put them under module\solr. You put any scripts that you want to execute into module\tools. You put Sitecore items in .dacpac format under module\db. And you put Sitecore items in item-as-resources under module\[role]\App_Data\items\[database name]\*.dat

Sitecore Content Items

There are 2 options for how you put items as files into the Sitecore asset image. The first is Data Tier AppliCation Package .dacpac. And the second ”items as resources” format .dat. You don’t need to place your items in 2 formats. You need to select what works better for us.

In theory, you can move your items into the Sitecore images using a different approach: .bacpac, running custom SQL queries, using serialization. etc. But for these approaches, you will need to do additional actions by yourself.

Using Asset Image

Files from your asset image don’t magically are used in other images. For each file(group of files) you need to perform some actions. You need to copy files that are part of your website. You need to copy “items as resources” to the proper location of your website. You need to copy .dacpac files to your MS SQL image and deploy them using DeployDatabases.ps1 script that comes with the Sitecore Tooling image. You need to copy Solr cores to your Solr image.

Conclusion

I hope you get a better understanding of Sitecore Asset Images. It is just a set of files. I hope this thought will make the creation of your own images and other images much more intuitive.