dotnet-docker-samples/dotnetapp-selfcontained

.NET Core self-contained application Docker Production Sample

This .NET Core Docker sample demonstrates a best practice pattern for building Docker images for self-contained .NET Core applications. This is the type of image you would want to use if you want the smallest possible container in production and do not see a benefit from sharing .NET images between containers (you would still potentially share lower Docker layers). The sample works with both Linux and Windows containers.

This sample Dockerfile for Linux creates an .NET Core application image based off the .NET Core Runtime Dependencies Docker image, which is based on Debian 9 (Stretch) base image.

This sample Dockerfile for Windows Nanoserver creates a .NET Core application image based off the Windows Nanoserver base image.

The sample uses the Docker multi-stage build feature for Linux and Windows to build the sample in a container based on the larger .NET Core SDK Docker image and then copies the final build result into a smaller Docker image based on the appropriate image mentioned above (based whether you are using Windows or Linux containers).

This sample requires Docker 17.06 or later of the Docker client. You need the latest Windows 10 or Windows Server 2016 to use Windows containers. The instructions assume you have the Git client installed.

Getting the sample

The easiest way to get the sample is by cloning the samples repository with git, using the following instructions.

git clone https://github.com/dotnet/dotnet-docker-samples/

You can also download the repository as a zip.

Producing small applications with the .NET Linker

The sample uses an experimental linker for removing code that your final application does not need. The linker helps to produce Docker images that are significantly smaller. The linker is not required and can be removed from the sample or disabled on the commandline if you do not want to use it.

Build and run the sample with Docker for Linux containers

You can build and run the sample in Docker using Linux containers using the following commands. The instructions assume that you are in the root of the repository.

cd dotnetapp-selfcontained
docker build -t dotnetapp-selfcontained .
docker run --rm dotnetapp-selfcontained Hello .NET Core from Docker

Build and run the sample with Docker for Windows containers

You can build and run the sample in Docker using Windows containers using the following commands. The instructions assume that you are in the root of the repository.

cd dotnetapp-selfcontained
docker build -t dotnetapp-selfcontained -f Dockerfile.nano .
docker run dotnetapp-selfcontained Hello .NET Core from Docker

Build on Windows or macOS and run the sample with Docker on Linux + ARM32 (Raspberry Pi)

The goal of this section is to create and run a Docker .NET Core runtime-based image on a Raspberry Pi running Linux. The .NET Core SDK does not run on the Linux + ARM32 configuration. As a result, the instructions used for X64 don't work. There are multiple ways to get around this limitation, primarily:

• Build final ARM32 image on Windows, push image to a Docker registry and then pull and run from the ARM32 device, or
• Build app on X64 and copy via scp (or pscp) to ARM32 device and then build and run a Docker runtime image on the ARM32 device

The first option is only supported on Windows and macOS. Linux users must use the second option. For simplicity, the first option is provided below.

The instructions assume that you are in the root of the repository.

Type the following commands in Docker "Linux mode" on Windows. The instructions assume that you have a personal Docker user account called mydockername. You will need to change that to your actual docker account name, such as richlander in the case of the author of this sample. You will also need to create a Docker repo called dotnetapp-selfcontained-arm32. You can create new repos in the Docker web UI.

You need to be signed into the Docker client to docker push to Docker Hub.

cd dotnetapp-selfcontained
docker build -t mydockername/dotnetapp-selfcontained-arm32 -f Dockerfile.arm32 .
docker push mydockername/dotnetapp-selfcontained-arm32

Switch to your Raspberry Pi, with Linux and Docker installed. Type the following command.

docker run --rm mydockername/dotnetapp-selfcontained-arm32 Hello .NET Core from Docker

Build, Run and Publish the sample locally

You can build and run the sample locally with the .NET Core 2.0 SDK using the following instructions. The instructions assume that you are in the root of the repository.

cd dotnetapp-selfcontained
dotnet run

Publishing on Windows

You can publish an application locally that is ready to deploy to production using the following commands.

dotnet publish -c release -r win-x64 -o selfcontained-win-x64
selfcontained-win-x64\dotnetapp.exe

Note: The -c release argument builds the application in release mode (the default is debug mode). See the dotnet run reference for more information on commandline parameters.

Publishing on Linux

You can publish an application locally that is ready to deploy to production using the following commands.

dotnet publish -c release -r linux-x64 -o selfcontained-linux-x64
./selfcontained-linux-x64/dotnetapp

Note: The -r argument specifies which runtime target the application should be built and published for. See the dotnet run reference for more information on commandline parameters.

Note: You can publish for other architectures with .NET Core. For example, you can publish for linux-x64 on Windows or macOS. You can use the linux-arm runtime ID you are targeting the Raspberry Pi on Linux, for example.

Publishing on macOS

You can publish an application locally that is ready to deploy to production using the following commands.

dotnet publish -c release -r osx-x64 -o selfcontained-osx-x64
./selfcontained-osx-x64/dotnetapp

Docker Images used in this sample

The following Docker images are used in this sample

• microsoft/dotnet:2.0-sdk
• microsoft/dotnet:2.0-runtime-deps
• microsoft/nanoserver

Related Resources

• Self-contained .NET Core applications
• ASP.NET Core Production Docker sample
• .NET Core Production Docker sample
• .NET Core Docker samples
• .NET Framework Docker samples