LEARN BUILD GROW TOGETHER
DEVELOPER LEARNING HUB
Learn. Build. Grow Together.

Practical tutorials, real-world examples and interview preparation.

.NETC#SQL SERVERANGULAR
Home /.NET /Dockerize ASP.NET Core Web API – Step-by-Step Guide

Dockerize ASP.NET Core Web API – Step-by-Step Guide

November 19, 2026 5 min read , , , , ,

Introduction

In the previous articles of our 30-Day ASP.NET Core Web API series, we explored API versioning, pagination, filtering, sorting, and unit testing.

Today, let's learn how to Dockerize an ASP.NET Core Web API and run our application inside a Docker container.

Instead of depending on the environment configured on our machine, Docker allows us to package our application and its dependencies into a portable container.

What Is Docker?

Docker is a platform that allows developers to package applications and their dependencies into containers.

A container provides a consistent environment in which an application can run, regardless of where it is deployed.

For example, an ASP.NET Core Web API might run on:

  • A developer's laptop

  • A testing server

  • A cloud server

  • A Docker-enabled hosting platform

Docker helps reduce the common problem:

"It works on my machine, but it doesn't work on the server."

Why Dockerize a Web API?

Without Docker, deployment may require installing and configuring the correct runtime, dependencies, environment variables, and other application requirements on each server.

Docker simplifies this process.

Benefits of Docker

  • Consistent application environments

  • Easier deployment

  • Application isolation

  • Simplified dependency management

  • Portable applications

  • Easier scaling

  • Faster environment setup

  • Support for CI/CD workflows


Docker Architecture

Docker uses several important concepts.

Docker Image

An image is a packaged blueprint containing the application and the environment required to run it.

Docker Container

A container is a running instance of a Docker image.

Dockerfile

A Dockerfile contains instructions used to build a Docker image.

Docker Engine

Docker Engine is responsible for building and running containers.

Docker Registry

A registry stores and distributes Docker images. Docker Hub is one commonly used registry.

Visual Overview

Docker Architecture Dockerfile Build instructions for the application Docker Image Packaged application and dependencies Container Running API instance Application Access Host Port → Container Port Docker Engine Build • Start • Stop • Manage


Step 1 – Install Docker

Install Docker Desktop on your machine.

After installation, open a terminal and verify the installation.

PowerShell / CMD

docker --version

Check whether Docker is running:

docker info

List currently running containers:

docker ps

List all containers, including stopped ones:

docker ps -a

Step 2 – Create an ASP.NET Core Web API

If you already have a Web API project, you can use it.

Otherwise, create a sample API.

dotnet new webapi -n ProductApi

Navigate to the project:

PowerShell

cd ProductApi

CMD

cd ProductApi

Run the API normally before Dockerizing it:

dotnet run

Verify that the API is working using the URL shown in your terminal.

Stop the application before continuing.


Step 3 – Understand the Dockerfile

A Dockerfile contains the instructions Docker uses to create an image.

For ASP.NET Core applications, we commonly use a multi-stage Dockerfile.

Why multiple stages?

  • The SDK image is required to restore, build, and publish the application.

  • The runtime image is sufficient to run the published application.

  • The final image can be smaller because it doesn't need the full SDK.

Multi-Stage Docker Build

Multi-Stage Docker Build Build Stage .NET SDK Image Restore & Build Publish Output Runtime Stage ASP.NET Runtime Image Published API Files Run Application SDK for building → Runtime for running


Step 4 – Create a Dockerfile

Inside your project folder, create a new file named:

Dockerfile

No file extension.

For this example, assume the project structure looks like this:

ProductApi/
│
├── ProductApi.csproj
├── Program.cs
├── appsettings.json
├── Controllers/
│
└── Dockerfile

Add the following code to the Dockerfile.

# Build stage
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build

WORKDIR /src

COPY *.csproj ./

RUN dotnet restore

COPY . ./

RUN dotnet publish -c Release -o /app/publish

# Runtime stage
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS final

WORKDIR /app

COPY --from=build /app/publish .

ENV ASPNETCORE_URLS=http://+:8080

EXPOSE 8080

ENTRYPOINT ["dotnet", "ProductApi.dll"]

Note: This example uses .NET 10. If your project targets another supported .NET version, use matching SDK and ASP.NET runtime image tags and update the Dockerfile accordingly.

Understanding the Dockerfile

Instruction Purpose
FROM Specifies the base image
WORKDIR Sets the working directory
COPY Copies files into the image
RUN Executes commands during image building
dotnet restore Restores dependencies
dotnet publish Publishes the application
ENV Sets an environment variable
EXPOSE Documents the container port
ENTRYPOINT Defines the command that starts the container

Step 5 – Create a .dockerignore File

Before building the Docker image, create a file named:

.dockerignore

This file prevents unnecessary files from being copied into the Docker build context.

bin/
obj/
.git/
.vs/
.vscode/
*.user
*.suo

Why is this important?

  • Reduces build context size

  • Avoids copying unnecessary files

  • Improves build performance

  • Helps keep images cleaner


Step 6 – Build the Docker Image

Open the terminal in the folder containing your Dockerfile.

Run:

docker build -t productapi .

Command explanation

  • docker build – Builds a Docker image.

  • -t productapi – Assigns the image a name.

  • . – Uses the current folder as the build context.

After the build completes, list your images.

docker images

You should see an image named productapi.


Step 7 – Run the Docker Container

Now let's start a container from the image.

docker run -d -p 8080:8080 --name productapi-container productapi

Understanding the command

Parameter Meaning
docker run Creates and starts a container
-d Runs in detached mode
-p 8080:8080 Maps host port 8080 to container port 8080
--name Assigns a container name
productapi The image used to create the container

Port Mapping

Your Computer                  Docker Container
─────────────────              ─────────────────
localhost:8080   ──────────►  Container:8080

Your application is configured to listen on port 8080 inside the container. Docker maps that port to port 8080 on your computer.


Step 8 – Test the API

Open your browser or API testing tool and access the API through:

http://localhost:8080

If your API contains a controller endpoint such as:

[HttpGet]
public IActionResult GetProducts()
{
    return Ok(new[]
    {
        new { Id = 1, Name = "Laptop" },
        new { Id = 2, Name = "Mouse" }
    });
}

Your actual endpoint might be:

http://localhost:8080/api/products

Use the endpoint defined by your application.


Step 9 – Docker Commands You Should Know

View Running Containers

docker ps

View All Containers

docker ps -a

View Container Logs

docker logs productapi-container

Follow logs continuously:

docker logs -f productapi-container

Stop a Container

docker stop productapi-container

Start a Stopped Container

docker start productapi-container

Restart a Container

docker restart productapi-container

Remove a Container

First stop it:

docker stop productapi-container

Then remove it:

docker rm productapi-container

Remove an Image

docker rmi productapi

You may need to remove containers created from that image before Docker allows the image to be removed.


Step 10 – Useful Commands for PowerShell and CMD

Most Docker commands are the same in both PowerShell and CMD.

Build an Image

docker build -t productapi .

Run a Container

docker run -d -p 8080:8080 --name productapi-container productapi

Check Containers

docker ps

Stop the Container

docker stop productapi-container

View Logs

docker logs productapi-container

PowerShell: Remove Container

docker rm -f productapi-container

CMD: Remove Container

docker rm -f productapi-container

These commands are identical in both shells for this example.


Step 11 – Docker Image vs. Docker Container

This is one of the most common Docker interview questions.

Docker Image Application Dependencies Blueprint / Package Container Running API Runtime Process Running Instance An image can be used to create multiple containers

Docker Image Docker Container
Blueprint/package Running instance
Generally immutable Has a writable container layer
Created through a build or pull Created from an image
Can create multiple containers Represents an application instance

Step 12 – Run Multiple Containers from the Same Image

One Docker image can be used to create multiple containers.

For example:

docker run -d -p 8081:8080 --name productapi-1 productapi
docker run -d -p 8082:8080 --name productapi-2 productapi

Now you have two containers running from the same image.

                  ProductApi Image
                       |
             ┌─────────┴─────────┐
             |                   |
       Container 1         Container 2
       Host: 8081          Host: 8082
       Docker: 8080        Docker: 8080

You can access them separately using their host ports.

http://localhost:8081
http://localhost:8082

Each container has its own application process and container environment.


Step 13 – Common Docker Mistakes

1. Port Mapping Is Incorrect

Incorrect:

docker run -p 8080:5000 productapi

If your application listens on port 8080 inside the container, mapping host port 8080 to container port 5000 will not work.

Correct:

docker run -p 8080:8080 productapi

2. Application Listening on the Wrong Address

An application listening only on localhost inside the container may not be accessible through Docker's published port.

Configure the API to listen on an address accessible inside the container, for example:

ENV ASPNETCORE_URLS=http://+:8080

3. Using the SDK Image for Production

The SDK image includes build tools that are not required to run the published application.

Using separate build and runtime stages can reduce the final image size.

4. Forgetting to Check Logs

If a container stops unexpectedly, check its logs:

docker logs productapi-container

5. Forgetting Environment Configuration

Production applications may require connection strings, API keys, and environment-specific settings.

Don't hardcode secrets inside the Dockerfile or image.

Use appropriate environment configuration and secret-management approaches for your deployment environment.


Step 14 – What Happens When We Dockerize an API?

ASP.NET Core Web API Source Code
              |
              ▼
         Dockerfile
              |
              ▼
        docker build
              |
              ▼
         Docker Image
              |
              ▼
         docker run
              |
              ▼
      Running Container
              |
              ▼
       API Accessible

Docker gives us a consistent way to package and run our API.


Key Takeaways

  • Docker packages applications into containers.

  • A Docker image is a blueprint for creating containers.

  • A Docker container is a running instance of an image.

  • Dockerfile defines how an image is built.

  • Multi-stage builds separate building from running.

  • Port mapping allows us to access a containerized API from the host.

  • Docker helps make application deployment more consistent.

  • Multiple containers can run from the same image.

  • Logs are essential when troubleshooting containers.


What's Next?

In Day 28, we'll learn how to Deploy an ASP.NET Core Web API to Azure and understand how our application can move from a local Docker environment to cloud hosting.



Skills Tutorials – Learn • Build • Grow Together

Continue learning with our 30-day .NET Core Web API series.