Dockerizing ASP.NET Core: Multi-Stage Builds, Clean Images & a Production-Ready Ship Workflow

dotnet new webapi -n DockerizedTodoApi --no-https --minimal
cd DockerizedTodoApi

# Health checks are included in the ASP.NET Core shared framework (.NET 8)
# No additional package needed — AddHealthChecks() is available in Program.cs directly
# If using a specific DB health check (e.g. SQL Server), add the provider package:
# dotnet add package AspNetCore.HealthChecks.SqlServer

# Verify the app runs locally before touching Docker
dotnet run
# Expected: Application started. Press Ctrl+C to shut down.
# Expected: http://localhost:5000/todos → 200 OK

DockerizedTodoApi/
├── Dockerfile                  # multi-stage, non-root, health-checked
├── .dockerignore               # prevents bin/obj/secrets entering build context
├── docker-compose.yml          # local run with health-check dependency
├── appsettings.json            # base config — committed, no secrets
├── appsettings.Development.json
├── appsettings.Production.json # structure only — runtime env vars supply values
├── Models/
│   └── TodoItem.cs
├── Endpoints/
│   └── TodoEndpoints.cs
├── Health/
│   └── DatabaseHealthCheck.cs  # custom health check registered in Section 6
└── Program.cs

// Models/TodoItem.cs
public record TodoItem(int Id, string Title, bool IsComplete);

// Endpoints/TodoEndpoints.cs
public static class TodoEndpoints
{
    private static readonly List<TodoItem> _store =
    [
        new(1, "Write the Dockerfile", false),
        new(2, "Add health checks",    false),
        new(3, "Ship to registry",     false)
    ];

    public static void MapTodoEndpoints(this WebApplication app)
    {
        var group = app.MapGroup("/todos").WithTags("Todos");

        group.MapGet("/",          ()        => Results.Ok(_store));
        group.MapGet("/{id:int}", (int id)   => _store.FirstOrDefault(t => t.Id == id)
                                               is { } item ? Results.Ok(item) : Results.NotFound());
        group.MapPost("/", (TodoItem item)   => { _store.Add(item); return Results.Created($"/todos/{item.Id}", item); });
        group.MapPut("/{id:int}", (int id, TodoItem updated) =>
        {
            var idx = _store.FindIndex(t => t.Id == id);
            if (idx == -1) return Results.NotFound();
            _store[idx] = updated;
            return Results.NoContent();
        });
        group.MapDelete("/{id:int}", (int id) =>
        {
            _store.RemoveAll(t => t.Id == id);
            return Results.NoContent();
        });
    }
}

# :latest — always points to the most recent published tag
# NEVER use in production Dockerfiles — you get a different image on every pull
FROM mcr.microsoft.com/dotnet/aspnet:latest          # ❌ unpinned

# Major.minor — stable channel, receives patch updates automatically
FROM mcr.microsoft.com/dotnet/aspnet:8.0             # ✅ good default

# Major.minor.patch — exact version, fully deterministic
FROM mcr.microsoft.com/dotnet/aspnet:8.0.13          # ✅ maximum reproducibility

# OS variant suffixes
FROM mcr.microsoft.com/dotnet/aspnet:8.0             # Debian bookworm-slim (recommended default)
FROM mcr.microsoft.com/dotnet/aspnet:8.0-alpine      # Alpine — smaller, musl libc (test thoroughly)
FROM mcr.microsoft.com/dotnet/aspnet:8.0-jammy       # Ubuntu 22.04

# SDK image — for the build stage ONLY, never the final runtime stage
FROM mcr.microsoft.com/dotnet/sdk:8.0                # ✅ build stage
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS final       # ❌ SDK in production image — 800MB+

# Container listens on 8080 internally (non-root cannot bind 80)
# Host maps 5000 → container 8080
docker run -p 5000:8080 my-todo-api

# Format: -p HOST_PORT:CONTAINER_PORT
# You access http://localhost:5000 — Docker routes it to :8080 inside the container

# Expose multiple ports
docker run -p 5000:8080 -p 5001:8081 my-todo-api

# Bind to a specific host interface (more secure — not accessible from other machines)
docker run -p 127.0.0.1:5000:8080 my-todo-api

# EXPOSE in the Dockerfile is documentation only — it does NOT publish the port
# You still need -p at docker run time, or ports: in docker-compose.yml

# ──────────────────────────────────────────────────────────────────
# Stage 1: restore
# Separate restore from build to maximise Docker layer cache.
# The restore layer rebuilds only when .csproj files change —
# not when source files change.
# ──────────────────────────────────────────────────────────────────
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS restore
WORKDIR /src

# Copy project file(s) first — triggers restore layer rebuild only on csproj change
COPY ["DockerizedTodoApi/DockerizedTodoApi.csproj", "DockerizedTodoApi/"]
RUN dotnet restore "DockerizedTodoApi/DockerizedTodoApi.csproj" --locked-mode

# ──────────────────────────────────────────────────────────────────
# Stage 2: build
# Copy all source, then build — restore cache is already warm
# ──────────────────────────────────────────────────────────────────
FROM restore AS build
COPY . .
RUN dotnet build "DockerizedTodoApi/DockerizedTodoApi.csproj" \
    -c Release \
    --no-restore \
    -o /build

# ──────────────────────────────────────────────────────────────────
# Stage 3: publish
# Produce the self-contained publish output without SDK tooling
# ──────────────────────────────────────────────────────────────────
FROM restore AS publish
RUN dotnet publish "DockerizedTodoApi/DockerizedTodoApi.csproj" \
    -c Release \
    --no-restore \
    -o /publish \
    /p:UseAppHost=false          # no native binary wrapper — not needed in Linux container

# ──────────────────────────────────────────────────────────────────
# Stage 4: final runtime image
# Only the publish output lands here — no SDK, no source, no build tools
# ──────────────────────────────────────────────────────────────────
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS final
WORKDIR /app

# Copy only the published output from Stage 3
COPY --from=publish /publish .

# Non-root user setup — covered in detail in Section 4
RUN addgroup --system appgroup && \
    adduser  --system --ingroup appgroup --no-create-home appuser
USER appuser

# Document the port the app listens on (informational — does NOT publish it)
EXPOSE 8080

# Health check — covered in detail in Section 6
HEALTHCHECK --interval=30s --timeout=10s --start-period=15s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1

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

# Without the separate restore stage (naive approach):
COPY . .                         # ← any source file change invalidates this layer
RUN dotnet restore               # ← re-downloads all NuGet packages every time
RUN dotnet publish -c Release    # ← builds from scratch

# With the separate restore stage (correct approach):
COPY *.csproj .                  # ← only csproj files — rarely changes
RUN dotnet restore --locked-mode # ← cached unless .csproj changes
COPY . .                         # ← source files
RUN dotnet build --no-restore    # ← restore cache is already warm

# Result: editing Program.cs and rebuilding takes ~5 seconds (build only)
# instead of ~60 seconds (restore + build). On CI this compounds significantly.

# --locked-mode requires packages.lock.json to exist and be committed.
# Generate it once: dotnet restore --use-lock-file

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

# Copy the publish output first (owned by root at this point)
COPY --from=publish /publish .

# Create a system group and system user with no home directory
# --system users have UID/GID in the system range (typically < 1000)
# --no-create-home reduces the filesystem footprint
RUN addgroup --system appgroup && \
    adduser  --system \
             --ingroup appgroup \
             --no-create-home \
             --disabled-password \
             appuser

# Change ownership of the app directory to the new user
# This ensures the process can read its own files but cannot write outside /app
RUN chown -R appuser:appgroup /app

# Switch to the non-root user — all subsequent RUN, CMD, ENTRYPOINT run as appuser
USER appuser

EXPOSE 8080
ENTRYPOINT ["dotnet", "DockerizedTodoApi.dll"]

# .NET 8 base images ship with a pre-created non-root user named 'app' (UID 1654)
# This is the simplest non-root setup and Microsoft's recommended approach

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

# Use COPY --chown to set ownership in a single layer (more efficient than RUN chown)
COPY --from=publish --chown=app:app /publish .

# Switch to the built-in non-root app user
USER app

EXPOSE 8080
ENTRYPOINT ["dotnet", "DockerizedTodoApi.dll"]

# Verify the running user from inside the container:
# docker exec <container-id> whoami  → app
# docker exec <container-id> id      → uid=1654(app) gid=1654(app)

# ASP.NET Core's config provider stack runs the same inside a container:
# appsettings.json → appsettings.{ASPNETCORE_ENVIRONMENT}.json → Environment Variables

# Set the environment at docker run time
docker run \
  -e ASPNETCORE_ENVIRONMENT=Production \
  -e ConnectionStrings__DefaultConnection="Server=db;Database=todos;..." \
  -e Jwt__SigningKey="runtime-secret-never-in-image" \
  -p 5000:8080 \
  my-todo-api

# Double underscore __ is the hierarchy separator for env vars in .NET
# ConnectionStrings__DefaultConnection → ConnectionStrings:DefaultConnection in config

# Load from a file for local development (file must be gitignored)
docker run --env-file .env.local -p 5000:8080 my-todo-api

# .env.local (gitignored — never committed):
# ASPNETCORE_ENVIRONMENT=Development
# ConnectionStrings__DefaultConnection=Data Source=dev.db
# Jwt__SigningKey=local-dev-signing-key-not-a-real-secret

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "ConnectionStrings": {
    "DefaultConnection": ""
  },
  "Jwt": {
    "Issuer":     "https://your-domain.com",
    "Audience":   "todos-api",
    "SigningKey":  ""
  },
  "AllowedHosts": "*"
}

var builder = WebApplication.CreateBuilder(args);

// Register health checks — add as many as needed
builder.Services.AddHealthChecks()
    // Built-in: always returns Healthy
    // Use for liveness — "is the process alive?"
    .AddCheck("self", () => HealthCheckResult.Healthy("Process is running"))

    // Custom check: "can we reach the database?"
    // Use for readiness — "is the app ready to serve traffic?"
    .AddCheck<DatabaseHealthCheck>("database", tags: ["readiness"]);

var app = builder.Build();

app.MapTodoEndpoints();

// Liveness probe — Kubernetes restarts the pod if this returns unhealthy
// Returns: 200 OK with { "status": "Healthy" }
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = _ => false    // only the always-healthy "self" check
});

// Readiness probe — Kubernetes stops sending traffic if this returns unhealthy
// Returns: 200 OK when all readiness checks pass, 503 Service Unavailable otherwise
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("readiness")
});

// Combined endpoint — used by Docker HEALTHCHECK and load balancers
app.MapHealthChecks("/health");

app.Run();

public class DatabaseHealthCheck(IConfiguration config) : IHealthCheck
{
    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken  cancellationToken = default)
    {
        try
        {
            var connStr = config.GetConnectionString("DefaultConnection");
            if (string.IsNullOrEmpty(connStr))
                return HealthCheckResult.Degraded("Connection string is not configured");

            // Open a connection and run a trivial query to verify reachability
            // Simulated connectivity check — replace with real DB check for production
await Task.Delay(10, cancellationToken); // simulate async check
return HealthCheckResult.Healthy("Database is reachable");

            return HealthCheckResult.Healthy("Database is reachable");
        }
        catch (Exception ex)
        {
            return HealthCheckResult.Unhealthy(
                "Database connectivity check failed",
                exception: ex);
        }
    }
}

# HEALTHCHECK tells the Docker daemon how to probe the container
# Status appears in: docker ps, docker inspect, and compose depends_on conditions

HEALTHCHECK \
  --interval=30s    `# how often Docker runs the check` \
  --timeout=10s     `# how long before the check is considered failed` \
  --start-period=15s `# grace period on startup before failures count` \
  --retries=3       `# consecutive failures before container = unhealthy` \
  CMD curl -f http://localhost:8080/health || exit 1

# curl must be available in the base image
# aspnet:8.0 (Debian) includes curl — verify with: docker run --rm aspnet:8.0 which curl
# aspnet:8.0-alpine does NOT include curl — use wget or install it:
# RUN apk add --no-cache curl

# Alternatively, use the dotnet health check tool (no curl dependency):
HEALTHCHECK CMD dotnet-monitor collect --output /dev/null \
  || wget -qO- http://localhost:8080/health || exit 1

# Check container health status:
docker inspect --format='{{.State.Health.Status}}' <container-id>
# Possible values: starting | healthy | unhealthy | none

## Build output — the single most important exclusion
## Without this, every dotnet build invalidates all COPY layers in Docker
**/bin/
**/obj/

## Git history — never needed in an image, can be large
.git/
.gitignore
.gitattributes

## IDE and editor files
.vs/
.vscode/
*.user
*.suo

## Test projects — not needed in production images
**/*.Tests/
**/*.Test/
**/*Tests.csproj

## Secret files — critical: these must never enter the build context
**/.env
**/.env.*
**/secrets.json
**/appsettings.Local.json
**/*.pfx
**/*.key

## CI/CD and documentation
.github/
docs/
README.md
CHANGELOG.md
*.md

## Node modules (if frontend assets present)
**/node_modules/

## Docker files themselves (informational — reduces build context size slightly)
Dockerfile*
docker-compose*
.dockerignore

# Level 1: Pin to major.minor — gets patch security updates automatically
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS restore        # ✅ recommended for most teams
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS final

# Level 2: Pin to exact patch version — fully deterministic, requires manual updates
FROM mcr.microsoft.com/dotnet/sdk:8.0.404 AS restore
FROM mcr.microsoft.com/dotnet/aspnet:8.0.13 AS final

# Level 3: Pin to SHA256 digest — byte-for-byte identical every build
# Find the digest: docker pull mcr.microsoft.com/dotnet/aspnet:8.0 && docker inspect
FROM mcr.microsoft.com/dotnet/aspnet:8.0@sha256:abc123... AS final

# Practical recommendation:
# Development / feature branches: major.minor (8.0) — automatic security patches
# Production releases / compliance: exact patch (8.0.13) — change-controlled updates
# Air-gapped / regulated environments: SHA256 digest — absolute reproducibility

# Check for available .NET 8 base image digests:
# https://mcr.microsoft.com/v2/dotnet/aspnet/tags/list

# ── Build ────────────────────────────────────────────────────────────────────
# Use a git SHA as the version tag for deterministic, traceable deployments
export VERSION=$(git rev-parse --short HEAD)

docker build \
  -t my-todo-api:${VERSION} \
  -t my-todo-api:latest \
  -f Dockerfile \
  .

# Verify the image is clean — check size and layers
docker image inspect my-todo-api:${VERSION} --format '{{.Size}}'
docker history my-todo-api:${VERSION}

# ── Push to Docker Hub ────────────────────────────────────────────────────────
docker login                                        # prompts for username/password
docker tag  my-todo-api:${VERSION} yourusername/todo-api:${VERSION}
docker push yourusername/todo-api:${VERSION}
docker push yourusername/todo-api:latest

# ── Push to GitHub Container Registry (GHCR) ─────────────────────────────────
# Authenticate with a GitHub Personal Access Token (write:packages scope)
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

docker tag  my-todo-api:${VERSION} ghcr.io/yourusername/todo-api:${VERSION}
docker push ghcr.io/yourusername/todo-api:${VERSION}

# Pull and run from GHCR to verify the push succeeded
docker pull  ghcr.io/yourusername/todo-api:${VERSION}
docker run --rm \
  -p 5000:8080 \
  -e ASPNETCORE_ENVIRONMENT=Production \
  -e ConnectionStrings__DefaultConnection="Data Source=/data/todos.db" \
  ghcr.io/yourusername/todo-api:${VERSION}

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   # required to push to GHCR

    steps:
      - uses: actions/checkout@v4

      - name: Log in to GHCR
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}  # automatically available, no setup needed

      - name: Extract Docker metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=sha                   # ghcr.io/owner/repo:sha-abc1234
            type=raw,value=latest,enable={{is_default_branch}}

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha       # GitHub Actions cache for Docker layers
          cache-to:   type=gha,mode=max

# ── Azure Container Apps ──────────────────────────────────────────────────────
az containerapp create \
  --name todo-api \
  --resource-group my-rg \
  --environment my-env \
  --image ghcr.io/yourusername/todo-api:sha-abc1234 \
  --target-port 8080 \
  --ingress external \
  --env-vars \
      ASPNETCORE_ENVIRONMENT=Production \
      ConnectionStrings__DefaultConnection=secretref:db-conn \
  --min-replicas 1 \
  --max-replicas 5

# Secrets are managed by Container Apps — referenced via secretref:
az containerapp secret set --name todo-api --resource-group my-rg \
  --secrets "db-conn=Server=prod-db;Database=todos;..."

# ── Kubernetes Deployment Manifest ────────────────────────────────────────────
# kubernetes/deployment.yaml (abbreviated — key sections)
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: todo-api
          image: ghcr.io/yourusername/todo-api:sha-abc1234
          ports:
            - containerPort: 8080
          env:
            - name: ASPNETCORE_ENVIRONMENT
              value: Production
            - name: ConnectionStrings__DefaultConnection
              valueFrom:
                secretKeyRef:
                  name: todo-api-secrets
                  key: db-connection-string
          livenessProbe:              # uses ASP.NET Core /health/live endpoint
            httpGet: { path: /health/live, port: 8080 }
            initialDelaySeconds: 15
            periodSeconds: 30
          readinessProbe:             # uses ASP.NET Core /health/ready endpoint
            httpGet: { path: /health/ready, port: 8080 }
            initialDelaySeconds: 5
            periodSeconds: 10