docker

Docker

Core Principles

1. Multi-stage builds always — Separate build and runtime stages. Build in the SDK image, run in the ASP.NET runtime image.
2. Non-root by default — .NET container images support USER app by default since .NET 8. Never run as root in production.
3. Layer caching matters — Copy .csproj files and restore before copying source code. This caches NuGet dependencies across builds.
4. Health probes at the orchestrator level — Expose a /health/live endpoint and let Kubernetes/Compose probe it. Chiseled and default aspnet images have no shell or curl, so in-image HEALTHCHECK commands have nothing to run with.

Patterns

Multi-Stage Dockerfile for Web API

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

# Copy project files and restore (cached layer)
COPY ["src/MyApp.Api/MyApp.Api.csproj", "src/MyApp.Api/"]
COPY ["src/MyApp.Domain/MyApp.Domain.csproj", "src/MyApp.Domain/"]
COPY ["Directory.Build.props", "."]
COPY ["Directory.Packages.props", "."]
RUN dotnet restore "src/MyApp.Api/MyApp.Api.csproj"

# Copy everything and build
COPY . .
RUN dotnet publish "src/MyApp.Api/MyApp.Api.csproj" \
    -c Release \
    -o /app/publish \
    --no-restore

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

# Non-root user (default in .NET 8+ images)
USER app

COPY --from=build /app/publish .

EXPOSE 8080

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

Container Health Probes

Prefer orchestrator-level probes (Kubernetes livenessProbe, Compose healthcheck) over a Dockerfile HEALTHCHECK — the standard aspnet and chiseled images ship no shell, no curl, and no wget, so there is nothing inside the container to run the probe with. Point the orchestrator at /health/live:

# docker-compose — probe from outside the app process
services:
  api:
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:8080/health/live || exit 1"]
      interval: 30s
      timeout: 3s
      retries: 3
# Note: CMD-SHELL requires a shell + wget in the image. Use a non-chiseled
# variant for this, or better: let Kubernetes httpGet probes do it —
# they run from the kubelet, needing nothing inside the image.