Chapter 2. Building and testing RHEL bootc images

You can use a Containerfile to build and customize your own bootc-based image with the tools, configurations, and applications you need. While most standard instructions work, some are ignored when the image is installed on a system.

Figure 2.1. Building an image by using instructions from a Containerfile, testing the container, pushing an image to a registry, and sharing it with others

A general Containerfile structure is the following:

FROM registry.redhat.io/rhel9/rhel-bootc:latest

RUN dnf -y install [software] [dependencies] && dnf clean all

ADD [application]
ADD [configuration files]

RUN [config scripts]

The available commands that are usable inside a Containerfile and a Dockerfile are equivalent.

However, the following commands in a Containerfile are ignored when the rhel-9-bootc image is installed to a system:

The rhel-9-bootc container image reuses the OCI image format.

Red Hat Enterprise Linux (RHEL) now supports reproducible container builds using Podman and Buildah, reducing image changes with consistent inputs over time. This new feature decreases data pulled from registries when updating images, which is crucial for supply chain security, reliable software deployment, and effective debugging. Reproducible builds for RHEL containers reduce registry storage, create smaller update payloads, and enable faster downloads by ensuring image layers remain consistent. Previously, challenges with tarball creation and escalating container image sizes led to increased storage burdens and unnecessary layer pulls, even when underlying data remained unchanged, hindering faster updates in environments like rhel-bootc and RHEL AI.

To build an image by using instructions from a Containerfile, use the podman build command.

The deployment image must include only the application and its required runtime, without adding any build tools or unnecessary libraries. To achieve this, use a two-stage Containerfile: one stage for building the artifacts and another for hosting the application.

With multi-stage builds, you use multiple FROM instructions in your Containerfile. Each FROM instruction can use a different base, and each of them begins a new stage of the build. You can selectively copy artifacts from one stage to another and exclude everything you do not need in the final image.

Multi-stage builds offer several advantages:

The following Containerfile consists of two stages. The first stage is typically named builder and it compiles a golang binary. The second stage copies the binary from the first stage. The default working directory for the go-toolset builder is opt/ap-root/src.

FROM registry.access.redhat.com/ubi9/go-toolset:latest as builder
RUN echo 'package main; import "fmt"; func main() { fmt.Println("hello world") }' > helloworld.go
RUN go build helloworld.go

FROM registry.redhat.io/rhel9/rhel-bootc:latest
COPY --from=builder /opt/app-root/src/helloworld /
CMD ["/helloworld"]

As a result, the final container image includes the helloworld binary but no data from the previous stage.

You can also use multi-stage builds to perform the following scenarios:

$ podman build --target build -t hello .

For example, you can use this approach to debugging a specific build stage.

COPY --from=<image> <source_path> <destination_path>

FROM ubi9 AS stage1
[...]

FROM stage1 AS stage2
[...]

FROM ubi9 AS final-stage
[...]

To run and test your container, use the podman run command.

Red Hat Enterprise Linux (RHEL) base images, Universal Base Images (UBI), and rhel-bootc use version numbers that track only the major operating system version. To define a specific version number for a derived image, you can override this value by adding the version label to your Containerfile.

To push an image to your own registry, or a third-party registry, and share it with others, use the podman push command. The following procedure uses the Red Hat Quay registry as an example.