$ run as a normal user# run as root (or with sudo)
Skills in this chapter
- Build, install, update and roll back image-mode systems with bootc
Know image mode
Package mode changes a server package by package. Image mode replaces the whole system image in one transaction.
| Package mode | Image mode | |
|---|---|---|
| Build | Install, then change the running server | Build an image in a Containerfile, before deployment |
| Update | dnf update (many small changes) | bootc upgrade: the new image, all or nothing |
| Undo | Hard (dnf history undo per transaction) | bootc rollback: boot the old image |
| Same on every server | Only with good automation | Yes: every server runs the same image |
| Good for | Classic servers, many different jobs | Edge devices, appliances, many identical servers |
How the file system works on an image-mode system:
| Path | Behaviour |
|---|---|
/usr | Comes from the image, read-only |
/etc | Comes from the image; your local changes are kept and merged at updates |
/var | Local data, kept across updates (logs, databases, /var/home) |
Remember
In image mode you do not dnf install on the server. You add the package to the Containerfile and build a new image.
Write the Containerfile
Start FROM the RHEL bootc base image and add your packages, files and settings.
FROM registry.redhat.io/rhel10/rhel-bootc:10.0
# Software for this server role
RUN dnf -y install httpd firewalld && dnf clean all
# Configuration (files in /etc and /usr are part of the image)
COPY motd /etc/motd
COPY web.conf /etc/httpd/conf.d/web.conf
RUN systemctl enable httpd firewalld
# Web content in /usr, because /var is not updated by new images
COPY html/ /usr/share/web/html/DocumentRoot "/usr/share/web/html"
<Directory "/usr/share/web/html">
Require all granted
</Directory>Watch out
Files you put in /var in the Containerfile are copied only at the first installation. Later images do not change /var on the server. Put content that comes with the image in /usr (or /etc).
Build and test the image
Build it like any container image. You can even start it as a normal container to test the software before you make a disk from it.
podman login registry.redhat.io
cd ~/web-bootc
podman build -t quay.io/s0sta/web-bootc:1.0 .
podman images quay.io/s0sta/web-bootc
podman run --rm quay.io/s0sta/web-bootc:1.0 rpm -q httpd
httpd-2.4.63-1.el10.x86_64
podman run --rm quay.io/s0sta/web-bootc:1.0 bootc container lint
podman push quay.io/s0sta/web-bootc:1.0bootc container lint checks the image for common mistakes before you deploy it.
Make a disk image with bootc-image-builder
bootc-image-builder turns the container image into a disk or installer image: qcow2 (KVM), raw, vmdk, ami (AWS) or anaconda-iso. It runs as a privileged container.
[[customizations.user]]
name = "admin"
password = "ChangeMe-2026"
key = "ssh-ed25519 AAAAC3Nza...k9 admin@laptop"
groups = ["wheel"]podman pull quay.io/s0sta/web-bootc:1.0
mkdir -p output
podman run --rm -it --privileged --pull=newer \
--security-opt label=type:unconfined_t \
-v ./config.toml:/config.toml:ro \
-v ./output:/output \
-v /var/lib/containers/storage:/var/lib/containers/storage \
registry.redhat.io/rhel10/bootc-image-builder:latest \
--type qcow2 \
quay.io/s0sta/web-bootc:1.0
ls output/qcow2/
disk.qcow2- The builder reads the image from root's container storage, so pull (or build) it as root first.
config.tomladds users and SSH keys to the disk image only — not to the container image.
Install an image-mode system
Boot the disk image, or install with Anaconda and a Kickstart file that points to the image.
cp output/qcow2/disk.qcow2 /var/lib/libvirt/images/web1.qcow2
virt-install --name web1 --memory 2048 --vcpus 2 --import \
--disk /var/lib/libvirt/images/web1.qcow2 --os-variant rhel10.0 --graphics noneWith Kickstart, the ostreecontainer command replaces %packages:
text
zerombr
clearpart --all --initlabel
autopart --type=lvm
network --bootproto=dhcp --activate
ostreecontainer --url quay.io/s0sta/web-bootc:1.0
rootpw --lock
user --name=admin --groups=wheel --iscrypted --password=$6$...
rebootCheck, update and roll back
On the server, bootc status shows the booted image and a staged or rollback image. bootc upgrade gets a newer build of the same image; bootc switch moves to another image.
sudo bootc status
sudo bootc upgrade --check
sudo bootc upgrade
sudo bootc upgrade --apply
sudo bootc switch quay.io/s0sta/web-bootc:2.0
sudo bootc rollback
systemctl list-timers bootc-fetch-apply-updates.timer| Command | What it does |
|---|---|
bootc status | Booted, staged and rollback images, with versions |
bootc upgrade --check | Is there a newer image? Download only the metadata |
bootc upgrade | Download and stage the new image; it is used at the next reboot |
bootc upgrade --apply | Stage it and reboot at once |
bootc switch IMAGE | Use another image (another tag or repository) from now on |
bootc rollback | Boot the previous image at the next reboot |
The update flow for a whole fleet:
- Change the Containerfile, build
:2.0, test it. - Push it (or move the tag the servers follow, for example
:prod). - The servers pick it up with
bootc upgrade(or the automatic timer) and reboot. - Problem?
bootc rollbackand reboot — the old system is back in minutes.
Make a quick change for testing
/usr is read-only. For a short test (a debug tool), bootc usr-overlay adds a temporary writable layer that is gone at the next reboot.