diff --git a/content/guides/dotnet/containerize.md b/content/guides/dotnet/containerize.md index 146874ca9d8c..1383675c764b 100644 --- a/content/guides/dotnet/containerize.md +++ b/content/guides/dotnet/containerize.md @@ -39,12 +39,31 @@ $ git clone https://github.com/docker/docker-dotnet-sample ## Initialize Docker assets -Now that you have an application, you can use `docker init` to create the -necessary Docker assets to containerize your application. Inside the -`docker-dotnet-sample` directory, run the `docker init` command in a terminal. -`docker init` provides some default configuration, but you'll need to answer a -few questions about your application. Refer to the following example to answer -the prompts from `docker init` and use the same answers for your prompts. +Now that you have an application, you can create the necessary Docker assets to containerize it. You can choose between using the official .NET images or Docker Hardened Images (DHI). + +> [Docker Hardened Images (DHIs)](https://docs.docker.com/dhi/) are minimal, secure, and production-ready container base and application images maintained by Docker. DHI images are recommended for better security—they are designed to reduce vulnerabilities and simplify compliance. + +{{< tabs >}} +{{< tab name="Using Docker Hardened Images" >}} + +Docker Hardened Images (DHIs) for .NET are available in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/aspnetcore). Docker Hardened Images are freely available to everyone with no subscription required. You can pull and use them like any other Docker image after signing in to the DHI registry. For more information, see the [DHI quickstart](/dhi/get-started/) guide. + +1. Sign in to the DHI registry: + ```console + $ docker login dhi.io + ``` + +2. Pull the .NET SDK DHI (check the catalog for available versions): + ```console + $ docker pull dhi.io/dotnet:10-sdk + ``` + +3. Pull the ASP.NET Core runtime DHI (check the catalog for available versions): + ```console + $ docker pull dhi.io/aspnetcore:10 + ``` + +You can use `docker init` to generate Docker assets, then modify the Dockerfile to use DHI images: ```console $ docker init @@ -60,10 +79,86 @@ Let's get started! ? What application platform does your project use? ASP.NET Core ? What's the name of your solution's main project? myWebApp -? What version of .NET do you want to use? 8.0 +? What version of .NET do you want to use? 10.0 ? What local port do you want to use to access your server? 8080 ``` +In the following Dockerfile, the `FROM` instructions use `dhi.io/dotnet:10-sdk` and `dhi.io/aspnetcore:10` as the base images. + +```dockerfile {title=Dockerfile} +# syntax=docker/dockerfile:1 + +FROM --platform=$BUILDPLATFORM dhi.io/dotnet:10-sdk AS build +ARG TARGETARCH +COPY . /source +WORKDIR /source/src +RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \ + dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app + +FROM dhi.io/aspnetcore:10 +WORKDIR /app +COPY --from=build /app . +ENTRYPOINT ["dotnet", "myWebApp.dll"] +``` + +> [!NOTE] +> +> DHI runtime images already run as a non-root user (`nonroot`, UID 65532), so there's no need to create a user or specify `USER` in your Dockerfile. This reduces the attack surface and simplifies your configuration. + +{{< /tab >}} +{{< tab name="Using the official .NET 10 image" >}} + +You can use `docker init` to create the necessary Docker assets. Inside the `docker-dotnet-sample` directory, run the `docker init` command in a terminal. `docker init` provides some default configuration, but you'll need to answer a few questions about your application. Refer to the following example to answer the prompts from `docker init` and use the same answers for your prompts. + +```console +$ docker init +Welcome to the Docker Init CLI! + +This utility will walk you through creating the following files with sensible defaults for your project: + - .dockerignore + - Dockerfile + - compose.yaml + - README.Docker.md + +Let's get started! + +? What application platform does your project use? ASP.NET Core +? What's the name of your solution's main project? myWebApp +? What version of .NET do you want to use? 10.0 +? What local port do you want to use to access your server? 8080 +``` + +This generates a Dockerfile using the official .NET 10 images from Microsoft Container Registry: + +```dockerfile {title=Dockerfile} +# syntax=docker/dockerfile:1 + +FROM --platform=$BUILDPLATFORM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS build +ARG TARGETARCH +COPY . /source +WORKDIR /source/src +RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \ + dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app + +FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final +WORKDIR /app +COPY --from=build /app . +ARG UID=10001 +RUN adduser \ + --disabled-password \ + --gecos "" \ + --home "/nonexistent" \ + --shell "/sbin/nologin" \ + --no-create-home \ + --uid "${UID}" \ + appuser +USER appuser +ENTRYPOINT ["dotnet", "myWebApp.dll"] +``` + +{{< /tab >}} +{{< /tabs >}} + You should now have the following contents in your `docker-dotnet-sample` directory. @@ -78,7 +173,7 @@ directory. │ └── README.md ``` -To learn more about the files that `docker init` added, see the following: +To learn more about the files, see the following: - [Dockerfile](/reference/dockerfile.md) - [.dockerignore](/reference/dockerfile.md#dockerignore-file) - [compose.yaml](/reference/compose-file/_index.md) @@ -126,6 +221,7 @@ Related information: - [Dockerfile reference](/reference/dockerfile.md) - [.dockerignore file reference](/reference/dockerfile.md#dockerignore-file) - [Docker Compose overview](/manuals/compose/_index.md) + - [Docker Hardened Images](/dhi/) ## Next steps diff --git a/content/guides/dotnet/develop.md b/content/guides/dotnet/develop.md index c37a1950cd42..92929432808e 100644 --- a/content/guides/dotnet/develop.md +++ b/content/guides/dotnet/develop.md @@ -288,11 +288,11 @@ immediately reflected in the running container. Open `docker-dotnet-sample/src/Pages/Index.cshtml` in an IDE or text editor and update the student name text on line 13 from `Student name is` to `Student name:`. ```diff --

Student Name is @Model.StudentName

+-

Student name is @Model.StudentName

+

Student name: @Model.StudentName

``` -Save the changes to `Index.cshmtl` and then wait a few seconds for the application to rebuild. Refresh [http://localhost:8080](http://localhost:8080) in your browser and verify that the updated text appears. +Save the changes to `Index.cshtml` and then wait a few seconds for the application to rebuild. Refresh [http://localhost:8080](http://localhost:8080) in your browser and verify that the updated text appears. Press `ctrl+c` in the terminal to stop your application. @@ -304,22 +304,49 @@ Add a new development stage to your Dockerfile and update your `compose.yaml` fi The following is the updated Dockerfile. +{{< tabs >}} +{{< tab name="Using Docker Hardened Images" >}} + ```Dockerfile {hl_lines="10-13"} # syntax=docker/dockerfile:1 -FROM --platform=$BUILDPLATFORM mcr.microsoft.com/dotnet/sdk:8.0-alpine AS build +FROM --platform=$BUILDPLATFORM dhi.io/dotnet:10-sdk AS build ARG TARGETARCH COPY . /source WORKDIR /source/src RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \ dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app -FROM mcr.microsoft.com/dotnet/sdk:8.0-alpine AS development +FROM dhi.io/dotnet:10-sdk AS development COPY . /source WORKDIR /source/src CMD dotnet run --no-launch-profile -FROM mcr.microsoft.com/dotnet/aspnet:8.0-alpine AS final +FROM dhi.io/aspnetcore:10 +WORKDIR /app +COPY --from=build /app . +ENTRYPOINT ["dotnet", "myWebApp.dll"] +``` + +{{< /tab >}} +{{< tab name="Using the official .NET 10 image" >}} + +```Dockerfile {hl_lines="10-13"} +# syntax=docker/dockerfile:1 + +FROM --platform=$BUILDPLATFORM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS build +ARG TARGETARCH +COPY . /source +WORKDIR /source/src +RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \ + dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app + +FROM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS development +COPY . /source +WORKDIR /source/src +CMD dotnet run --no-launch-profile + +FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final WORKDIR /app COPY --from=build /app . ARG UID=10001 @@ -335,6 +362,9 @@ USER appuser ENTRYPOINT ["dotnet", "myWebApp.dll"] ``` +{{< /tab >}} +{{< /tabs >}} + The following is the updated `compose.yaml` file. ```yaml {hl_lines=[5,15,16]} @@ -379,7 +409,7 @@ secrets: file: db/password.txt ``` -Your containerized application will now use the `mcr.microsoft.com/dotnet/sdk:8.0-alpine` image, which includes development tools like `dotnet test`. Continue to the next section to learn how you can run `dotnet test`. +Your containerized application will now use the SDK image (either `dhi.io/dotnet:10-sdk` for DHI or `mcr.microsoft.com/dotnet/sdk:10.0-alpine` for official images), which includes development tools like `dotnet test`. Continue to the next section to learn how you can run `dotnet test`. ## Summary diff --git a/content/guides/dotnet/run-tests.md b/content/guides/dotnet/run-tests.md index 1e404c345965..daa78458e613 100644 --- a/content/guides/dotnet/run-tests.md +++ b/content/guides/dotnet/run-tests.md @@ -36,7 +36,7 @@ You should see output that contains the following. Starting test execution, please wait... A total of 1 test files matched the specified pattern. -Passed! - Failed: 0, Passed: 1, Skipped: 0, Total: 1, Duration: < 1 ms - /source/tests/bin/Debug/net8.0/tests.dll (net8.0) +Passed! - Failed: 0, Passed: 1, Skipped: 0, Total: 1, Duration: < 1 ms - /source/tests/bin/Debug/net10.0/tests.dll (net10.0) ``` To learn more about the command, see [docker compose run](/reference/cli/docker/compose/run/). @@ -47,10 +47,38 @@ To run your tests when building, you need to update your Dockerfile. You can cre The following is the updated Dockerfile. +{{< tabs >}} +{{< tab name="Using Docker Hardened Images" >}} + +```dockerfile {hl_lines="9"} +# syntax=docker/dockerfile:1 + +FROM --platform=$BUILDPLATFORM dhi.io/dotnet:10-sdk AS build +ARG TARGETARCH +COPY . /source +WORKDIR /source/src +RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \ + dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app +RUN dotnet test /source/tests + +FROM dhi.io/dotnet:10-sdk AS development +COPY . /source +WORKDIR /source/src +CMD dotnet run --no-launch-profile + +FROM dhi.io/aspnetcore:10 +WORKDIR /app +COPY --from=build /app . +ENTRYPOINT ["dotnet", "myWebApp.dll"] +``` + +{{< /tab >}} +{{< tab name="Using the official .NET 10 image" >}} + ```dockerfile {hl_lines="9"} # syntax=docker/dockerfile:1 -FROM --platform=$BUILDPLATFORM mcr.microsoft.com/dotnet/sdk:8.0-alpine AS build +FROM --platform=$BUILDPLATFORM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS build ARG TARGETARCH COPY . /source WORKDIR /source/src @@ -58,12 +86,12 @@ RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \ dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app RUN dotnet test /source/tests -FROM mcr.microsoft.com/dotnet/sdk:8.0-alpine AS development +FROM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS development COPY . /source WORKDIR /source/src CMD dotnet run --no-launch-profile -FROM mcr.microsoft.com/dotnet/aspnet:8.0-alpine AS final +FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final WORKDIR /app COPY --from=build /app . ARG UID=10001 @@ -79,6 +107,9 @@ USER appuser ENTRYPOINT ["dotnet", "myWebApp.dll"] ``` +{{< /tab >}} +{{< /tabs >}} + Run the following command to build an image using the build stage as the target and view the test results. Include `--progress=plain` to view the build output, `--no-cache` to ensure the tests always run, and `--target build` to target the build stage. ```console @@ -92,16 +123,16 @@ You should see output containing the following. #11 1.564 Determining projects to restore... #11 3.421 Restored /source/src/myWebApp.csproj (in 1.02 sec). #11 19.42 Restored /source/tests/tests.csproj (in 17.05 sec). -#11 27.91 myWebApp -> /source/src/bin/Debug/net8.0/myWebApp.dll -#11 28.47 tests -> /source/tests/bin/Debug/net8.0/tests.dll -#11 28.49 Test run for /source/tests/bin/Debug/net8.0/tests.dll (.NETCoreApp,Version=v8.0) +#11 27.91 myWebApp -> /source/src/bin/Debug/net10.0/myWebApp.dll +#11 28.47 tests -> /source/tests/bin/Debug/net10.0/tests.dll +#11 28.49 Test run for /source/tests/bin/Debug/net10.0/tests.dll (.NETCoreApp,Version=v10.0) #11 28.67 Microsoft (R) Test Execution Command Line Tool Version 17.3.3 (x64) #11 28.67 Copyright (c) Microsoft Corporation. All rights reserved. #11 28.68 #11 28.97 Starting test execution, please wait... #11 29.03 A total of 1 test files matched the specified pattern. #11 32.07 -#11 32.08 Passed! - Failed: 0, Passed: 1, Skipped: 0, Total: 1, Duration: < 1 ms - /source/tests/bin/Debug/net8.0/tests.dll (net8.0) +#11 32.08 Passed! - Failed: 0, Passed: 1, Skipped: 0, Total: 1, Duration: < 1 ms - /source/tests/bin/Debug/net10.0/tests.dll (net10.0) #11 DONE 32.2s ``` diff --git a/content/guides/nodejs/containerize.md b/content/guides/nodejs/containerize.md index 16f22245234b..a2326c073ce2 100644 --- a/content/guides/nodejs/containerize.md +++ b/content/guides/nodejs/containerize.md @@ -323,9 +323,17 @@ Choosing DHI offers the advantage of a production-ready image that is lightweigh {{< tabs >}} {{< tab name="Using Docker Hardened Images" >}} -Docker Hardened Images (DHIs) are available for Node.js on [Docker Hub](https://hub.docker.com/hardened-images/catalog/dhi/node). Unlike using the Docker Official Image, you must first mirror the Node.js image into your organization and then use it as your base image. Follow the instructions in the [DHI quickstart](/dhi/get-started/) to create a mirrored repository for Node.js. +Docker Hardened Images (DHIs) are available for Node.js in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/node). Docker Hardened Images are freely available to everyone with no subscription required. You can pull and use them like any other Docker image after signing in to the DHI registry. For more information, see the [DHI quickstart](/dhi/get-started/) guide. -Mirrored repositories must start with `dhi-`, for example: `FROM /dhi-node:`. In the following Dockerfile, the `FROM` instruction uses `/dhi-node:24-alpine3.22-dev` as the base image. +1. Sign in to the DHI registry: + + $ docker login dhi.io + +2. Pull the Node.js DHI (check the catalog for available versions): + + $ docker pull dhi.io/node:24-alpine3.22-dev + +In the following Dockerfile, the `FROM` instruction uses `dhi.io/node:24-alpine3.22-dev` as the base image. ```dockerfile # ======================================== @@ -333,7 +341,7 @@ Mirrored repositories must start with `dhi-`, for example: `FROM /dhi-node:24-alpine3.22-dev AS base +FROM dhi.io/node:24-alpine3.22-dev AS base # Set working directory WORKDIR /app @@ -419,7 +427,7 @@ CMD ["npm", "run", "dev:docker"] # ======================================== # Production Stage # ======================================== -FROM /dhi-node:24-alpine3.22-dev AS production +FROM dhi.io/node:24-alpine3.22-dev AS production # Set working directory WORKDIR /app diff --git a/content/guides/python/containerize.md b/content/guides/python/containerize.md index fedc4b75237a..072537b1c972 100644 --- a/content/guides/python/containerize.md +++ b/content/guides/python/containerize.md @@ -14,7 +14,7 @@ aliases: ## Prerequisites - You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). -- You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client. +- You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. ## Overview @@ -314,8 +314,19 @@ venv.bak/ {{< /tab >}} {{< tab name="Using Docker Hardened Image" >}} -If you don't have Docker Desktop installed or prefer creating the assets -manually, you can create the following files in your project directory. +Docker Hardened Images (DHIs) are available for Python in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/python). Docker Hardened Images are freely available to everyone with no subscription required. You can pull and use them like any other Docker image after signing in to the DHI registry. For more information, see the [DHI quickstart](/dhi/get-started/) guide. + +1. Sign in to the DHI registry: + + ```console + $ docker login dhi.io + ``` + +2. Pull the Python DHI (check the catalog for available versions): + + ```console + $ docker pull dhi.io/python:3.12.12-debian13-fips-dev + ``` Create a file named `Dockerfile` with the following contents. @@ -331,7 +342,7 @@ Create a file named `Dockerfile` with the following contents. # This Dockerfile uses Docker Hardened Images (DHI) for enhanced security. # For more information, see https://docs.docker.com/dhi/ ARG PYTHON_VERSION=3.12.12-debian13-fips-dev -FROM /dhi-python:${PYTHON_VERSION} +FROM dhi.io/python:${PYTHON_VERSION} # Prevents Python from writing pyc files. ENV PYTHONDONTWRITEBYTECODE=1