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
wants to merge 1 commit into
base: main
Choose a base branch
from
+164 −28
Open

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
192 changes: 164 additions & 28 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.71.1
? What port does your server listen on? 8000
```

Expand All @@ -62,6 +62,140 @@ 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 >}}
{{< tab name="Using Docker Hardened Images" >}}

Docker Hardened Images (DHIs) are available for Rust in the Hardened Image catalog. Unlike the official image, you must first mirror the Rust DHI into your Docker organization.
Follow the [DHI quickstart](/dhi/get-started/) to mirror the `dhi-rust` repository. Mirrored repositories must start with `dhi-`, for example:
`FROM <your-namespace>/dhi-rust:${RUST_VERSION}-alpine`.

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.71.1
ARG APP_NAME=docker-rust-hello

################################################################################
# Create a stage for building the application.
FROM <your-namespace>/dhi-rust:${RUST_VERSION}-alpine 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

################################################################################
# Runtime stage with minimal dependencies.
FROM alpine:3.18 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 official Rust image" >}}

By default, docker init creates a multi-stage Dockerfile that uses the official Rust image
in the build stage and Alpine as the runtime image. For example:

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

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

FROM rust:${RUST_VERSION}-alpine 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

################################################################################
# Runtime stage with minimal dependencies.
FROM alpine:3.18 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 >}}
{{< /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 Down Expand Up @@ -91,27 +225,30 @@ $ docker build --tag docker-rust-image .
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 2.2s (18/18) FINISHED
=> [internal] load build definition from Dockerfile 0.0s
=> => transferring dockerfile: 2.92kB 0.0s
=> resolve image config for docker-image://docker.io/docker/dockerfile:1 1.2s
=> [auth] docker/dockerfile:pull token for registry-1.docker.io 0.0s
=> => resolve docker.io/docker/dockerfile:1@sha256:b6afd42430b15f2d2a4c5a02b919e98a525b785b1aaff16747d2f623364e39b6 0.0s
=> [internal] load metadata for docker.io/library/alpine:3.18 0.8s
=> [internal] load metadata for docker.io/library/rust:1.71.1-alpine 0.7s
=> [auth] library/rust:pull token for registry-1.docker.io 0.0s
=> [auth] library/alpine:pull token for registry-1.docker.io 0.0s
=> [internal] load .dockerignore 0.0s
=> => transferring context: 683B 0.0s
=> [build 1/4] FROM docker.io/library/rust:1.71.1-alpine@sha256:3419c5212b75ce4e7786b71bd2bd49587a2481f8b42ca685d719d265a11c7e96 0.0s
=> => resolve docker.io/library/rust:1.71.1-alpine@sha256:3419c5212b75ce4e7786b71bd2bd49587a2481f8b42ca685d719d265a11c7e96 0.0s
=> [final 1/3] FROM docker.io/library/alpine:3.18@sha256:de0eb0b3f2a47ba1eb89389859a9bd88b28e82f5826b6969ad604979713c2d4f 0.0s
=> => resolve docker.io/library/alpine:3.18@sha256:de0eb0b3f2a47ba1eb89389859a9bd88b28e82f5826b6969ad604979713c2d4f 0.0s
=> [internal] load build context 0.0s
=> => transferring context: 265B 0.0s
=> exporting to image 0.0s
=> => exporting layers 0.0s
=> => exporting manifest sha256:0c9f89589c2bf35bbeb642222fe8c42d2479ee6e9c9028a57aeeacf591aa5375 0.0s
=> => exporting config sha256:09a032b66ff64682e6c4a74896017e33854169b5ceb0e51603597d1d2a68358d 0.0s
=> => naming to docker.io/library/docker-rust-image:latest 0.0s
=> => unpacking to docker.io/library/docker-rust-image:latest
```

## View local images
Expand All @@ -123,7 +260,7 @@ 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
docker-rust-image latest 0c9f89589c2b 3 minutes ago 123MB
```

You should see at least one image listed, including the image you just built `docker-rust-image:latest`.
Expand All @@ -147,9 +284,8 @@ 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
docker-rust-image latest 0c9f89589c2b 4 minutes ago 123MB
docker-rust-image v1.0.0 0c9f89589c2b 4 minutes ago 123MB
```

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.
Expand All @@ -166,8 +302,7 @@ Note that the response from Docker tells you that Docker didn't remove the image
```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
docker-rust-image latest 0c9f89589c2b 6 minutes ago 123MB
```

Docker removed the image tagged with `:v1.0.0`, but the `docker-rust-image:latest` tag is available on your machine.
Expand All @@ -182,6 +317,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