Skip to content

Latest commit

 

History

History
165 lines (111 loc) · 7.62 KB

README.md

File metadata and controls

165 lines (111 loc) · 7.62 KB
Raw

ASP.NET Core Docker Sample

This sample demonstrates how to build container images for ASP.NET Core web apps. See .NET Docker Samples for more samples.

Note

.NET 8+ container images use port 8080, by default. Previous .NET versions used port 80. The instructions for the sample assume the use of port 8080.

Run the sample image

You can start by launching a sample from our container registry and access it in your web browser at http://localhost:8000.

docker run --rm -it -p 8000:8080 -e ASPNETCORE_HTTP_PORTS=8080 mcr.microsoft.com/dotnet/samples:aspnetapp

You should see the following console output as the application starts:

> docker run --rm -it -p 8000:8080 -e ASPNETCORE_HTTP_PORTS=8080 aspnetapp
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://[::]:8080
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.

After the application starts, navigate to http://localhost:8000 in your web browser. You can also view the ASP.NET Core site running in the container from another machine with a local IP address such as http://192.168.1.18:8000.

You can also reach the app's endpoint from the command line:

$ curl http://localhost:8000/Environment
{"runtimeVersion":".NET 9.0.0-rc.1.24431.7","osVersion":"Debian GNU/Linux 12 (bookworm)","osArchitecture":"X64","user":"app","processorCount":16,"totalAvailableMemoryBytes":33632370688,"memoryLimit":9223372036854771712,"memoryUsage":35770368,"hostName":"834f365bfcfa"}

Note

ASP.NET Core apps (in official images) listen to port 8080 by default, starting with .NET 8. The -p argument in these examples maps host port 8000 to container port 8080 (host:container mapping). The container will not be accessible without this mapping. ASP.NET Core can be configured to listen on a different or additional port.

You can see the app running via docker ps. The sample includes a health check endpoint at /healthz, indicated in the "STATUS" column.

$ docker ps
CONTAINER ID   IMAGE                                        COMMAND         CREATED          STATUS                    PORTS                  NAMES
d79edc6bfcb6   mcr.microsoft.com/dotnet/samples:aspnetapp   "./aspnetapp"   35 seconds ago   Up 34 seconds (healthy)   0.0.0.0:8080->8080/tcp   nice_curran

Change port

You can change the port ASP.NET Core uses with one of the following environment variables. However, the default port 8080 is recommended.

Note that ports 1 to 1023 are restricted to root users only, and will not work when running as the non-root root user provided in .NET images.

The following evnironment variables will change the port to port 80.

  • ASPNETCORE_HTTP_PORTS=80
  • ASPNETCORE_URLS=http://+:80

ASPNETCORE_URLS overrides ASPNETCORE_HTTP_PORTS if set. The ASPNETCORE_HTTP_PORTS envrionment variable is used in the ASP.NET Core images to set the default port.

Enable HTTPS

To host the sample image with HTTPS, follow the instructions for Running pre-built Container Images with HTTPS. For a more in-depth guide to developing ASP.NET Core apps with HTTPS, check out Developing ASP.NET Core Applications with Docker over HTTPS.

Build the sample image

You can build the sample image using the following command (cloninig the repo isn't necessary):

docker build --pull -t aspnetapp 'https://github.com/dotnet/dotnet-docker.git#:samples/aspnetapp'

If you have cloned the repo, you can build the image using your local copy:

cd samples/aspnetapp
docker build --pull -t aspnetapp .

Add the argument -f <Dockerfile> to build the sample in a different configuration. For example, build an Ubuntu Chiseled image using Dockerfile.chiseled:

docker build --pull -t dotnetapp -f Dockerfile.chiseled 'https://github.com/dotnet/dotnet-docker.git#:samples/dotnetapp'

You can run your local image the same way as described in Run the sample image:

docker run --rm -it -p 8000:8080 -e ASPNETCORE_HTTP_PORTS=8080 aspnetapp

Multi-platform build

.NET sample Dockerfiles support multi-platform builds via cross-compilation. First, check out the Docker multi-platform build prerequisites

Once you have the prerequisites set up, you can build the ASP.NET app sample for a specific architecture:

# From an amd64 machine:
docker buildx build --platform linux/arm64 -t aspnetapp .

# From an arm64 machine:
docker buildx build --platform linux/amd64 -t aspnetapp .

You can also build both platforms at once:

docker buildx build --platform linux/amd64,linux/arm64 -t aspnetapp .

This works thanks to .NET's support for cross-compilation. The build runs on your build machine's architecture and outputs IL for the target architecture. The app is then copied to the final stage without running any commands on the target image - there's no emulation involved.

Note

.NET does not support running under QEMU emulation. See .NET and QEMU for more information.

Build image with the SDK

The easiest way to build images is with the SDK.

dotnet publish /p:PublishProfile=DefaultContainer

That command can be further customized to use a different base image and publish to a container registry. You must first use docker login to login to the registry.

dotnet publish /p:PublishProfile=DefaultContainer /p:ContainerBaseImage=mcr.microsoft.com/dotnet/aspnet:9.0-noble-chiseled /p:ContainerRegistry=docker.io /p:ContainerRepository=youraccount/aspnetapp

Supported Linux distros

The .NET Team publishes images for multiple distros.

Samples are provided for:

Supported Windows versions

The .NET Team publishes images for multiple Windows versions. You must have Windows containers enabled to use these images.

Samples are provided for

Windows variants of the sample can be pulled via one the following registry addresses:

  • mcr.microsoft.com/dotnet/samples:aspnetapp-nanoserver-1809
  • mcr.microsoft.com/dotnet/samples:aspnetapp-nanoserver-ltsc2022