Docker

In simple words#

Learning objectives#

• Write a multi-stage Dockerfile for an API
• Choose a small, secure runtime image
• Configure ports, environment and health checks
• Run the API with SQL Server in Docker Compose

Explanation#

Build with the SDK image and run with the ASP.NET Core runtime image. Restore first (copy only the .csproj), then copy the source and publish — Docker caches the restore layer.

Chiseled Ubuntu images (mcr.microsoft.com/dotnet/aspnet:9.0-noble-chiseled) contain only what .NET needs: no shell, no package manager, non-root by default — smaller and with fewer vulnerabilities.

Images listen on port 8080 by default (ASPNETCORE_HTTP_PORTS). Terminate TLS at the ingress or load balancer; pass configuration with environment variables (ConnectionStrings__Shop, Jwt__Key from secrets).

Because chiseled images have no curl, health probes are configured in the orchestrator (Kubernetes, Container Apps) against /health, not with a Dockerfile HEALTHCHECK.

Docker Compose runs the API and SQL Server together for local development and integration tests; use named volumes for the database and a health check on SQL Server before starting the API.

Syntax#

1docker build -t shopsmart-api:1.0 .
2docker run -d -p 8080:8080 -e ConnectionStrings__Shop="…" shopsmart-api:1.0
3curl http://localhost:8080/health

Code example: Dockerfile for the ShopSmart API#

1# ── Build ──
2FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
3WORKDIR /src
4COPY ShopSmart.Api/ShopSmart.Api.csproj ShopSmart.Api/
5RUN dotnet restore ShopSmart.Api/ShopSmart.Api.csproj
6COPY . .
7RUN dotnet publish ShopSmart.Api/ShopSmart.Api.csproj -c Release -o /app/publish --no-restore /p:UseAppHost=false
8

9# ── Runtime: chiseled = no shell, no package manager, non-root ──
10FROM mcr.microsoft.com/dotnet/aspnet:9.0-noble-chiseled AS final
11WORKDIR /app
12COPY --from=build /app/publish .
13ENV ASPNETCORE_ENVIRONMENT=Production \
14    ASPNETCORE_HTTP_PORTS=8080
15EXPOSE 8080
16ENTRYPOINT ["dotnet", "ShopSmart.Api.dll"]

docker build produces an image of roughly 120 MB (the SDK stage is discarded). docker run -p 8080:8080 starts the API as a non-root user; curl http://localhost:8080/health returns “Healthy” and http://localhost:8080/api/products returns JSON.

This example is illustrative. Copy or download it and run it in your own environment; the expected output is shown above.

Step-by-step explanation#

1. Restoring with only the .csproj copied lets Docker reuse that layer until dependencies change.
2. dotnet publish creates a framework-dependent build in /app/publish.
3. The chiseled runtime image is small and already runs as a non-root user.
4. ASPNETCORE_HTTP_PORTS=8080 matches EXPOSE; TLS is handled outside the container.
5. All other settings (connection strings, JWT keys) arrive as environment variables or mounted secrets at runtime.

Real-world use case#

Common mistakes#

Best practices#

• Multi-stage builds with cached restore
• Chiseled runtime images for APIs
• Probes on /health in the orchestrator
• Secrets and connection strings at runtime

Remember this#

Practice exercise#

1services:
2  db:
3    image: mcr.microsoft.com/mssql/server:2022-latest
4    environment:
5      ACCEPT_EULA: "Y"
6      MSSQL_SA_PASSWORD: ${SA_PASSWORD}
7    volumes:
8      - sqldata:/var/opt/mssql
9    healthcheck:
10      test: ["CMD-SHELL", "/opt/mssql-tools18/bin/sqlcmd -C -S localhost -U sa -P \"$MSSQL_SA_PASSWORD\" -Q 'SELECT 1' || exit 1"]
11      interval: 10s
12      retries: 10
13

14  api:
15    build: .
16    ports:
17      - "5080:8080"
18    environment:
19      ConnectionStrings__Shop: "Server=db;Database=ShopSmart;User Id=sa;Password=${SA_PASSWORD};TrustServerCertificate=True"
20    depends_on:
21      db:
22        condition: service_healthy
23

24volumes:
25  sqldata:

Mini quiz#

Want more? Practise all ASP.NET Core Web API MCQs · ASP.NET Core Web API interview questions

Related topics#

My notes#

Saved in this browser.