--- title: Hosting ASP.NET Core Images with Docker over HTTPS author: rick-anderson description: Learn how to host ASP.NET Core Images with Docker over HTTPS ms.author: wpickett ms.custom: mvc ms.date: 09/07/2024 uid: security/docker-https --- # Hosting ASP.NET Core images with Docker over HTTPS :::moniker range=">= aspnetcore-8.0" By [Rick Anderson](https://twitter.com/RickAndMSFT) ASP.NET Core uses [HTTPS by default](~/security/enforcing-ssl.md). [HTTPS](https://en.wikipedia.org/wiki/HTTPS) relies on [certificates](https://en.wikipedia.org/wiki/Public_key_certificate) for trust, identity, and encryption. This document explains how to run pre-built container images with HTTPS using the [.NET command-line interface (CLI)](/dotnet/core/tools/). For instructions on how to run Docker in development with Visual Studio, see [Developing ASP.NET Core Applications with Docker over HTTPS](https://github.com/dotnet/dotnet-docker/blob/main/samples/run-aspnetcore-https-development.md). This sample requires [Docker 17.06](https://docs.docker.com/release-notes/docker-ce) or later of the [Docker client](https://www.docker.com/products/docker). ## Prerequisites The current [.NET SDK](https://dotnet.microsoft.com/download). ## Certificates A certificate from a [certificate authority](https://wikipedia.org/wiki/Certificate_authority) is required for [production hosting](https://blogs.msdn.microsoft.com/webdev/2017/11/29/configuring-https-in-asp-net-core-across-different-platforms/) for a domain. [:::no-loc text="Let's Encrypt":::](https://letsencrypt.org/) is a certificate authority that offers free certificates. This document uses [self-signed development certificates](https://en.wikipedia.org/wiki/Self-signed_certificate) 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](https://kubernetes.io/docs/tasks/tls/managing-tls-in-a-cluster/) to setup TLS within pods. Use [`dotnet dev-certs`](/dotnet/core/tools/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: ```dotnetcli dotnet dev-certs https -ep %USERPROFILE%\.aspnet\https\aspnetapp.pfx -p dotnet dev-certs https --trust ``` In the preceding commands, replace `` 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="" -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 `` with the password. The password must match the password used for the certificate. When using [PowerShell](/powershell/scripting/overview), 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](/windows/wsl/about), validate the mount path to ensure that the certificate loads correctly. ### macOS or Linux Generate certificate and configure local machine: ```dotnetcli dotnet dev-certs https -ep ${HOME}/.aspnet/https/aspnetapp.pfx -p 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 `` 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="" -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 `` with the password. The password must match the password used for the certificate. ### Windows using Windows containers Generate certificate and configure local machine: ```dotnetcli dotnet dev-certs https -ep %USERPROFILE%\.aspnet\https\aspnetapp.pfx -p dotnet dev-certs https --trust ``` In the preceding commands, replace `` with a password. When using [PowerShell](/powershell/scripting/overview), 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="" -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:*** `` is a placeholder for the Kestrel certificates default password. The password must match the password used for the certificate. When using [PowerShell](/powershell/scripting/overview), replace `%USERPROFILE%` with `$env:USERPROFILE`. ## Developing ASP.NET Core Applications with Docker over HTTPS See [Developing ASP.NET Core Applications with Docker over HTTPS](https://github.com/dotnet/dotnet-docker/blob/master/samples/run-aspnetcore-https-development.md) 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](https://github.com/dotnet/dotnet-docker/blob/main/samples/run-aspnetcore-https-development.md) * [`dotnet dev-certs`](/dotnet/core/tools/dotnet-dev-certs) :::moniker-end [!INCLUDE[](~/security/includes/docker-https6.md)]