Deploy ASP.NET Core 3.1 Web API to Heroku with Docker

Unlock the potential of deploying your .NET Core 3.1 API on Heroku through Docker, as I guide you in this step-by-step tutorial

Posted: 1/31/2020

As you may know, Heroku do not officially support .NET and .NET Core, but it doesn’t mean that you can’t deploy to it your application written in one of these technologies. In today’s post I will show you how to deploy your .NET Core 3.1 API to Heroku using Docker and how to avoid issues that may occur during this process.


Create a project in Visual Studio

We are starting from creating new project in Visual Studio. In today’s post we’ll use Web API template. Remember to select checkbox with Docker Support - it will automatically generate Dockerfile for your project which we’ll need later.

Remember - even if you use Windows to application development, your Docker image should be prepared for Linux.

If you have Docker installed, but not running you will see the following message box after creating project. Of course choose ‘Yes’ if you don’t want to see errors in the future.

Issue #1: If you select Windows Docker Support, you will get the following error while trying to build a docker image:

Image operating system “windows” cannot be used on this platform.

Prepare dockerfile

When you open Dockerfile generated by project template you should see the following content:

Although we didn’t change anything in the Dockerfile or in the cs files, attempting to build the image would end in error. I was googling a lot on how to repair this file with as few changes as possible and after many errors I’ve finally successfully build an image with following Dockerfile:

FROM AS base

FROM AS build
COPY ["HerokuDockerDeployment.csproj", "HerokuDockerDeployment"]
RUN dotnet restore "HerokuDockerDeployment/HerokuDockerDeployment.csproj"
WORKDIR "/src/HerokuDockerDeployment"
COPY . .
RUN dotnet build "HerokuDockerDeployment.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "HerokuDockerDeployment.csproj" -c Release -o /app/publish

FROM base AS final
COPY --from=publish /app/publish .
CMD ASPNETCORE_URLS=http://*:$PORT dotnet HerokuDockerDeployment.dll

Create Heroku app

The most difficult part of the process is behind us, now it’s time for some clicking ;) Go to Heroku website and log in or sign up if you don’t have account yet. Then click on New and Create new app as shown on the screen.

Enter the name you like and select the region (closest to you would be the best). Remember the name of the application - you will need it in the next steps. Click on Create app button - your app is now ready.

Create docker image

Now open the PowerShell console in the project folder (not solution!). For example, for my project it is: ~/source/repos//. Then run the following command to build a docker image (don’t forget the dot at the end!):

docker build -t <docker-image-name> .

Issue #2: If Docker is not running on your machine, you will get the following error:

Error during connect Docker issue.

If command was completed successfully, use the tag command to tag from your source image into target image (on Heroku).

docker tag <docker-image-name><heroku-app-name>/web

Use Heroku CLI

The last part covers deployment of created image to Heroku. We’re starting with logging from PowerShell console to Heroku and then to container using Heroku CLI commands.

heroku login
heroku container:login

Next, push the container to Heroku:

heroku container:push web -a <heroku-app-name>

And finally - release your work to web:

heroku container:release web -a <heroku-app-name>

Issue #3: If you make a mistake in your Dockerfile or use ENTRYPOINT command instead of CMD with dynamic PORT assignment you will see the following error:

Unable to start Kestrel.

Testing Result

Now we need to check whether our application is publicly available. This is another moment when the previously assigned name for our application is important - the domain of the hosted application consists of the application name and suffix In my case it is

Final view of published example .NET Core 3.1 API on Heroku.

I hope that thanks to this tutorial you will publish your .NET Core application on Heroku quickly and without any issues. Good luck!


Hero photo by chuttersnap on Unsplash