README.md

.NET Core Docker Sample

This sample demonstrates how to use .NET Core and Docker together. It builds multiple projects and executes unit tests in a container. The sample works with both Linux and Windows containers and can also be used without Docker.

The sample builds the application in a container based on the larger .NET Core SDK Docker image. It builds and tests the application and then copies the final build result into a Docker image based on the smaller .NET Core Docker Runtime image. It uses Docker multi-stage build and multi-arch tags.

This sample requires Docker 17.06 or later of the Docker client.

Try a pre-built .NET Core Docker Image

You can quickly run a container with a pre-built .NET Core Docker image, based on this sample.

Type the following Docker command:

docker run --rm microsoft/dotnet-samples

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/

You can also download the repository as a zip.

Build and run the sample with Docker

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

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

The commands above run unit tests as part docker build. You can also run .NET unit tests as part of docker run. The following instructions provide you with the simplest way of doing that.

docker build --target testrunner -t dotnetapp:test .
docker run --rm -it dotnetapp:test

You can mount a volume while running the image in order to save the test results to your local disk. The instructions to do that are provided in Running Unit Tests with Docker

Multiple variations of this sample have been provided, as follows. Some of these example Dockerfiles are demonstrated later. Specify an alternate Dockerfile via the -f argument.

• Multi-arch sample with build and unit testing
• Multi-arch sample with build and unit testing, using a preview version of .NET Core
• Multi-arch basic sample
• Multi-arch basic sample, using a preview version of .NET Core
• Alpine x64 sample with build and unit testing
• Alpine x64 sample, with Globalization enabled
• Nano Server self-contained x64 sample with build and unit testing
• Debian self-contained x64 sample with build and unit testing
• Debian self-contained ARM32 sample with build and unit testing

Build and run the sample for Alpine with Docker

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

cd samples
cd dotnetapp
docker build --pull -t dotnetapp:alpine -f Dockerfile.alpine-x64 .
docker run --rm -it dotnetapp:alpine Hello .NET Core from Alpine

Globalization is disabled by default with Alpine images in order to produce smaller images. You can re-enable globalization if your application relies on it. Dockerfile.alpine-x64-globalization enables globalization for Alpine images, but produces larger images.

Related: .NET Core Alpine Docker Image announcement

Build and run the sample for Ubuntu 18.04 with Docker

You can also build for Ubuntu 18.04, with a bionic tag. The bionic tags are documented at microsoft/dotnet. You would switch to the following tags:

• SDK: 2.1-sdk-bionic
• Runtime:-2.1-runtime-bionic

Build and run the sample for Linux ARM32 with Docker

You can build and run the sample for ARM32 and Raspberry Pi with Build .NET Core Applications for Raspberry Pi with Docker instructions.

Build and run the sample for Linux ARM64 with Docker

• .NET Core ARM64 Docker Status

Build .NET Core Self-Contained Applications with Docker

You can build Build .NET Core Self-Contained Applications with Docker.

Develop .NET Core Applications in a container

You can develop applications without a .NET Core installation on your machine with the Develop .NET Core applications in a container instructions. These instructions are also useful if your development and production environments do not match.

Run Docker Image on Another Device

You can push the image to a container registry so that you can pull and run it on another device. Straightforward instructions are provided for pushing to both Azure Container Registry and DockerHub.

• Push Docker Images to Azure Container Registry
• Push Docker Images to DockerHub

Build and run 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 samples
cd dotnetapp
dotnet run Hello .NET Core

You can produce an application that is ready to deploy to production using the following command.

dotnet publish -c release -o out

You can run the published application using the following command:

cd out
dotnet dotnetapp.dll

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

.NET Resources

More Samples

• .NET Core Docker Samples
• .NET Framework Docker Samples

Docs and More Information:

• .NET Docs
• ASP.NET Docs
• dotnet/core for starting with .NET Core on GitHub.
• dotnet/announcements for .NET announcements.

Related Repositories

.NET Core Docker Hub repos:

• microsoft/aspnetcore for ASP.NET Core images.
• microsoft/dotnet for .NET Core images.
• microsoft/dotnet-nightly for .NET Core preview images.
• microsoft/dotnet-samples for .NET Core sample images.

.NET Framework Docker Hub repos:

• microsoft/aspnet for ASP.NET Web Forms and MVC images.
• microsoft/dotnet-framework for .NET Framework images.
• microsoft/dotnet-framework-samples for .NET Framework and ASP.NET sample images.