Building .NET Core container images using S2I

Building .NET Core container images using S2I

Red Hat OpenShift implements .NET Core support via a source-to-image (S2I) builder. In this article, we’ll take a closer look at how you can use that builder directly. Using S2I, you can build .NET Core application images without having to write custom build scripts or Dockerfiles. This can be useful on your development machine or as part of a CI/CD pipeline.

Containers for your builds

Container images provide an efficient mechanism to deploy self-contained applications in a portable way across clouds and OS distributions.

By building the application images themselves using a builder image, the application images can be built in a portable, reproducible way.

S2I is a toolkit for building reproducible application images. S2I uses builder images to produce application images from source code or pre-compiled applications.

application source/        +-------+
prebuilt application  +--> |  s2i  | +-->  application image
                        builder image

On Fedora and Red Hat Enterprise Linux (RHEL), you can obtain S2I by installing the source-to-image package (yum install source-to-image). If you are using another OS, including Windows and macOS, you can download S2I from You’ll also need to install docker and git, which are used by s2i.

.NET Core builder images

A builder image is available for each .NET Core version. These images are built from the Dockerfiles at

For .NET Core 2.1, these images are available as follows:

OS base Image Type Image Name
RHEL 7 Runtime
CentOS 7 Runtime
CentOS 7 SDK

If you are looking for a different .NET Core version, you can check the Red Hat Container Catalog or the CentOS Container Registry.

To use the RHEL 7 images, you need a Red Hat subscription. For development, you can use the free development subscription. Use the docker login command to configure your credentials.

Building images

The sections below describe three ways you can build your images.

Building an application image from a git repository

As our first, example, we’ll build an application image named mywebapp for the ASP.NET Core application at

$ s2i build mywebapp -r dotnetcore-2.1 -e DOTNET_STARTUP_PROJECT=app -p always

When we run this command, we’ll see s2i check out the sources and build the .NET Core application image. When the command finishes, we can run the newly created image:

$ docker run --rm -p 8080:8080 mywebapp

Let’s look at the parameters we’ve passed to the s2i command:

Parameter Description S2I builder image
https://…/s2i-dotnetcore-ex The git repository
-r dotnetcore-2.1 Branch in the repository
-e DOTNET_STARTUP_PROJECT=app Folder in the repository that contains the application csproj file
-p always Always pull the latest builder image

The -e DOTNET_STARTUP_PROJECT is an environment variable passed to the S2I builder. The builder supports a number of environment variables that allow you to customize its behavior. See the environment variables documentation for a complete list.

Building an application image from local sources

The source parameter for the s2i command can also refer to a local folder that contains the source code. In the following example, we clone the repository locally and check out the appropriate branch into the s2i-dotnetcore-ex folder. Then we build from that local folder.

$ git clone -b dotnetcore-2.1
$ s2i build s2i-dotnetcore-ex mywebapp -r dotnetcore-2.1 -e DOTNET_STARTUP_PROJECT=app -p always

We can run the image using the same docker run command as before.

Building an application image from a pre-built application

The .NET Core builder can also be used to build an application image from a pre-built application.

To explore this, we first publish the s2i-dotnetcore-ex application. To do that, you need to install a .NET SDK on your system (RHEL7/CentOS7, Fedora, other).

$ git clone -b dotnetcore-2.1
$ cd s2i-dotnetcore-ex/app
$ dotnet publish -c Release /p:MicrosoftNETPlatformLibrary=Microsoft.NETCore.App

We are specifying the MicrosoftNETPlatformLibrary parameter to make the published application contain the ASP.NET Core shared framework assemblies. This is needed because the images don’t contain the shared framework.

To create the image, we pass the publish folder as the source parameter of the s2i build command. We can use the SDK builder images like before, but since the application is already built, we can use the smaller runtime image instead.

$ s2i build bin/Release/netcoreapp2.1/publish mywebapp -p always


In this article, you’ve learned how to create .NET Core application images using s2i. These images can be built directly from a git repository, local sources, or a pre-built application.