From scratch Fedora/CentOS bootc base container images
Creating "from scratch" base bootc images provides control the base image content, allowing you to own the OS stream and tailor the environment to suit specific needs and workflows.
While a core premise of the bootc model is that rich control over Linux system customization can be accomplished with a "default" container built with the provided base image that works on a wide range of environments and systems without any additional overhead associated with maintaining a from scratch base image. Also, as part of the default derivation, it is possible to swap the kernel and other fundamental components.
Default Container Build
FROM <base image>
RUN ...
However, some use cases want even more control. Specifically:
-
An organization building a bootc system may need to ensure the base image version carries a set of packages at exactly specific versions.
-
An organization may want to start from a minimal base image, adding only the necessary packages.
Goals
Exact content version control
As an organization deploying a bootc system, I may want to ensure the base image version carries a set of packages at exactly specific versions (perhaps defined by a lockfile, or an rpm-md repository). There are many tools which manage snapshots of yum (rpm-md) repositories.
There are currently issues where it won’t quite work to e.g.
dnf -y upgrade selinux-policy-targeted.
Building up from minimal
Today there is just one default image produced by the project, which is now known as "standard". It is roughly a headless server-oriented installation (although it can be used for desktops as well), and comes with a lot of opinionated packages for networking, CLI tooling, etc.
This project also has a "minimal" content set definition which is not currently shipped as a distinct container, but can be built from the standard image.
Considerations
Like layered bootc images that use the default base image, from scratch base images are still derived from the base container. They will not automatically consume changes to the default base image unless they are part of a container pipeline.
For more background on the bootc update model, see updating bootc images here and an overview of derived images here.
If you come from the "package" world, you may already use tools like Pulp/Satellte/Artifactory to set up "snapshots/versions" of packages in your base image and help bootc more seamlessly fit into your existing workflow.
If you come from the CoreOS world, this is a key difference when interacting with the base OS image. Read about the differences between Fedora CoreOS and Fedora bootc here.
Understanding the base image content
Most, but not all content from the base image comes from RPMs.
There is some additional non-RPM content, as well as postprocessing
that operates on the filesystem root. At the current time the
implementation of the base image build uses rpm-ostree,
but this is considered an implementation detail subject to change.
Using bootc-base-imagectl build-rootfs
The core operation is bootc-base-imagectl build-rootfs.
This command takes just one required argument:
-
A path to the target root filesystem which will be generated as a directory. The target should not already exist (but its parent must exist).
Additionally, --manifest can be provided to choose the input set of packages
and configuration. The two default images are:
-
standard: The default image. -
minimal: A quite small root content set, effectivelybootc,systemd,kernel,dnfplus their hard dependencies, as well as a small set of non-RPM content tweaks to e.g. enable systemd persistent journaling.
For more information on the available content sets, run bootc-base-imagectl list.
The set of packages is currently not officially supported to configure directly.
The general intention is that you can start from either image, and then add, change
or remove content from it in a secondary build phase. Especially building up from
the minimal image should cover many use cases that want to control the content
set to a high degree.
A key goal is that this avoids "forking" by default, ensuring that by default when we change the base image (adding new packages usually) or provide updates or fixes for the build operation, from scratch builds will inherit those changes by default.
A "source root" can also be provided to enable "cross builds". More on this below.
Build privileges required
We’re generating a new root filesystem, not modifying the existing container. This is most easily done by using container features (mount namespacing in particular) that is not enabled by default in many container build environments today.
In summary, you must provide at least these arguments to e.g. podman build:
--cap-add=all --security-opt=label=type:container_runtime_t --device /dev/fuse
It is a goal to reduce these required capabilities; see this tracker issue.
Note however ultimately the goal here is to deploy this container image as a base operating system on a physical or virtualized environment, where inherently more trust is required regardless.
Example: Generating a from scratch base image with exact version control
# Begin with a standard bootc base image that serves as a "builder" for our from scratch image.
FROM quay.io/centos-bootc/centos-bootc:stream10 as builder
# Configure and override source RPM repositories, if necessary. This step is required when referencing specific content views or target mirrored/snapshotted/pinned versions of content.
RUN rm -rf /etc/yum.repos.d/*
COPY mypinnedcontent.repo /etc/yum.repos.d/
# Build the root file system using the specified repositories and non-RPM content from the "builder" base image.
# If no repositories are defined, the default build will be used. You can modify the scope of packages in the base image by changing the manifest between the "standard" and "minimal" sets.
RUN /usr/libexec/bootc-base-imagectl build-rootfs --manifest=standard /target-rootfs
# Create a new, empty image from scratch.
FROM scratch
# Copy the root file system built in the previous step into this image.
COPY --from=builder /target-rootfs/ /
# Apply customizations to the image. This syntax uses "heredocs" https://www.docker.com/blog/introduction-to-heredocs-in-dockerfiles/ to pass multi-line arguments in a more readable format.
RUN <<EORUN
# Set pipefail to display failures within the heredoc and avoid false-positive successful builds.
set -xeuo pipefail
# Install necessary packages, run scripts, etc.
dnf -y install emacs
# Remove leftover build artifacts from installing packages in the final built image.
dnf clean all
rm /var/{log,cache,lib}/* -rf
# Run the bootc linter to avoid encountering certain bugs and maintain content quality. Place this as the final command in your last run invoaction.
bootc container lint
EORUN
# Define required labels for this bootc image to be recognized as such.
LABEL containers.bootc 1
LABEL ostree.bootable 1
# https://pagure.io/fedora-kiwi-descriptions/pull-request/52
ENV container=oci
# Optional labels that only apply when running this image as a container. These keep the default entry point running under systemd.
STOPSIGNAL SIGRTMIN+3
CMD ["/sbin/init"]
Example: Generating a custom minimal base image
# Begin with a standard bootc base image that is reused as a "builder" for the custom image.
FROM quay.io/centos-bootc/centos-bootc:stream10 as builder
# Configure and override source RPM repositories, if necessary. This step is not required when building up from minimal unless referencing specific content views or target mirrored/snapshotted/pinned versions of content.
# Add additional repositories to apply customizations to the image. However, referencing a custom manifest in this step is not currently supported without forking the code.
# Build the root file system using the specified repositories and non-RPM content from the "builder" base image.
# If no repositories are defined, the default build will be used. You can modify the scope of packages in the base image by changing the manifest between the "standard" and "minimal" sets.
RUN /usr/libexec/bootc-base-imagectl build-rootfs --manifest=minimal /target-rootfs
# Create a new, empty image from scratch.
FROM scratch
# Copy the root file system built in the previous step into this image.
COPY --from=builder /target-rootfs/ /
# Apply customizations to the image. This syntax uses "heredocs" https://www.docker.com/blog/introduction-to-heredocs-in-dockerfiles/ to pass multi-line arguments in a more readable format.
RUN <<EORUN
# Set pipefail to display failures within the heredoc and avoid false-positive successful builds.
set -xeuo pipefail
# Install required packages for our custom bootc image.
# Note that using a minimal manifest means we need to add critical components specific to our use case and environment.
# For example, install networking and SSH - not every use case will want SSH, so it's not included in minimal
dnf -y install NetworkManager openssh-server
# Remove leftover build artifacts from installing packages from the final built image.
dnf clean all
rm /var/{log,cache,lib}/* -rf
# Run the bootc linter to avoid encountering certain bugs and maintain content quality. Place this as the final command in your last run invoaction.
bootc container lint
EORUN
# Define required labels for this bootc image to be recognized as such.
LABEL containers.bootc 1
LABEL ostree.bootable 1
# https://pagure.io/fedora-kiwi-descriptions/pull-request/52
ENV container=oci
# Optional labels that only apply when running this image as a container. These keep the default entry point running under systemd.
STOPSIGNAL SIGRTMIN+3
CMD ["/sbin/init"]
Optimizing container images
This rechunk subcommand is not supported in rootless podman.
|
The output of the above will be an image with a single large layer (tarball), which means every change will result in copying (pushing to the registry, pulling for clients) the single large tarball.
There is support in rpm-ostree to take a large image like this and "rechunk" it. This process will optimize the ordering and grouping of installed packages into many layers in the final image, which provides better network efficiency since a number of layers may be reused without incurring a transfer.
The bootc-base-imagectl tool provides a rechunk subcommand to
interact with rpm-ostree and perform this rechunking. It is
recommended to use the bootc-base-imagectl rechunk command and not
rpm-ostree directly, since the implementation details may change in
the future.
Example:
Currently, bootc-base-imagectl is shipped as part of the
centos-stream bootc images. It is convenient to use these
pre-existing images in order to rechunk "from scratch" base images. This can
be done by mapping the host containers-storage into the container and
running bootc-base-imagectl within to do the rechunking operation.
A previously-built base image named
quay.io/exampleos/fedora-bootc:single can be optimized with the
following command (as root):
# podman run --rm --privileged -v /var/lib/containers:/var/lib/containers \
quay.io/centos-bootc/centos-bootc:stream10 \
/usr/libexec/bootc-base-imagectl rechunk \
quay.io/exampleos/fedora-bootc:single \
quay.io/exampleos/fedora-bootc:chunked
Custom layer assignment with user.component
The rechunker automatically groups files into layers based on RPM
package ownership. However, you can override this behavior using the
user.component extended attribute to assign specific files or
directories to custom-named layers.
This is useful when you have custom content (not from RPMs) that you want to group together for better layer caching and sharing across builds.
# Assign a single file to a custom layer
RUN setfattr -n user.component -v "my-apps" /usr/bin/my-custom-app
# Assign an entire directory tree to a layer
RUN setfattr -n user.component -v "my-lib" /usr/share/my-lib
When a directory has the user.component attribute set, all files and
subdirectories within it are automatically included in that layer.
You can override specific files or subdirectories by setting a
different user.component value on them:
RUN <<EORUN
set -euxo pipefail
mkdir -p /usr/share/my-lib/docs
# ... populate the directory ...
# All content under my-lib goes to "my-lib" layer
setfattr -n user.component -v "my-lib" /usr/share/my-lib
# Override: docs go to a separate "docs" layer
setfattr -n user.component -v "docs" /usr/share/my-lib/docs
EORUN
Layers created via user.component are given priority over the
automatic package-based layers during rechunking.
|
The default systemd target
The base images boot to graphical.target, because that is where systemd’s
packaged default.target symlink points and nothing in the base images
changes it. They include no display manager, so in practice this only adds
graphical.target itself and the few units it pulls in (such as
udisks2.service) on top of multi-user.target.
Disk images made with bootc-image-builder (such as
qcow2 or raw) and systems installed with bootc install keep this
default. Anaconda installs, including bootc-image-builder’s anaconda-iso,
do not: Anaconda writes its own /etc/systemd/system/default.target,
replacing any default target set in the image. For an image without a
display manager, that is multi-user.target unless the kickstart sets a
target. See
Installing on generic infrastructure for the
installation methods.
To choose the target yourself, set it in a derived image or in the customization step of the from scratch examples above:
FROM quay.io/fedora/fedora-bootc:44
RUN systemctl set-default multi-user.target
If you maintain your own rpm-ostree manifest, for example in a fork of the
base images repository, you can
set default-target: multi-user.target (also spelled default_target) in it
instead, which replaces the default.target symlink in
/usr/lib/systemd/system.
For Anaconda installs, set the target in the kickstart instead, for example
xconfig --startxonboot for graphical.target: the link Anaconda writes in
/etc overrides the one in the image, and is kept across updates.
The other Fedora image-based variants make their own choice:
-
Fedora CoreOS boots to
multi-user.target: a postprocess script in its manifest replaces thedefault.targetsymlink. -
Fedora IoT boots to
multi-user.target, set with thedefault_targetkey of its rpm-ostree manifest. -
The Fedora Atomic desktops boot to
graphical.target, set with thedefault_targetkey of their shared manifest, and include a display manager such as GDM.
Growing the root filesystem
Disk images are often booted on a disk larger than the image, for example
in the cloud. The standard base images grow the root partition and
filesystem to fill the disk at boot with
bootc-generic-growpart.service,
which comes from the
standard content set.
The minimal content set does not include it, so an image built from it,
such as the custom minimal image above, keeps the root at the size it was
installed with.
To add it, copy the service and its script from the standard image used as
the builder, and install cloud-utils-growpart, which provides the
growpart command the service needs. The unit has no [Install] section,
so enable it with a symlink rather than systemctl enable. In the custom
minimal image example above, that is:
FROM scratch
COPY --from=builder /target-rootfs/ /
COPY --from=builder /usr/libexec/bootc-generic-growpart /usr/libexec/
COPY --from=builder /usr/lib/systemd/system/bootc-generic-growpart.service /usr/lib/systemd/system/
RUN <<EORUN
set -xeuo pipefail
dnf -y install NetworkManager openssh-server cloud-utils-growpart
mkdir -p /usr/lib/systemd/system/local-fs.target.wants
ln -s ../bootc-generic-growpart.service /usr/lib/systemd/system/local-fs.target.wants/
# ... the rest of the customization step as above
EORUN
Copying from the builder keeps the files at the same version as the rest of
the image. An image derived from another base without the service can copy
them the same way from the matching standard image, such as
COPY --from=quay.io/centos-bootc/centos-bootc:stream10.
The service then behaves as in the standard image: it only runs in virtual machines, and leaves some storage setups such as LVM alone (see its page for details). For how growing the root works on a bootc system, see Expanding the root filesystem in the bootc documentation.
Want to help? Learn how to contribute to Fedora Docs ›