Skip to content

Commit 9ca5425

Browse files
edithturnedithturn
committed
Add a DHI section to the Rust guide with DHI-based Dockerfile example
1 parent e21ee9d commit 9ca5425

File tree

1 file changed

+164
-28
lines changed

1 file changed

+164
-28
lines changed

‎content/guides/rust/build-images.md‎

Lines changed: 164 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ This utility will walk you through creating the following files with sensible de
5050
Let's get started!
5151

5252
? What application platform does your project use? Rust
53-
? What version of Rust do you want to use? 1.70.0
53+
? What version of Rust do you want to use? 1.71.1
5454
? What port does your server listen on? 8000
5555
```
5656

@@ -62,6 +62,140 @@ directory:
6262
- compose.yaml
6363
- README.Docker.md
6464

65+
## Choose a base image
66+
67+
Before editing your Dockerfile, you need to choose a base image. You can use the [Rust Docker Official Image](https://hub.docker.com/_/rust),
68+
or a [Docker Hardened Image (DHI)](https://hub.docker.com/hardened-images/catalog/dhi/rust).
69+
70+
Docker Hardened Images (DHIs) are minimal, secure, and production-ready base images maintained by Docker.
71+
They help reduce vulnerabilities and simplify compliance. For more details, see [Docker Hardened Images](/dhi/).
72+
73+
{{< tabs >}}
74+
{{< tab name="Using Docker Hardened Images" >}}
75+
76+
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.
77+
Follow the [DHI quickstart](/dhi/get-started/) to mirror the `dhi-rust` repository. Mirrored repositories must start with `dhi-`, for example:
78+
`FROM <your-namespace>/dhi-rust:${RUST_VERSION}-alpine`.
79+
80+
The following Dockerfile is equivalent to the one generated by `docker init`, but it uses a Rust DHI as the build base image:
81+
82+
```dockerfile {title=Dockerfile}
83+
# Make sure RUST_VERSION matches the Rust version
84+
ARG RUST_VERSION=1.71.1
85+
ARG APP_NAME=docker-rust-hello
86+
87+
################################################################################
88+
# Create a stage for building the application.
89+
FROM <your-namespace>/dhi-rust:${RUST_VERSION}-alpine AS build
90+
ARG APP_NAME
91+
WORKDIR /app
92+
93+
# Install host build dependencies.
94+
RUN apk add --no-cache clang lld musl-dev git
95+
96+
# Build the application.
97+
RUN --mount=type=bind,source=src,target=src \
98+
--mount=type=bind,source=Cargo.toml,target=Cargo.toml \
99+
--mount=type=bind,source=Cargo.lock,target=Cargo.lock \
100+
--mount=type=cache,target=/app/target/ \
101+
--mount=type=cache,target=/usr/local/cargo/git/db \
102+
--mount=type=cache,target=/usr/local/cargo/registry/ \
103+
cargo build --locked --release && \
104+
cp ./target/release/$APP_NAME /bin/server
105+
106+
################################################################################
107+
# Runtime stage with minimal dependencies.
108+
FROM alpine:3.18 AS final
109+
110+
# Create a non-privileged user that the app will run under.
111+
ARG UID=10001
112+
RUN adduser \
113+
--disabled-password \
114+
--gecos "" \
115+
--home "/nonexistent" \
116+
--shell "/sbin/nologin" \
117+
--no-create-home \
118+
--uid "${UID}" \
119+
appuser
120+
USER appuser
121+
122+
# Copy the executable from the "build" stage.
123+
COPY --from=build /bin/server /bin/
124+
125+
# Configure rocket to listen on all interfaces.
126+
ENV ROCKET_ADDRESS=0.0.0.0
127+
# Expose the port that the application listens on.
128+
EXPOSE 8000
129+
130+
# What the container should run when it is started.
131+
CMD ["/bin/server"]
132+
133+
```
134+
{{< /tab >}}
135+
{{< tab name="Using the official Rust image" >}}
136+
137+
By default, docker init creates a multi-stage Dockerfile that uses the official Rust image
138+
in the build stage and Alpine as the runtime image. For example:
139+
140+
```dockerfile {title=Dockerfile}
141+
# Make sure RUST_VERSION matches the Rust version
142+
ARG RUST_VERSION=1.71.1
143+
ARG APP_NAME=docker-rust-hello
144+
145+
################################################################################
146+
# Create a stage for building the application.
147+
148+
FROM rust:${RUST_VERSION}-alpine AS build
149+
ARG APP_NAME
150+
WORKDIR /app
151+
152+
# Install host build dependencies.
153+
RUN apk add --no-cache clang lld musl-dev git
154+
155+
# Build the application.
156+
RUN --mount=type=bind,source=src,target=src \
157+
--mount=type=bind,source=Cargo.toml,target=Cargo.toml \
158+
--mount=type=bind,source=Cargo.lock,target=Cargo.lock \
159+
--mount=type=cache,target=/app/target/ \
160+
--mount=type=cache,target=/usr/local/cargo/git/db \
161+
--mount=type=cache,target=/usr/local/cargo/registry/ \
162+
cargo build --locked --release && \
163+
cp ./target/release/$APP_NAME /bin/server
164+
165+
################################################################################
166+
# Runtime stage with minimal dependencies.
167+
FROM alpine:3.18 AS final
168+
169+
# Create a non-privileged user that the app will run under.
170+
ARG UID=10001
171+
RUN adduser \
172+
--disabled-password \
173+
--gecos "" \
174+
--home "/nonexistent" \
175+
--shell "/sbin/nologin" \
176+
--no-create-home \
177+
--uid "${UID}" \
178+
appuser
179+
USER appuser
180+
181+
# Copy the executable from the "build" stage.
182+
COPY --from=build /bin/server /bin/
183+
184+
# Configure rocket to listen on all interfaces.
185+
ENV ROCKET_ADDRESS=0.0.0.0
186+
# Expose the port that the application listens on.
187+
EXPOSE 8000
188+
189+
# What the container should run when it is started.
190+
CMD ["/bin/server"]
191+
192+
```
193+
194+
{{< /tab >}}
195+
{{< /tabs >}}
196+
197+
198+
65199
For building an image, only the Dockerfile is necessary. Open the Dockerfile
66200
in your favorite IDE or text editor and see what it contains. To learn more
67201
about Dockerfiles, see the [Dockerfile reference](/reference/dockerfile.md).
@@ -91,27 +225,30 @@ $ docker build --tag docker-rust-image .
91225
You should see output like the following.
92226

93227
```console
94-
[+] Building 62.6s (14/14) FINISHED
95-
=> [internal] load .dockerignore 0.1s
96-
=> => transferring context: 2B 0.0s
97-
=> [internal] load build definition from Dockerfile 0.1s
98-
=> => transferring dockerfile: 2.70kB 0.0s
99-
=> resolve image config for docker.io/docker/dockerfile:1 2.3s
100-
=> CACHED docker-image://docker.io/docker/dockerfile:1@sha256:39b85bbfa7536a5feceb7372a0817649ecb2724562a38360f4d6a7782a409b14 0.0s
101-
=> [internal] load metadata for docker.io/library/debian:bullseye-slim 1.9s
102-
=> [internal] load metadata for docker.io/library/rust:1.70.0-slim-bullseye 1.7s
103-
=> [build 1/3] FROM docker.io/library/rust:1.70.0-slim-bullseye@sha256:585eeddab1ec712dade54381e115f676bba239b1c79198832ddda397c1f 0.0s
104-
=> [internal] load build context 0.0s
105-
=> => transferring context: 35.29kB 0.0s
106-
=> [final 1/3] FROM docker.io/library/debian:bullseye-slim@sha256:7606bef5684b393434f06a50a3d1a09808fee5a0240d37da5d181b1b121e7637 0.0s
107-
=> CACHED [build 2/3] WORKDIR /app 0.0s
108-
=> [build 3/3] RUN --mount=type=bind,source=src,target=src --mount=type=bind,source=Cargo.toml,target=Cargo.toml --mount= 57.7s
109-
=> CACHED [final 2/3] RUN adduser --disabled-password --gecos "" --home "/nonexistent" --shell "/sbin/nologin" 0.0s
110-
=> CACHED [final 3/3] COPY --from=build /bin/server /bin/ 0.0s
111-
=> exporting to image 0.0s
112-
=> => exporting layers 0.0s
113-
=> => writing image sha256:f1aa4a9f58d2ecf73b0c2b7f28a6646d9849b32c3921e42adc3ab75e12a3de14 0.0s
114-
=> => naming to docker.io/library/docker-rust-image
228+
[+] Building 2.2s (18/18) FINISHED
229+
=> [internal] load build definition from Dockerfile 0.0s
230+
=> => transferring dockerfile: 2.92kB 0.0s
231+
=> resolve image config for docker-image://docker.io/docker/dockerfile:1 1.2s
232+
=> [auth] docker/dockerfile:pull token for registry-1.docker.io 0.0s
233+
=> => resolve docker.io/docker/dockerfile:1@sha256:b6afd42430b15f2d2a4c5a02b919e98a525b785b1aaff16747d2f623364e39b6 0.0s
234+
=> [internal] load metadata for docker.io/library/alpine:3.18 0.8s
235+
=> [internal] load metadata for docker.io/library/rust:1.71.1-alpine 0.7s
236+
=> [auth] library/rust:pull token for registry-1.docker.io 0.0s
237+
=> [auth] library/alpine:pull token for registry-1.docker.io 0.0s
238+
=> [internal] load .dockerignore 0.0s
239+
=> => transferring context: 683B 0.0s
240+
=> [build 1/4] FROM docker.io/library/rust:1.71.1-alpine@sha256:3419c5212b75ce4e7786b71bd2bd49587a2481f8b42ca685d719d265a11c7e96 0.0s
241+
=> => resolve docker.io/library/rust:1.71.1-alpine@sha256:3419c5212b75ce4e7786b71bd2bd49587a2481f8b42ca685d719d265a11c7e96 0.0s
242+
=> [final 1/3] FROM docker.io/library/alpine:3.18@sha256:de0eb0b3f2a47ba1eb89389859a9bd88b28e82f5826b6969ad604979713c2d4f 0.0s
243+
=> => resolve docker.io/library/alpine:3.18@sha256:de0eb0b3f2a47ba1eb89389859a9bd88b28e82f5826b6969ad604979713c2d4f 0.0s
244+
=> [internal] load build context 0.0s
245+
=> => transferring context: 265B 0.0s
246+
=> exporting to image 0.0s
247+
=> => exporting layers 0.0s
248+
=> => exporting manifest sha256:0c9f89589c2bf35bbeb642222fe8c42d2479ee6e9c9028a57aeeacf591aa5375 0.0s
249+
=> => exporting config sha256:09a032b66ff64682e6c4a74896017e33854169b5ceb0e51603597d1d2a68358d 0.0s
250+
=> => naming to docker.io/library/docker-rust-image:latest 0.0s
251+
=> => unpacking to docker.io/library/docker-rust-image:latest
115252
```
116253

117254
## View local images
@@ -123,7 +260,7 @@ To list images, run the `docker images` command.
123260
```console
124261
$ docker images
125262
REPOSITORY TAG IMAGE ID CREATED SIZE
126-
docker-rust-image latest 8cae92a8fbd6 3 minutes ago 123MB
263+
docker-rust-image latest 0c9f89589c2b 3 minutes ago 123MB
127264
```
128265

129266
You should see at least one image listed, including the image you just built `docker-rust-image:latest`.
@@ -147,9 +284,8 @@ Now, run the `docker images` command to see a list of the local images.
147284
```console
148285
$ docker images
149286
REPOSITORY TAG IMAGE ID CREATED SIZE
150-
docker-rust-image latest 8cae92a8fbd6 4 minutes ago 123MB
151-
docker-rust-image v1.0.0 8cae92a8fbd6 4 minutes ago 123MB
152-
rust latest be5d294735c6 4 minutes ago 113MB
287+
docker-rust-image latest 0c9f89589c2b 4 minutes ago 123MB
288+
docker-rust-image v1.0.0 0c9f89589c2b 4 minutes ago 123MB
153289
```
154290

155291
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.
@@ -166,8 +302,7 @@ Note that the response from Docker tells you that Docker didn't remove the image
166302
```console
167303
$ docker images
168304
REPOSITORY TAG IMAGE ID CREATED SIZE
169-
docker-rust-image latest 8cae92a8fbd6 6 minutes ago 123MB
170-
rust latest be5d294735c6 6 minutes ago 113MB
305+
docker-rust-image latest 0c9f89589c2b 6 minutes ago 123MB
171306
```
172307

173308
Docker removed the image tagged with `:v1.0.0`, but the `docker-rust-image:latest` tag is available on your machine.
@@ -182,6 +317,7 @@ Related information:
182317
- [.dockerignore file](/reference/dockerfile.md#dockerignore-file)
183318
- [docker init CLI reference](/reference/cli/docker/init.md)
184319
- [docker build CLI reference](/reference/cli/docker/buildx/build.md)
320+
- [Docker Hardened Images](/dhi/)
185321

186322
## Next steps
187323

0 commit comments

Comments
 (0)