The Complete step by step Guide to Docker in .NET 10

Let me paint a picture that will sound painfully familiar. Your .NET application compiles and runs perfectly on your machine. Unit tests pass, integration tests pass, the API responds beautifully on localhost. You merge the pull request, the team pulls it down, and suddenly half the dependencies are missing. QA picks it up and gets a different version of the runtime. Staging has a different OS patch level. Production breaks on deploy day because of an environment variable that exists on your machine but nowhere else.

This is the it works on my machine problem, and it has been wasting engineering hours since the beginning of software deployment. Docker solves it completely. When you containerize your .NET application, you package everything, the runtime, the dependencies, the configuration, the exact OS layer into a single artifact. That artifact runs identically on your laptop, in CI, in staging, and in production. There will be zero surprises, environment drift and deploy day panic.

In this article, we are going to build a complete Docker implementation for .NET 10 applications. Not a hello world container. We are going to build production grade infrastructure: multi-stage Dockerfiles that shrink your images by 93%, Docker Compose stacks for full local development, layer caching that makes your builds lightning fast, health checks, CI/CD pipelines, and security hardening. Everything uses real code you can drop into your own projects.

Why Docker for .NET Developers

Before we touch a Dockerfile, it is worth understanding why Docker matters specifically for .NET development and what problems it actually solves.

The Environment Parity Problem

Every .NET application depends on more than just your code. It depends on the .NET runtime version, NuGet package versions, OS-level libraries, environment variables, configuration files, and often external services like databases and caches. In a traditional deployment, you install the runtime on the server, copy your published files, configure IIS or a reverse proxy, and hope that the server's environment matches what you tested against.

The gap between tested locally and deployed to production is where bugs hide. Maybe your local machine has .NET 10.0.1 but the server has 10.0.0. Maybe a NuGet package depends on a native library that exists on Windows but not on the Linux server. Maybe there is an environment variable set on your machine that you forgot to document. These are not edge cases. They are the most common source of deployment failures in .NET projects.

Docker eliminates this entire category of problems. Your Dockerfile explicitly declares every dependency. The image you build locally is byte-for-byte identical to the image that runs in production. If it works in the container, it works everywhere.

The Onboarding Problem

Think about what happens when a new developer joins your team. They need to install the correct .NET SDK version, set up a local database, configure Redis, install any native dependencies, set environment variables, and hope their machine matches everyone else's setup. This process takes hours to days and almost always involves troubleshooting someone's unique machine configuration.

With Docker Compose, the new developer runs a single command: docker compose up. Five minutes later, they have the full application stack running API, database, cache, logging. all configured and connected. There will be no installation instructions, No environment setup, No ask Rizwan, He got it working last week.

Image Size and Build Speed

A common misconception is that Docker images are huge and slow to build. With multi-stage builds, a .NET 10 API image can be under 100 MB. With proper layer caching, subsequent builds complete in seconds because Docker only rebuilds the layers that changed. We will build both of these optimizations step by step.

Installing Docker and Verifying the Setup

Docker Desktop is the easiest way to get started on Windows and macOS. It includes the Docker daemon, the CLI, and Docker Compose.

Download and Install

Download Docker Desktop from the official Docker website for your operating system. On Windows, make sure WSL 2 is enabled (Docker Desktop will prompt you during installation if it is not). On macOS, the installer handles everything automatically.

After installation, verify that Docker is running:

bash
docker --version

You should see something like:

Docker version 27.x.x, build xxxxxxx

Also verify Docker Compose:

bash
docker compose version

Docker Compose version v2.x.x

Running Your First Container

Let us make sure everything works with a quick test:

bash
docker run --rm -it mcr.microsoft.com/dotnet/sdk:10.0 dotnet --info

This pulls the official .NET 10 SDK image and prints the runtime information. If you see the .NET 10 version details, Docker is working correctly.

Understanding Docker Concepts for .NET

Before we write our Dockerfile, let us clarify the key concepts:

Image: A read only template that contains everything needed to run your application, the OS layer, runtime, dependencies, and your compiled code. Think of it like a snapshot.

Container: A running instance of an image. You can run multiple containers from the same image. Each container has its own isolated file system, networking, and process space (volume).

Dockerfile: A text file with instructions that tell Docker how to build an image. Each instruction creates a layer in the image. The file name should be exact Dockerfile and this file does not have any extension.

Layer: Each Dockerfile instruction (FROM, COPY, RUN) creates a new layer. Docker caches these layers, so if a layer has not changed since the last build, Docker reuses the cached version instead of rebuilding it.

Registry: A storage location for Docker images. Docker Hub, GitHub Container Registry, and Azure Container Registry are common choices.

Writing a Production Dockerfile for .NET 10

This is where most teams get it wrong. The simplest Dockerfile for a .NET application looks like this:

dockerfile
FROM mcr.microsoft.com/dotnet/sdk:10.0
WORKDIR /app
COPY . .
RUN dotnet publish -c Release -o /out
ENTRYPOINT ["dotnet", "/out/MyApp.dll"]

This works, but it is terrible for production. The SDK image is over 800 MB. It includes the compiler, MSBuild, NuGet CLI, and other build tools that your running application does not need. You are shipping your entire workshop when you only need the finished product.

Multi-Stage Build: The Right Way

A multi-stage build uses one image to build your application and a different, much smaller image to run it.

dockerfile
# Stage 1: Build
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src

# Copy only the project file first (for layer caching)
COPY ["src/MyApp.Api/MyApp.Api.csproj", "src/MyApp.Api/"]
RUN dotnet restore "src/MyApp.Api/MyApp.Api.csproj"

# Copy everything else and publish
COPY . .
WORKDIR "/src/src/MyApp.Api"
RUN dotnet publish "MyApp.Api.csproj" -c Release -o /app/publish \
    --no-restore \
    /p:UseAppHost=false

# Stage 2: Runtime
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS final
WORKDIR /app

# Create a non-root user for security
RUN adduser --disabled-password --gecos "" appuser
USER appuser

COPY --from=build /app/publish .

EXPOSE 8080
ENTRYPOINT ["dotnet", "MyApp.Api.dll"]

Let us break down what each section does and why it matters.

Stage 1 (build) uses the full SDK image because it needs the compiler. The key optimization is copying the .csproj file separately and running dotnet restore before copying the rest of the source code. This means that as long as your project file (and therefore your NuGet dependencies) has not changed, Docker reuses the cached restore layer. Your builds only need to recompile the code that changed.

Stage 2 (final) uses the ASP.NET runtime image, which is dramatically smaller because it only contains the runtime, no compiler, no build tools. The COPY --from=build instruction copies just the published output from the build stage into the runtime image. Everything else from the build stage is discarded.

The size difference is dramatic:

If you compile as a self-contained application with trimming enabled, you can use runtime-deps (which only contains the OS dependencies, not the .NET runtime itself) and get your image under 100 MB.

The .dockerignore File

Just like .gitignore prevents files from being tracked by Git, .dockerignore prevents files from being sent to the Docker daemon during builds. Without it, Docker copies everything in your project directory, including bin/, obj/, node_modules/, .git/, local secrets, and IDE configuration into the build context.

Create a .dockerignore file in your project root:

**/.dockerignore
**/.env
**/.git
**/.gitignore
**/.vs
**/.vscode
**/bin
**/obj
**/node_modules
**/docker-compose*.yml
**/Dockerfile*
**/*.md
**/*.user
**/*.suo
**/charts
**/secrets.dev.yaml

This reduces your build context from potentially gigabytes to just your source code. I have seen teams where adding a proper .dockerignore cut their build time from 8 minutes to under a minute because Docker was no longer uploading 2 GB of unnecessary files to the daemon.

Docker Compose for Local Development

Running a single container is straightforward, but real applications usually depend on a database, a cache, a message queue, and a logging stack. Docker Compose lets you define and run all of these services together.

The docker-compose.yml File

yaml
services:
  api:
    build:
      context: .
      dockerfile: src/MyApp.Api/Dockerfile
    ports:
      - "5000:8080"
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - ConnectionStrings__DefaultConnection=Host=postgres;Database=myapp;Username=postgres;Password=postgres
      - ConnectionStrings__Redis=redis:6379,abortConnect=false
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - app-network

  postgres:
    image: postgres:16
    environment:
      - POSTGRES_DB=myapp
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
    ports:
      - "5432:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - app-network

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - app-network

  seq:
    image: datalust/seq:latest
    environment:
      - ACCEPT_EULA=Y
    ports:
      - "5341:5341"
      - "8081:80"
    volumes:
      - seq-data:/data
    networks:
      - app-network

volumes:
  postgres-data:
  redis-data:
  seq-data:

networks:
  app-network:
    driver: bridge

What This Stack Gives You

With a single docker compose up, you get:

• ASP.NET Core API built from your Dockerfile, running on port 5000
• PostgreSQL 16 with persistent storage and a health check
• Redis 7 for caching with persistent storage and a health check
• Seq for structured logging with a web UI on port 8081

The depends_on with condition: service_healthy ensures your API does not start until the database and cache are actually ready to accept connections. Without this, your API might start before PostgreSQL finishes initializing and throw connection errors on the first few requests.

Running the Stack

bash
# Start all services in the background
docker compose up -d

# View logs from all services
docker compose logs -f

# View logs from just the API
docker compose logs -f api

# Stop all services
docker compose down

# Stop and remove all data volumes
docker compose down --volumes

Environment Configuration with Docker

.NET's configuration system works naturally with Docker environment variables. The double underscore __ syntax maps to the colon : separator in your configuration hierarchy.

For example, this environment variable:

ConnectionStrings__DefaultConnection=Host=postgres;Database=myapp

Maps to this in appsettings.json:

json
{
  "ConnectionStrings": {
    "DefaultConnection": "Host=postgres;Database=myapp"
  }
}

Using the Options Pattern

For structured settings, use the Options pattern with environment variables:

csharp
public class DockerSettings
{
    public string DatabaseHost { get; set; } = "localhost";
    public int DatabasePort { get; set; } = 5432;
    public string RedisConnection { get; set; } = "localhost:6379";
}

csharp
builder.Services.Configure<DockerSettings>(
    builder.Configuration.GetSection("Docker"));

Then set the variables in your Docker Compose file:

yaml
environment:
  - Docker__DatabaseHost=postgres
  - Docker__DatabasePort=5432
  - Docker__RedisConnection=redis:6379

This approach keeps your code clean and testable while letting Docker control the configuration at runtime.

Health Checks Inside Containers

Health checks tell Docker (and any orchestrator running your containers) whether your application is actually healthy and ready to serve traffic. Without health checks, Docker only knows if your process is running, not whether it can actually handle requests.

ASP.NET Core Health Check Endpoint

First, add the health checks NuGet package and configure them in your application:

csharp
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks()
    .AddNpgSql(
        builder.Configuration.GetConnectionString("DefaultConnection")!,
        name: "postgresql",
        tags: new[] { "db", "ready" })
    .AddRedis(
        builder.Configuration.GetConnectionString("Redis")!,
        name: "redis",
        tags: new[] { "cache", "ready" });

var app = builder.Build();

app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = _ => false // No checks, just confirms the app is running
});

app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("ready")
});

The /health/live endpoint confirms the application process is running (liveness). The /health/ready endpoint confirms that the application can connect to its dependencies (readiness).

Docker HEALTHCHECK Instruction

Wire the health endpoint into your Dockerfile:

dockerfile
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS final
WORKDIR /app

COPY --from=build /app/publish .

EXPOSE 8080

HEALTHCHECK --interval=30s --timeout=10s --start-period=15s --retries=3 \
    CMD curl -f http://localhost:8080/health/live || exit 1

ENTRYPOINT ["dotnet", "MyApp.Api.dll"]

Docker will call the health check every 30 seconds. If it fails 3 times in a row, the container is marked as unhealthy. Any orchestrator (Docker Compose, Kubernetes, etc.) can use this information to restart or replace the container.

Layer Caching: Making Builds Fast

Docker layer caching is the single biggest build performance optimization, and it depends entirely on the order of instructions in your Dockerfile.

The rule is simple: Docker caches each layer and reuses it as long as that layer and all previous layers have not changed. The moment Docker detects a change, it invalidates that layer and all subsequent layers.

The Wrong Order

dockerfile
COPY . .
RUN dotnet restore
RUN dotnet publish -c Release -o /out

With this order, every time you change any file in your project, Docker invalidates the COPY . . layer, which invalidates the restore layer, which forces a full NuGet restore on every build. If you have 200 NuGet packages, that is an extra 30 to 60 seconds on every build.

The Right Order

dockerfile
COPY *.csproj .
RUN dotnet restore
COPY . .
RUN dotnet publish -c Release -o /out --no-restore

With this order, the restore layer is only invalidated when your .csproj file changes (which means your NuGet dependencies changed). Day to day code changes only invalidate the final COPY . . and publish layers. Your builds go from minutes to seconds.

For a solution with multiple projects:

dockerfile
# Copy all project files first
COPY src/MyApp.Api/MyApp.Api.csproj src/MyApp.Api/
COPY src/MyApp.Core/MyApp.Core.csproj src/MyApp.Core/
COPY src/MyApp.Infrastructure/MyApp.Infrastructure.csproj src/MyApp.Infrastructure/
COPY MyApp.sln .

# Restore using the solution file
RUN dotnet restore MyApp.sln

# Now copy everything else
COPY . .

Debugging .NET Containers

One concern developers have about Docker is losing their debugging workflow. You do not have to give up breakpoints or the watch window.

Visual Studio

Visual Studio has built-in Docker support. Right-click your project, select Add > Docker Support, and Visual Studio generates a Dockerfile and debugging configuration. Press F5, and it builds the image, starts the container, and attaches the debugger automatically. Breakpoints, watch window, immediate window so everything works as if you are running locally.

Visual Studio Code

For VS Code, add a .vscode/tasks.json that builds your Docker image and a .vscode/launch.json with a Docker attach configuration. The C# Dev Kit extension supports attaching to containers directly.

Alternatively, you can use the docker exec command to attach a debugger manually:

bash
# Find your container ID
docker ps

# Exec into the container
docker exec -it <container-id> /bin/bash

For most day-to-day development, running the API directly with dotnet run and using Docker Compose only for dependencies (database, Redis, etc.) gives you the best balance of development speed and production parity.

Container Networking

When you run multiple containers with Docker Compose, they need to communicate with each other. Docker handles networking through bridge networks.

How Service Discovery Works

In our Compose file, we defined a network called app-network. Every service on this network can reach other services by their service name. When your .NET API connects to the database using Host=postgres, Docker's built-in DNS resolves postgres to the IP address of the PostgreSQL container.

This is why the connection string in the Docker environment uses service names instead of localhost:

ConnectionStrings__DefaultConnection=Host=postgres;Database=myapp;Username=postgres;Password=postgres

The service name postgres is the DNS name. Docker resolves it automatically within the Compose network.

Port Mapping

The ports configuration in Compose maps a host port to a container port:

yaml
ports:
  - "5000:8080" # host:container

This means:

• From your host machine (browser, API client), access the API at localhost:5000
• Inside the Docker network, other containers reach the API at api:8080
• The container itself listens on port 8080

CI/CD Pipeline with GitHub Actions

Once your Dockerfile is production ready, automate the build and push process with GitHub Actions.

Build, Tag, and Push Workflow

yaml
name: Build and Push Docker Image

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Log in to Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=sha,prefix=
            type=ref,event=branch
            type=semver,pattern={{version}}

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          file: src/MyApp.Api/Dockerfile
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

This workflow builds the Docker image on every push and pull request. On pushes to main, it also pushes the tagged image to GitHub Container Registry. The cache-from and cache-to options use GitHub Actions cache to speed up subsequent builds.

Security Best Practices

Running containers in production requires attention to security. Here are the practices every .NET team should follow.

Run as Non-Root User

By default, Docker containers run as root. This means if an attacker exploits a vulnerability in your application, they have root access inside the container. Always create and switch to a non-root user:

dockerfile
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS final
WORKDIR /app

# Create non-root user
RUN adduser --disabled-password --gecos "" appuser

# Copy application files
COPY --from=build /app/publish .

# Switch to non-root user
USER appuser

EXPOSE 8080
ENTRYPOINT ["dotnet", "MyApp.Api.dll"]

Use Minimal Base Images

The smaller your image, the smaller your attack surface. Prefer aspnet over sdk for runtime, and runtime-deps for self-contained applications. Alpine-based images are even smaller:

dockerfile
FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final

Scan for Vulnerabilities

Use Trivy or Docker Scout to scan your images for known vulnerabilities:

bash
# Install Trivy and scan your image
trivy image myapp:latest

Add vulnerability scanning to your CI pipeline so you catch issues before they reach production.

Read-Only File System

If your application does not need to write to the file system, run with a read-only root:

yaml
services:
  api:
    image: myapp:latest
    read_only: true
    tmpfs:
      - /tmp

The tmpfs mount provides a writable temporary directory in memory for anything that genuinely needs to write temporary files.

Common Mistakes and How to Fix Them

After helping multiple teams containerize their .NET applications, these are the mistakes I see most often.

1. No Multi-Stage Build

Mistake: Using the SDK image as the runtime image, shipping 800+ MB images with the compiler baked in.

Fix: Always use a multi-stage build. Build with sdk, run with aspnet or runtime-deps.

2. Missing .dockerignore

Mistake: Docker uploads bin/, obj/, .git/, node_modules/, and local secrets to the build context.

Fix: Create a comprehensive .dockerignore file. Your build context should contain only source code.

3. Wrong Layer Order

Mistake: Copying all files before restoring NuGet packages, forcing a full restore on every build.

Fix: Copy .csproj files first, restore, then copy the rest. NuGet restore is cached until dependencies change.

4. Hardcoded Connection Strings

Mistake: Baking connection strings into appsettings.json or worse, directly in code.

Fix: Use environment variables for all environment-specific configuration. Docker Compose and Kubernetes both have excellent support for injecting environment variables at runtime.

5. No Health Checks

Mistake: Docker has no way to know if your application is truly healthy or just has a running process.

Fix: Add ASP.NET Core health checks with the HEALTHCHECK Dockerfile instruction. Distinguishing between liveness and readiness checks.

6. Running as Root

Mistake: The default container runs as root, giving potential attackers elevated privileges.

Fix: Add a non-root user in your Dockerfile and switch to it with USER.

7. Ignoring Image Size

Mistake: Shipping 1+ GB images that take minutes to pull and eat storage.

Fix: Multi-stage builds, .dockerignore, Alpine base images, and trimming for self-contained builds.

Real World Migration Results

When I migrated a production .NET application to Docker, the numbers spoke for themselves:

The deployment time improvement came from replacing a manual publish-and-copy process with pulling a pre-built image. The environment parity bugs disappeared completely because every environment runs the exact same image. The onboarding improvement was the biggest surprise, new developers went from spending two days setting up their local environment to running docker compose up and being productive in under an hour.

What I Recommend for Most .NET Teams

If you are starting from scratch, here is the path I recommend:

Step 1: Dockerfile. Write a multi-stage Dockerfile for your API. Add a .dockerignore. Verify the image size is under 250 MB (ideally under 100 MB with runtime-deps).

Step 2: Docker Compose. Add a Compose file for local development with your database and cache. Every developer should be able to run docker compose up and have the full stack working.

Step 3: CI/CD. Add a GitHub Actions workflow that builds and pushes your Docker image on every merge to main. Tag images with the git SHA so you can always trace a running image back to the exact commit.

Step 4: Health Checks. Add liveness and readiness health checks to your API and wire them into the Docker HEALTHCHECK instruction.

Step 5: Security. Non-root user, minimal base image, vulnerability scanning in CI. These take 10 minutes to set up and prevent entire categories of security issues.

Do not jump to Kubernetes. Docker Compose handles the needs of most teams. Kubernetes adds significant complexity and operational overhead. Only adopt it when you genuinely need multi-node orchestration, auto-scaling based on metrics, or advanced deployment strategies like canary releases.

Conclusion

Docker is not just another tool to add to your stack. It is a fundamental shift in how you think about deployment. Instead of deploying code to a server and hoping the environment matches, you deploy a complete, self-contained unit that is guaranteed to run identically everywhere.

For .NET developers specifically, the ecosystem support is excellent. Microsoft maintains official Docker images for every .NET version, the multi-stage build pattern works beautifully with dotnet publish, and Docker Compose gives you a production-like local environment with zero manual setup.

The investment is front-loaded, writing the Dockerfile, configuring Compose, setting up CI/CD but once it is done, every subsequent deployment is faster, more reliable, and more predictable. Your team stops fighting environment issues and starts shipping features.

Start with a single Dockerfile for your API. Get comfortable with the build, run, and debug cycle. Then expand to Compose for your full stack. The consistency and reliability you gain will make you wonder how you ever deployed any other way.

Thanks, Muhammad Rizwan