How to run an ASP.NET Core web app in Docker Compose and use a local development certificate for SSL

When running an ASP.NET Core web app through Visual Studio, an SSL certificate is managed for you so you can use HTTPS to navigate to the web app.

However, it is not clear how you mount this local SSL certificate inside a Docker container running via Docker Compose.

The following document from the docker-dotnet outlines the process if you are running a Docker container manually but doesn’t include specifics on Docker Compose.

Create new local SSL certificate with password

Remove your existing local development self-signed certificate.

dotnet dev-certs https --clean

Create a new local development self-signed certificate (note that this is PowerShell syntax for getting the user profile path, modify as needed for other shells) and set a password

dotnet dev-certs https -ep $env:USERPROFILE/.aspnet/https/aspnetapp.pfx -p <password>

dotnet dev-certs https --trust

You will notice that a new SSL cert has been created in your home directory with the name aspnetapp.pfx.

dir ~/.aspnet/https

        Directory: C:\Users\dwightschrute\.aspnet\https


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a---         7/11/2023  10:37 PM           2660   aspnetapp.pfx

Modify docker-compose.yaml to mount the new SSL certificate & reference it in ASP.NET Core

Open your docker-compose.yaml file and add the following volume mount under the service that is hosting your ASP.NET Core web app.

volumes:
  - ~/.aspnet/https:/https

This mounts the directory that contains the new SSL cert as a directory in the container (under the /https path). Note that this is for a Windows machine running WSL2. You may have to modify this path to point to the correct path as exposed to your Linux environment.

Now add the following environment variables under the service that is hosting your ASP.NET Core web app in the environment section.

environment:
  "ASPNETCORE_URLS": "https://+;http://+"
  "ASPNETCORE_Kestrel__Certificates__Default__Password": "<password>"
  "ASPNETCORE_Kestrel__Certificates__Default__Path": "/https/aspnetapp.pfx"

These environment variables tell ASP.NET where & how to set up SSL. Note the password needs to be the same as the one that you generated before. Note the path to the SSL cert is the path inside the container, not the path on your machine. Also note the double underscore between the nested sections of the environment variables. This is the most cross-platform way to specify nested parameters (colons are not necessarily cross-platform depending on your environment).

Finally, expose both the HTTP & HTTPS ports in the ports section of your service definition.

ports:
  - "80:80"
  - "443:443"

The complete Docker Compose file looks like this.

services:
  server:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: server
    environment:      
      "ASPNETCORE_URLS": "https://+;http://+"
      "ASPNETCORE_Kestrel__Certificates__Default__Password": "<password>"
      "ASPNETCORE_Kestrel__Certificates__Default__Path": "/https/aspnetapp.pfx"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ~/.aspnet/https:/https

You can now launch your Docker Compose app.

docker compose up

You can now navigate to your locally running web app on HTTPS.