How to build derived bootc container images
The original Docker container model of using "layers" to model applications has been extremely successful. This project aims to apply the same technique for bootable host systems - using standard OCI/Docker containers as a transport and delivery format for base operating system updates.
With bootable containers, you can build and customize the entire host OS with the same tools as for application containers. That means you can build on top of base bootc images with Dockerfiles and tailor the OS to your needs.
Best Practices
Multi-stage builds
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.
/etc/alternatives
At the present, /etc/alternatives
do not work in the fedora-bootc
image
(see upstream tracker).
In case you run into this issue, you may use symlinks. For golang
the symlink may look as follows:
FROM quay.io/fedora/fedora-bootc:40
RUN dnf -y golang && dnf clean all
RUN ln -sfr /usr/lib/golang/bin/go /usr/bin/go
# Further steps to compile a go project
Multi-stage builds may be another alternative.
Container metadata
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.
Lifecycle binding code and configuration
At the current time, the role of bootc
is solely to boot and
upgrade from a single container image. This is a very simplistic
model, but it is one that captures many use cases.
In particular, the default assumption is that code and configuration for the base OS are tightly bound. Systems which update one or the other asynchronously often lead to problems with skew.
Containerized vs 1:1 host:app
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.
httpd (bound)
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.
FROM quay.io/fedora/fedora-bootc:40
# The default package drops content in /var/www, and on bootc systems
# we have /var as a machine-local mount by default. Because this content
# should be read-only (at runtime) and versioned with the container image,
# we move it to /usr/share/www instead.
RUN dnf -y install httpd && \
systemctl enable httpd && \
mv /var/www /usr/share/www && \
echo 'd /var/log/httpd 0700 - - -' > /usr/lib/tmpfiles.d/httpd-log.conf && \
sed -ie 's,/var/www,/usr/share/www,' /etc/httpd/conf/httpd.conf
# Further, we also disable the default index.html which includes the operating
# system information (bad idea from a fingerprinting perspective), and crucially
# we inject our own content as part of the container image build.
# This is a key point: In this model, the webserver content is lifecycled exactly
# with the container image build, and you can change it "day 2" by updating
# the image. The content is underneath the /usr readonly bind mount - it
# should not be mutated per machine.
RUN rm /usr/share/httpd/noindex -rf
COPY index.html /usr/share/www/html
EXPOSE 80
httpd (containerized)
In contrast, this example demonstrates a webserver as a "referenced" container image via podman-systemd that is also configured for automatic updates.
This reference example is maintained in app-podman-systemd.
[Unit]
Description=Run a demo webserver
[Container]
# This image happens to be multiarch and somewhat maintained
Image=docker.io/library/caddy
PublishPort=80:80
AutoUpdate=registry
[Install]
WantedBy=default.target
# In this example, a simple "podman-systemd" unit which runs
# an application container via https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html
# that is also configured for automatic updates via
# https://docs.podman.io/en/latest/markdown/podman-auto-update.1.html
FROM quay.io/centos-bootc/centos-bootc:stream9
COPY caddy.container /usr/share/containers/systemd
# Enable the simple "automatic update containers" timer, in the same way
# that there is a simplistic bootc upgrade timer. However, you can
# obviously also customize this as you like; for example, using
# other tooling like Watchtower or explicit out-of-band control over container
# updates via e.g. Ansible or other custom logic.
RUN systemctl enable podman-auto-update.timer
Authentication, users and groups
The container images above are just illustrative demonstrations that are not useful standalone. It is highly likely that you will want to run other container images, and perform other customizations.
Among the most likely additions is configuring a mechanism for remote SSH; see Authentication, Users, and Groups.
General configuration guidance
See the bootc upstream guidance.
Many configuration changes to a Linux system boil down effectively to
writing configuration files into /etc
or /usr
- those operations
translate seamlessly into booted hosts via a COPY
instruction
or similar in a container build.
More examples
See Examples for many examples of container image definitions!
Want to help? Learn how to contribute to Fedora Docs ›