Hosting ASP.NET Core images with Docker over HTTPS

By Rick Anderson

ASP.NET Core uses HTTPS by default. HTTPS relies on certificates for trust, identity, and encryption.

This document explains how to run pre-built container images with HTTPS using the .NET command-line interface (CLI). For instructions on how to run Docker in development with Visual Studio, see Developing ASP.NET Core Applications with Docker over HTTPS.

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

Prerequisites

The current .NET SDK.

Certificates

A certificate from a certificate authority is required for production hosting for a domain. Let's Encrypt is a certificate authority that offers free certificates.

This document uses self-signed development certificates for hosting pre-built images over localhost. The instructions are similar to using production certificates. The certificate generated by dotnet dev-certs is for use with localhost only and should not be used in an environment like Kubernetes. To support HTTPS within a Kubernetes cluster, use the tools provided by Manage TLS Certificates in a Cluster to setup TLS within pods.

Use dotnet dev-certs to create self-signed certificates for development and testing.

For production certs:

• The dotnet dev-certs tool is not required.
• Certificates do not need to be stored in the location used in the instructions. Any location should work, although storing certs within your site directory is not recommended.

The instructions contained in the following section volume mount certificates into containers using Docker's -v command-line option. You could add certificates into container images with a COPY command in a Dockerfile, but it's not recommended. Copying certificates into an image isn't recommended for the following reasons:

• It's difficult to use the same image for testing with developer certificates.
• It's difficult to use the same image for Hosting with production certificates.
• There is significant risk of certificate disclosure.

Running pre-built container images with HTTPS

Use the following instructions for your operating system configuration.

Windows using Linux containers

Generate a certificate and configure the local machine:

.NET CLI

dotnet dev-certs https -ep %USERPROFILE%\.aspnet\https\aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
dotnet dev-certs https --trust

In the preceding commands, replace <CREDENTIAL_PLACEHOLDER> with a password.

Run the container image with ASP.NET Core configured for HTTPS in a command shell:

Console

docker pull mcr.microsoft.com/dotnet/samples:aspnetapp
docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORTS=8001 -e ASPNETCORE_Kestrel__Certificates__Default__Password="<CREDENTIAL_PLACEHOLDER>" -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/aspnetapp.pfx -v %USERPROFILE%\.aspnet\https:/https/ mcr.microsoft.com/dotnet/samples:aspnetapp

In the preceding code, replace <CREDENTIAL_PLACEHOLDER> with the password. The password must match the password used for the certificate.

When using PowerShell, replace %USERPROFILE% with $env:USERPROFILE.

Note: The certificate in this case must be a .pfx file. Utilizing a .crt or .key file with or without the password isn't supported with the sample container. For example, when specifying a .crt file, the container may return error messages such as 'The server mode SSL must use a certificate with the associated private key.'. When using WSL, validate the mount path to ensure that the certificate loads correctly.

macOS or Linux

Generate certificate and configure local machine:

.NET CLI

dotnet dev-certs https -ep ${HOME}/.aspnet/https/aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
dotnet dev-certs https --trust

On Linux, dotnet dev-certs https --trust requires .NET 9 SDK or later. For Linux on .NET 8.0.401 SDK and earlier, see your Linux distribution's documentation for trusting a certificate.

In the preceding commands, replace <CREDENTIAL_PLACEHOLDER> with a password.

Run the container image with ASP.NET Core configured for HTTPS:

Console

docker pull mcr.microsoft.com/dotnet/samples:aspnetapp
docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORTS=8001 -e ASPNETCORE_Kestrel__Certificates__Default__Password="<CREDENTIAL_PLACEHOLDER>" -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/aspnetapp.pfx -v ${HOME}/.aspnet/https:/https/ mcr.microsoft.com/dotnet/samples:aspnetapp

In the preceding code, replace <CREDENTIAL_PLACEHOLDER> with the password. The password must match the password used for the certificate.

Windows using Windows containers

Generate certificate and configure local machine:

.NET CLI

dotnet dev-certs https -ep %USERPROFILE%\.aspnet\https\aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
dotnet dev-certs https --trust

In the preceding commands, replace <CREDENTIAL_PLACEHOLDER> with a password. When using PowerShell, replace %USERPROFILE% with $env:USERPROFILE.

Run the container image with ASP.NET Core configured for HTTPS:

Console

docker pull mcr.microsoft.com/dotnet/samples:aspnetapp
docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORTS=8001 -e ASPNETCORE_Kestrel__Certificates__Default__Password="<CREDENTIAL_PLACEHOLDER>" -e ASPNETCORE_Kestrel__Certificates__Default__Path=c:\https\aspnetapp.pfx -v %USERPROFILE%\.aspnet\https:C:\https\ --user ContainerAdministrator mcr.microsoft.com/dotnet/samples:aspnetapp

NOTE: <CREDENTIAL_PLACEHOLDER> is a placeholder for the Kestrel certificates default password.

The password must match the password used for the certificate. When using PowerShell, replace %USERPROFILE% with $env:USERPROFILE.

Developing ASP.NET Core Applications with Docker over HTTPS

See Developing ASP.NET Core Applications with Docker over HTTPS for information and samples on how to develop ASP.NET Core applications with HTTPS in Docker containers.

See also

• Developing ASP.NET Core Applications with Docker over HTTPS
• dotnet dev-certs