Deploying SKS Blazor migrated app to Azure Container Instances

This document provides a detailed guide for deploying SKS Blazor migrated applications using Azure Container Instances (ACI). It covers the necessary steps for setting up a local Docker environment, building container images, defining base images, and pushing images to container registries, specifically GitHub Container Registry (GHCR) and Azure Container Registry (ACR). Additionally, it includes instructions for creating and running containers in Azure, along with important considerations for ensuring successful deployment, particularly regarding the choice of base images and runtime dependencies for Windows-based applications.

Installing Docker local environment.

To first build a Docker image with the SKS application is important to install and configure a local Docker runtime environment.

1. Add containers and hyper-v features on windows:

   1. Open Windows Features:

      1. Press Win + R, type optional features, and press Enter.

      2. Or, search for "Turn Windows features on or off" in the Start menu and open it.

   2. Enable Containers:

      1. In the Windows Features dialog, scroll down and check the box for Containers.

   3. Enable Hyper-V:

      1. In the same list, find and check Hyper-V (expand it and ensure both "Hyper-V Management Tools" and "Hyper-V Platform" are checked).

   4. Apply and Restart:

      1. Click OK.

      2. Windows will search for required files and apply changes.

      3. Restart your computer when prompted.

   
2. Download Docker Desktop from: https://www.docker.com/products/docker-desktop

3. Run the installer (Docker Desktop Installer.exe)

4. During installation:

   1. Enable "Install required Windows components for WSL 2"

   2. Enable "Use Windows containers instead of Linux containers"

5. Click "Ok" to install

6. Wait for installation to complete

7. Restart your computer

8. Run Docker desktop application.

9. Right click on Docker tray icon and select switch to windows containers (Since the images used to build the WebMap Blazor images are Windows OS based it’s necessary to work with Windows containers).

   
10. In settings verify that desktop-windows is running

    

How to build a Windows image with SKS app.

For this exercise the SKS application was used. You can find the application along with the Dockerfile in the repo: https://collaboration.artinsoft.com/tfs/Product/Product/_git/BlazorDemos

The branch with the changes and the Dockerfile is: support/DockerContainerWindowsSKS.

Before creating the Dockerfile it’s important to define the base image used to create the container.

Defining a base image

There a are 3 different types of base image the election should be based on the requirements:

• Linux Images

  • Base OS: Linux (usually Debian or Alpine).

  • Image Example: mcr.microsoft.com/dotnet/aspnet:9.0
  • Size: Smallest.

  • Performance: Fast startup, low resource usage.

  • Compatibility:

    • Runs on Linux hosts (including most cloud/container platforms).

    • Cannot run Windows-specific workloads (e.g., Windows Forms, WPF, COM).

  • Best for:

    • Web apps (Blazor, ASP.NET Core, APIs).

    • Cloud-native deployments (Azure Container Apps, Kubernetes, Docker Hub).

• Nano Server Images

  • Base OS: Windows Nano Server (minimal Windows kernel).

  • Image Example: mcr.microsoft.com/dotnet/aspnet:9.0-nanoserver-1809
  • Size: Smaller than Server Core, larger than Linux.

  • Performance: Good, but not as fast or small as Linux.

  • Compatibility:

    • Runs only on Windows hosts (Windows containers).

  • No support for full .NET Framework, Windows Forms, WPF, or GDI+.

  • Only supports .NET Core/.NET 5+ console and web apps.

  • Best for:

    • .NET Core web apps that require Windows but not full Windows APIs.

• Server Core Images

  • Base OS: Windows Server Core (more complete Windows environment).

  • Image Example: mcr.microsoft.com/dotnet/aspnet:9.0-windowsservercore-ltsc2022
  • Size: Largest.

  • Performance: Slower startup, higher resource usage.

  • Compatibility:

    • Runs only on Windows hosts (Windows containers).

    • Supports full .NET Framework, Windows Forms, WPF, GDI+, COM, etc.

  • Best for:

    • Legacy .NET Framework apps.

    • Apps needing full Windows APIs (desktop, GUI, COM, etc.).

Since most migrations come from windows architecture usually they are tightly coupled to windows environments, also WebMap Blazor code is compiled and designed to target Windows Desktop runtime that’s why the selected base image for the SKS POC is Server Core Images.

Once the based image is defined, a Dockerfile should be created to perform the image build. The Dockerfile used for this exercise can be found in the branch mentioned above.

After creating the Dockerfile, open a command line window pointing to the same folder where the dockerfile is and run the build command to generate an image.

docker build --no-cache -t <desired-image-name>:<version>

You should have the image created in the docker desktop UI.

Then you can run the image locally as a container using the docker run command.

docker run -p 8080:8080 -p 8081:8081 --name <desired-container-name> <image-name-used-build-command>

There should be a new container named sks_blazor_container created

Since one of the ports exposed when running the container is 8080. The app will listen in http://localhost:8080

Next step is to push the image to a Container registry so it can be run from the Azure Container instances app. But first you need to define which container registry to use.

Define container registry

These are some of the most common container registry options:

• Git Hub Container Registry

  • Free for public repositories and generous free tier for private images.

  • No extra Azure cost (unlike ACR, which may incur charges after the free tier).

  • Easy integration with GitHub Actions for CI/CD.

  • Widely supported by Azure Container Apps and Azure Web App for Containers.

  • No vendor lock-in—you can use the same registry for other platforms.

• Docker Hub

  • Free for public images (rate limits apply).

  • Simple to use and supported everywhere.

  • Private repositories are limited to the free tier.

• Azure Container Registry

  • If you need enterprise features (private networking, managed identities, geo-replication).

  • If you want tight Azure integration and are comfortable with potential costs.

  • https://azure.microsoft.com/en-us/pricing/details/container-registry/
• Using GHCR to push the image to the remote repository

  • Go to GitHub.com → Settings → Developer Settings → Personal Access Tokens → Tokens (classic).

  • Click "Generate new token (classic)"

  • Select the following scopes:

    • read:packages

    • write:packages

    • delete:packages (if you need to delete containers)

  • Copy the generated token

  • Login the local docker environment to GHCR:

    • echo <GENERATED-TOKEN>| docker login ghcr.io -u <YOUR_GITHUB_USERNAME> --password-stdin

  • Tag the image in GHCR:

    • docker tag <image-name>:<version> ghcr.io/<YOUR_GITHUB_USERNAME>/<image-name>:<version>

  • Push the image

    • docker push ghcr.io/<YOUR_GITHUB_USERNAME>/<image-name>:<version>

• Using ACR to push the image to the remote repository

  • Open the Azure Portal

    • Go to https://portal.azure.com and sign in with your Azure account.

  • Open Azure Cloud Shell

    • In the top-right corner of the portal, click the Cloud Shell icon (it looks like a terminal or command prompt).

    • When prompted, select Bash as your shell environment.

    • If this is your first time, you may be asked to create a storage account—follow the prompts to set it up.

  • Create a resource group.

  az group create --name <resource-group-name> --location <location>

  • Create ACR

  az acr create --resource-group <resource-group-name> --name <acr-name> --sku Basic

  • Go back to you local environment, open a cmd and login to azure.