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
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
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 | 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.