Chapter 2. Building and testing RHEL bootable container images

download PDF

The following procedures use Podman to build and test your container image. You can also use other tools, for example, OpenShift Container Platform. For more examples of configuring RHEL systems by using containers, see the rhel-bootc-examples repository.


Red Hat provides the rhel9/rhel-bootc container image as a Technology Preview. Technology Preview features provide early access to upcoming product innovations, enabling customers to test functionality and provide feedback during the development process. However, these features are not fully supported. Documentation for a Technology Preview feature might be incomplete or include only basic installation and configuration information. See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

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

639 RHEL Bootable Container Bifrost 0524 2

A general Containerfile structure is the following:


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

ADD [application]
ADD [configuration files]

RUN [config scripts]

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

  • The rhel-9-bootc container image ignores the container config section (Config) when it is installed to a system.
  • The rhel-9-bootc container image does not ignore the container config section (Config) when you run this image by using container runtimes such as podman or docker.

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

  • ENTRYPOINT and CMD (OCI: Entrypoint/Cmd): you can set CMD /sbin/init instead.
  • ENV (OCI: Env): change the systemd configuration to configure the global system environment.
  • EXPOSE (OCI: exposedPorts): it is independent of how the system firewall and network function at runtime.
  • USER (OCI: User): configure individual services inside the RHEL bootable container to run as unprivileged users instead.

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


Building custom rhel-bootc base images is not supported in this release.

2.1. Building a container image

Use the podman build command to build an image using instructions from a Containerfile.


  • The container-tools meta-package is installed.


  1. Create a Containerfile:

    $ cat Containerfile
    RUN dnf -y install cloud-init && \
        ln -s ../ /usr/lib/systemd/system/ && \
        dnf clean all

    This Containerfile example adds the cloud-init tool, so it automatically fetches SSH keys and can run scripts from the infrastructure and also gather configuration and secrets from the instance metadata. For example, you can use this container image for pre-generated AWS or KVM guest systems.

  2. Build the <image> image by using Containerfile in the current directory:

    $ podman build -t<namespace>/<image>:<tag>


  • List all images:

    $ podman images
    REPOSITORY                                  TAG      IMAGE ID       CREATED              SIZE
    localhost/<image>                           latest   b28cd00741b3   About a minute ago   2.1 GB

2.2. Running a container image

Use the podman run command to run and test your container.


  • The container-tools meta-package is installed.


  • Run the container named mybootc based on the<namespace>/<image>:<tag> container image:

    $ podman run -it --rm --name mybootc<namespace>/<image>:<tag> /bin/bash
    • The -i option creates an interactive session. Without the -t option, the shell stays open, but you cannot type anything to the shell.
    • The -t option opens a terminal session. Without the -i option, the shell opens and then exits.
    • The --rm option removes the<namespace>/<image>:<tag> container image after the container exits.


  • List all running containers:

    $ podman ps
    CONTAINER ID  IMAGE                                    COMMAND          CREATED        STATUS            PORTS   NAMES
    7ccd6001166e<namespace>/<image>:<tag>  /sbin/init  6 seconds ago  Up 5 seconds ago          mybootc

Additional resources

2.3. Pushing a container image to the registry

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


  • The container-tools meta-package is installed.
  • An image is built and available on the local system.
  • You have created the Red Hat Quay registry. For more information see Proof of Concept - Deploying Red Hat Quay.


  • Push the<namespace>/<image>:<tag> container image from your local storage to the registry:

    $ podman push<namespace>/<image>:<tag>

Additional resources

Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.