How to build derived bootc container images

Bootc containers are shipped as ordinary OCI containers and are intended to be usable as part of a container build process, but are primarily designed to run on booted physical/virtual machines via bootc. Hence, there is a number of things to consider when building and running bootc OCI containers.

There is a number of systemd services that setup the filesystem, among other things. For instance, the root’s home directory is not present but created by a systemd service on boot/init. That implies that a bootc container is not always the best environment to, for instance, compile a project. We recommend multi-stage builds for that purpose and compile the source in a build stage from which build artifacts can be copied into the final stage to create a derived image.

Do not attempt to invoke dnf -y update (or upgrade) in general. While some things will work correctly, others will not (especially at the moment kernel and bootloader updates). We will aim to fix much of this over time, but still you should instead prefer only explicitly pulling in updates (or reversions) that you need.

The secondary reason to avoid this: Often people choose image-based updates for their predicability, and you can easily "pin" the base image by digest for example. The default for dnf repositories is to "float" - so what happens with an image build today could be different tomorrow. Packages can be locked with extra effort.

We recommend running the bootc container lint command as a final stage during a container build in Containerfile. This command will perform a number of checks inside the container image and throw an error in case of issues.

While one can add Container configuration metadata (e.g., environment, exposed ports, default users) to an OCI container image, bootc generally ignores that. In practice, that means that certain things may work when being run as an ordinary OCI container via Podman but won’t work once booted. For instance, you may use the ENV foo=bar instruction in a Container file which will be visible in a Podman container but it won’t be propagated to the booted system.

For details and recommendations, please refer to the bootc-runtime documentation.

A webserver is the classic case of something that can be run as a container on a generic host alongside other workloads. However, many systems today still follow a "1:1" model between application and a virtual machine. Migrating to a container build for this can be an important stepping stone into eventually lifting the workload into an application container itself.

Additionally in practice, even some containerized workloads have such strong bindings/requirememnts for the host system that they effectively require a 1:1 binding. Production databases often fall into this class.

Nevertheless, here’s a classic static http webserver example; an illustrative aspect is that we move content from /var into /usr. It expects an index.html colocated with the Containerfile.

In contrast, this example demonstrates a webserver as a "referenced" container image via podman-systemd that is also configured for automatic updates.