Skip to content

docs: Add a section in the Rust guide to use DHI #23728

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
edithturn wants to merge 12 commits into
base: main
Choose a base branch
from
+229 −71
Open

docs: Add a section in the Rust guide to use DHI #23728

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
9ca5425
Add a DHI section to the Rust guide with DHI-based Dockerfile example
edithturn Nov 16, 2025
62a3794
Updated Rust Version from 1.71.1 to the latest 1.91.1
edithturn Nov 22, 2025
b772b34
Update build output
edithturn Nov 22, 2025
21f4de5
Merge branch 'docker:main' into rust-dhi
edithturn Jan 2, 2026
8caefe4
docs: update Rust build guide for public Docker Hardened Images
edithturn Jan 2, 2026
175dd2f
Update content/guides/rust/build-images.md
edithturn Jan 8, 2026
ae49ec2
Merge branch 'docker:main' into rust-dhi
edithturn Jan 11, 2026
b09eafb
Fix DHI image to a valid alpine version
edithturn Jan 17, 2026
aa6e660
Change Dockerfile to DHI image
edithturn Jan 17, 2026
c49c7c0
Update guide for Rust DHI images and DOI
edithturn Jan 18, 2026
cbdc0ac
Fix docker build proper name
edithturn Jan 18, 2026
8e64cb5
Remove one space in command
edithturn Jan 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
239 changes: 202 additions & 37 deletions content/guides/rust/build-images.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ This utility will walk you through creating the following files with sensible de
Let's get started!

? What application platform does your project use? Rust
? What version of Rust do you want to use? 1.70.0
? What version of Rust do you want to use? 1.92.0
? What port does your server listen on? 8000
```

Expand All @@ -62,6 +62,165 @@ directory:
- compose.yaml
- README.Docker.md

## Choose a base image

Before editing your Dockerfile, you need to choose a base image. You can use the [Rust Docker Official Image](https://hub.docker.com/_/rust),
or a [Docker Hardened Image (DHI)](https://hub.docker.com/hardened-images/catalog/dhi/rust).

Docker Hardened Images (DHIs) are minimal, secure, and production-ready base images maintained by Docker.
They help reduce vulnerabilities and simplify compliance. For more details, see [Docker Hardened Images](/dhi/).

{{< tabs >}}
Copy link
Contributor

@craig-osterhout craig-osterhout Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like there's only one tab. Suggest using 2 tabs, one for doi/docker init, and one for dhi. For example, see the bun guide at https://raw.githubusercontent.com/docker/docs/refs/heads/main/content/guides/bun/containerize.md

Copy link
Author

@edithturn edithturn Jan 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I created two tabs and tested both of them. One for DHI and the other for DOI! Thank you!

{{< tab name="Using Docker Hardened Images" >}}

Docker Hardened Images (DHIs) are publicly available and can be used directly as base images.
To pull Docker Hardened Images, authenticate once with Docker:

```bash
docker login dhi.io
```

Use DHIs from the dhi.io registry, for example:

```bash
FROM dhi.io/rust:${RUST_VERSION}-alpine3.22-dev AS build
```

The following Dockerfile is equivalent to the one generated by `docker init`, but it uses a Rust DHI as the build base image:

```dockerfile {title=Dockerfile}
# Make sure RUST_VERSION matches the Rust version
ARG RUST_VERSION=1.92
ARG APP_NAME=docker-rust-hello

################################################################################
# Create a stage for building the application.
################################################################################

FROM dhi.io/rust:${RUST_VERSION}-alpine3.22-dev AS build
ARG APP_NAME
WORKDIR /app

# Install host build dependencies.
RUN apk add --no-cache clang lld musl-dev git

# Build the application.
RUN --mount=type=bind,source=src,target=src \
--mount=type=bind,source=Cargo.toml,target=Cargo.toml \
--mount=type=bind,source=Cargo.lock,target=Cargo.lock \
--mount=type=cache,target=/app/target/ \
--mount=type=cache,target=/usr/local/cargo/git/db \
--mount=type=cache,target=/usr/local/cargo/registry/ \
cargo build --locked --release && \
cp ./target/release/$APP_NAME /bin/server

################################################################################
# Create a new stage for running the application that contains the minimal
# We use dhi.io/static for the final stage because it’s a minimal Docker Hardened Image runtime (basically “just # enough OS to run the binary”), which helps keep the image small and with a lower attack surface compared to a # # full Alpine/Debian runtime.
################################################################################

FROM dhi.io/static:20250419 AS final

# Create a non-privileged user that the app will run under.
ARG UID=10001
RUN adduser \
--disabled-password \
--gecos "" \
--home "/nonexistent" \
--shell "/sbin/nologin" \
--no-create-home \
--uid "${UID}" \
appuser
USER appuser

# Copy the executable from the "build" stage.
COPY --from=build /bin/server /bin/

# Configure rocket to listen on all interfaces.
ENV ROCKET_ADDRESS=0.0.0.0

# Expose the port that the application listens on.
EXPOSE 8000

# What the container should run when it is started.
CMD ["/bin/server"]

```

{{< /tab >}}
{{< tab name="Using the Docker Official Images" >}}

```dockerfile {title=Dockerfile}
# Pin the Rust toolchain version used in the build stage.
ARG RUST_VERSION=1.92

# Name of the compiled binary produced by Cargo (must match Cargo.toml package name).
ARG APP_NAME=docker-rust-hello

################################################################################
# Build stage (DOI Rust image)
# This stage compiles the application.
################################################################################

FROM docker.io/library/rust:${RUST_VERSION}-alpine AS build

# Re-declare args inside the stage if you want to use them here.
ARG APP_NAME

# All build steps happen inside /app.
WORKDIR /app

# Install build dependencies needed to compile Rust crates on Alpine
RUN apk add --no-cache clang lld musl-dev git

# Build the application
RUN --mount=type=bind,source=src,target=src \
--mount=type=bind,source=Cargo.toml,target=Cargo.toml \
--mount=type=bind,source=Cargo.lock,target=Cargo.lock \
--mount=type=cache,target=/app/target/ \
--mount=type=cache,target=/usr/local/cargo/git/db \
--mount=type=cache,target=/usr/local/cargo/registry/ \
cargo build --locked --release && \
cp ./target/release/$APP_NAME /bin/server

################################################################################
# Runtime stage (DOI Alpine image)
# This stage runs the already-compiled binary with minimal dependencies.
################################################################################

FROM docker.io/library/alpine:3.18 AS final

# Create a non-privileged user (recommended best practice)
ARG UID=10001
RUN adduser \
--disabled-password \
--gecos "" \
--home "/nonexistent" \
--shell "/sbin/nologin" \
--no-create-home \
--uid "${UID}" \
appuser

# Drop privileges for runtime.
USER appuser

# Copy only the compiled binary from the build stage.
COPY --from=build /bin/server /bin/

# Rocket: listen on all interfaces inside the container.
ENV ROCKET_ADDRESS=0.0.0.0

# Document the port your app listens on.
EXPOSE 8000

# Start the application.
CMD ["/bin/server"]
```
{{< /tab >}}
{{< /tabs >}}



For building an image, only the Dockerfile is necessary. Open the Dockerfile
in your favorite IDE or text editor and see what it contains. To learn more
about Dockerfiles, see the [Dockerfile reference](/reference/dockerfile.md).
Expand All @@ -85,33 +244,40 @@ Docker uses "latest" as its default tag.
Build the Docker image.

```console
$ docker build --tag docker-rust-image .
$ docker build --tag docker-rust-image-dhi .
```

You should see output like the following.

```console
[+] Building 62.6s (14/14) FINISHED
=> [internal] load .dockerignore 0.1s
=> => transferring context: 2B 0.0s
=> [internal] load build definition from Dockerfile 0.1s
=> => transferring dockerfile: 2.70kB 0.0s
=> resolve image config for docker.io/docker/dockerfile:1 2.3s
=> CACHED docker-image://docker.io/docker/dockerfile:1@sha256:39b85bbfa7536a5feceb7372a0817649ecb2724562a38360f4d6a7782a409b14 0.0s
=> [internal] load metadata for docker.io/library/debian:bullseye-slim 1.9s
=> [internal] load metadata for docker.io/library/rust:1.70.0-slim-bullseye 1.7s
=> [build 1/3] FROM docker.io/library/rust:1.70.0-slim-bullseye@sha256:585eeddab1ec712dade54381e115f676bba239b1c79198832ddda397c1f 0.0s
=> [internal] load build context 0.0s
=> => transferring context: 35.29kB 0.0s
=> [final 1/3] FROM docker.io/library/debian:bullseye-slim@sha256:7606bef5684b393434f06a50a3d1a09808fee5a0240d37da5d181b1b121e7637 0.0s
=> CACHED [build 2/3] WORKDIR /app 0.0s
=> [build 3/3] RUN --mount=type=bind,source=src,target=src --mount=type=bind,source=Cargo.toml,target=Cargo.toml --mount= 57.7s
=> CACHED [final 2/3] RUN adduser --disabled-password --gecos "" --home "/nonexistent" --shell "/sbin/nologin" 0.0s
=> CACHED [final 3/3] COPY --from=build /bin/server /bin/ 0.0s
=> exporting to image 0.0s
=> => exporting layers 0.0s
=> => writing image sha256:f1aa4a9f58d2ecf73b0c2b7f28a6646d9849b32c3921e42adc3ab75e12a3de14 0.0s
=> => naming to docker.io/library/docker-rust-image
[+] Building 1.4s (13/13) FINISHED docker:desktop-linux
=> [internal] load build definition from Dockerfile 0.0s
=> => transferring dockerfile: 1.67kB 0.0s
=> [internal] load metadata for dhi.io/static:20250419 1.1s
=> [internal] load metadata for dhi.io/rust:1.92-alpine3.22-dev 1.2s
=> [auth] static:pull token for dhi.io 0.0s
=> [auth] rust:pull token for dhi.io 0.0s
=> [internal] load .dockerignore 0.0s
=> => transferring context: 646B 0.0s
=> [build 1/3] FROM dhi.io/rust:1.92-alpine3.22-dev@sha256:49eb72825a9e15fe48f2c4875a63c7e7f52a5b430bb52b8254b91d132aa5bf38 0.0s
=> => resolve dhi.io/rust:1.92-alpine3.22-dev@sha256:49eb72825a9e15fe48f2c4875a63c7e7f52a5b430bb52b8254b91d132aa5bf38 0.0s
=> [final 1/2] FROM dhi.io/static:20250419@sha256:74fc43fa240887b8159970e434244039aab0c6efaaa9cf044004cdc22aa2a34d 0.0s
=> => resolve dhi.io/static:20250419@sha256:74fc43fa240887b8159970e434244039aab0c6efaaa9cf044004cdc22aa2a34d 0.0s
=> [internal] load build context 0.0s
=> => transferring context: 117B 0.0s
=> CACHED [build 2/3] WORKDIR /build 0.0s
=> CACHED [build 3/3] RUN --mount=type=bind,source=src,target=src --mount=type=bind,source=Cargo.toml,target=Cargo.toml --mount=type=bind,source=Cargo.lock,target=Cargo 0.0s
=> CACHED [final 2/2] COPY --from=build /build/target/release/docker-rust-hello /server 0.0s
=> exporting to image 0.1s
=> => exporting layers 0.0s
=> => exporting manifest sha256:cc937bbdd712ef6e5445501f77e02ef8455ef64c567598786d46b7b21a4d4fa8 0.0s
=> => exporting config sha256:077507b483af4b5e1a928e527e4bb3a4aaf0557e1eea81cd39465f564c187669 0.0s
=> => exporting attestation manifest sha256:11b60e7608170493da1fdd88c120e2d2957f2a72a22edbc9cfbdd0dd37d21f89 0.0s
=> => exporting manifest list sha256:99a1b925a8d6ebf80e376b8a1e50cd806ec42d194479a3375e1cd9d2911b4db9 0.0s
=> => naming to docker.io/library/docker-rust-image-dhi:latest 0.0s
=> => unpacking to docker.io/library/docker-rust-image-dhi:latest 0.0s

View build details: docker-desktop://dashboard/build/desktop-linux/desktop-linux/yczk0ijw8kc5g20e8nbc8r6lj
```

## View local images
Expand All @@ -122,11 +288,11 @@ To list images, run the `docker images` command.

```console
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
docker-rust-image latest 8cae92a8fbd6 3 minutes ago 123MB
IMAGE ID DISK USAGE CONTENT SIZE EXTRA
docker-rust-image-dhi:latest 99a1b925a8d6 11.6MB 2.45MB U
```

You should see at least one image listed, including the image you just built `docker-rust-image:latest`.
You should see at least one image listed, including the image you just built `docker-rust-image-dhi:latest`.

## Tag images

Expand All @@ -146,31 +312,29 @@ Now, run the `docker images` command to see a list of the local images.

```console
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
docker-rust-image latest 8cae92a8fbd6 4 minutes ago 123MB
docker-rust-image v1.0.0 8cae92a8fbd6 4 minutes ago 123MB
rust latest be5d294735c6 4 minutes ago 113MB
IMAGE ID DISK USAGE CONTENT SIZE EXTRA
docker-rust-image-dhi:latest 99a1b925a8d6 11.6MB 2.45MB U
docker-rust-image-dhi:v1.0.0 99a1b925a8d6 11.6MB 2.45MB U
```

You can see that two images start with `docker-rust-image`. You know they're the same image because if you take a look at the `IMAGE ID` column, you can see that the values are the same for the two images.
You can see that two images start with `docker-rust-image-dhi`. You know they're the same image because if you take a look at the `IMAGE ID` column, you can see that the values are the same for the two images.

Remove the tag you just created. To do this, use the `rmi` command. The `rmi` command stands for remove image.

```console
$ docker rmi docker-rust-image:v1.0.0
Untagged: docker-rust-image:v1.0.0
$ docker rmi docker-rust-image-dhi:v1.0.0
Untagged: docker-rust-image-dhi:v1.0.0
```

Note that the response from Docker tells you that Docker didn't remove the image, but only "untagged" it. You can check this by running the `docker images` command.

```console
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
docker-rust-image latest 8cae92a8fbd6 6 minutes ago 123MB
rust latest be5d294735c6 6 minutes ago 113MB
IMAGE ID DISK USAGE CONTENT SIZE EXTRA
docker-rust-image-dhi:latest 99a1b925a8d6 11.6MB 2.45MB U
```

Docker removed the image tagged with `:v1.0.0`, but the `docker-rust-image:latest` tag is available on your machine.
Docker removed the image tagged with `:v1.0.0`, but the `docker-rust-image-dhi:latest` tag is available on your machine.

## Summary

Expand All @@ -182,6 +346,7 @@ Related information:
- [.dockerignore file](/reference/dockerfile.md#dockerignore-file)
- [docker init CLI reference](/reference/cli/docker/init.md)
- [docker build CLI reference](/reference/cli/docker/buildx/build.md)
- [Docker Hardened Images](/dhi/)

## Next steps

Expand Down
Loading