David Claeys

Since Microsoft started to transition .NET they also started offering Docker images to package your applications. To be more specific at Docker Hub Microsoft lists their images and intended purposes.

I wanted to take myself up for a challenge and try to package a .NET API project into a Docker container. The purpose of this article isn't to tell you how to build an API project since this topic is broadly covered on the web. I want to tell you one of the roadblocks I ran against and how I managed to solve it.

If you want to get started the following tutorials could be useful : – Containerize a .NET app – Step By Step Dockerizing .NET Core API – Smaller Docker Images for ASP.NET Core Apps

Slim Docker images

It's best practice to make the Docker images you publish as slim as possible. The main benefit of doing this is that consuming your image will take less space on your host if you do so. There are many ways to make your image slimmer but one of the most effective ways is picking the right base image with the right tag.

For example if we look at the tags for the ASP.NET Core Runtime we see among others the following sections : Linux amd64, Nano Server 2022 amd64 , Windows Server Core 2022 amd64 and so on. If you want to make your Docker image multi platform compatible (one of the main benefits of .NET and Docker) you should automatically discard the tags representing a Windows environment. First of all it's probably not the most lightweight base OS to build your image but more importantly Windows Docker containers can't run on any system that isn't Windows based.

This limits our choice to Linux based images, but even there we have lots of choice. By example at this moment in time we can choose among others between 8.0-bookworm-slim (Debian), 8.0-alpine-amd64 (Alpine) and 8.0-jammy (Ubuntu). Microsoft marks the Debian variant with the latest tag since this distribution is pretty lightweight and also is quite widespread. However if we want to take things up a notch we should go for alpine since this is a lightweight no frills distribution.

The roadblock

When publishing a .NET API it is served by Kestrel. When making an API it is recommended to use HTTPS for security reasons. Furthermore when making a production build it is even required.

When reading the documentation we see we should use the following commands : – dotnet dev-certs https -ep $env:USERPROFILE\.aspnet\https\aspnetapp.pfx -p crypticpassword – dotnet dev-certs https --trust

This is simple enough, what's the problem then? Well the second of those command is only supported on Windows based systems.

The solution

After a lot of trial and error I came to the following solution :

# Password for the certificate
ARG CERT_PASSWORD_ARG=SUPERSECRET
# this image contains the entire .NET SDK and is ideal for creation the build
FROM mcr.microsoft.com/dotnet/sdk:8.0-alpine-amd64 AS build-env
ARG CERT_PASSWORD_ARG
ENV CERT_PASSWORD=$CERT_PASSWORD_ARG
WORKDIR /App
COPY . ./
# Restore dependencies for your application
RUN dotnet restore
# Build your application
RUN dotnet publish test.csproj --no-restore --self-contained false -c Release -o out /p:UseAppHost=false 
# Make the directory for certificate export
RUN mkdir /config
# Generate certificate with specified password
RUN dotnet dev-certs https --export-path /config/aspnetapp.pem --password "$CERT_PASSWORD" --format PEM

# this image contains the ASP.NET Core and .NET runtimes and libraries 
FROM mcr.microsoft.com/dotnet/aspnet:8.0-alpine-amd64
ARG CERT_PASSWORD_ARG
ENV CERT_PASSWORD=$CERT_PASSWORD_ARG
WORKDIR /App
# add dependency in system to setup certificates
RUN apk add ca-certificates 
# create directory to store certificate config
RUN mkdir /config 
# create necessary config directory
RUN mkdir -p /usr/local/share/ca-certificates/
# copy compiled files to runtime
COPY --from=build-env /App/out . 
# copy generated certificate
COPY --from=build-env /config /config
# Disable Big Brother
ENV DOTNET_CLI_TELEMETRY_OPTOUT=1
# Set the environment to production
ENV ASPNETCORE_ENVIRONMENT=Production
# Set the urls where Kestrel is going to listen
ENV ASPNETCORE_URLS=http://+:80;https://+:443
# location of the certificate file
ENV ASPNETCORE_Kestrel__Certificates__Default__Path=/usr/local/share/ca-certificates/aspnetapp.crt
# location of the certificate key
ENV ASPNETCORE_Kestrel__Certificates__Default__KeyPath=/usr/local/share/ca-certificates/aspnetapp.key
# specify password in order to open certificate key
ENV ASPNETCORE_Kestrel__Certificates__Default__Password=$CERT_PASSWORD
# copy certificate files to config directory
RUN cp /config/aspnetapp.pem $ASPNETCORE_Kestrel__Certificates__Default__Path 
RUN cp /config/aspnetapp.key $ASPNETCORE_Kestrel__Certificates__Default__KeyPath
# set file permisions for certificate file
RUN chmod 755 $ASPNETCORE_Kestrel__Certificates__Default__Path 
RUN chmod +x $ASPNETCORE_Kestrel__Certificates__Default__Path
# change file ownership for certificate file
# add generated certificate to trusted certificate list on the system
RUN cat $ASPNETCORE_Kestrel__Certificates__Default__Path >> /etc/ssl/certs/ca-certificates.crt
# set file permissions for key file
RUN chmod 755 $ASPNETCORE_Kestrel__Certificates__Default__KeyPath
RUN chmod +x $ASPNETCORE_Kestrel__Certificates__Default__KeyPath
# change file ownership for key file
RUN update-ca-certificates

ENTRYPOINT ["dotnet", "test.dll"]
EXPOSE 80 
EXPOSE 443

The above file is for demonstration purposes, in practice you shouldn't use consecutive RUN instructions, you should update system dependencies and perform some cleanup. I've excluded those steps in order to focus on this article's subject.

Deep dive

The first step I want to focus on is the following :

RUN dotnet dev-certs https --export-path /config/aspnetapp.pem --password "$CERT_PASSWORD" --format PEM

By default the command to generate certificates generates a certificate in the PFX format. While it is theoretically possible to use that format on Linux systems it's an overly complicated mess. So in order to make things easier we tell the generator tool to use the PEM format. This way of using certificates is much better supported in Linux and much easier to setup. This command will generate two files : a certificate file and a key file. The key file is encrypted with the password that is specified in CERT_PASSWORD_ARG.

The next important part is :

# location of the certificate file
ENV ASPNETCORE_Kestrel__Certificates__Default__Path=/usr/local/share/ca-certificates/aspnetapp.crt
# location of the certificate key
ENV ASPNETCORE_Kestrel__Certificates__Default__KeyPath=/usr/local/share/ca-certificates/aspnetapp.key
# specify password in order to open certificate key
ENV ASPNETCORE_Kestrel__Certificates__Default__Password=$CERT_PASSWORD

These environment variables tell the Kestrel server where it needs to look for the certificate files. The ASPNETCORE_Kestrel__Certificates__Default__Password is key, since if it is not specified or correctly populated Kestrel won't be able to use the certificate and will crash. This variable isn't anywhere to be found on Microsoft's documentation and I only was able to find it looking at the .NET source code published on GitHub.

The next important part is

RUN cat $ASPNETCORE_Kestrel__Certificates__Default__Path >> /etc/ssl/certs/ca-certificates.crt
RUN update-ca-certificates

This tells the system to trust the certificate we generated. If we wouldn't do that Kestrel also wouldn't be able to run and would crash.

Security implications

Maybe the elephant in the room is that in this setup we are using a self signed certificate in order to serve our application in a container. Many might be eager to discard this whole setup for this reason. But before doing that hear me out.

To start with, it's bad practice to hardcode the certificate you'll deploy in production environments in code. So in fact your Docker image should always use a development certificate. Yes, this example also contains a hardcode password at the beginning but this shouldn't be an issue.

In theory we could use the ASPNETCORE_Kestrel__Certificates__Default__Path, ASPNETCORE_Kestrel__Certificates__Default__KeyPath and ASPNETCORE_Kestrel__Certificates__Default__Password environment variables in order to setup our production certificates at deployment. This would allow us to run the image in a container while developing and use a securely stored certificated at deployment. However this solution is discouraged since Microsoft doesn't recommend directly exposing the Kestrel server in Production environments.

This leads to what in my opinion is the preferable solution : using a proxy. You can setup IIS, Nginx, Apache, Traefik and so on, with the certificate you want to use. Clients using the deployed application will have a secure connection and you don't need to deal with the complexities of setting up a “real” certificate at the image level.

Using Docker is amazing, and being able to use it with .NET even more. If you stumbled on the same roadblock I hope this article proved useful.