From 4b9e859ab15aa2f40b0514d379df706755a613a3 Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Wed, 17 Jun 2026 13:52:06 +0200
Subject: [PATCH] docs: Revamp image requirements

Closes: https://github.com/bootc-dev/bootc/issues/2237

Signed-off-by: Colin Walters <walters@verbum.org>
---
 docs/src/bootc-images.md | 128 +++++++++++----------------------------
 1 file changed, 37 insertions(+), 91 deletions(-)

diff --git a/docs/src/bootc-images.md b/docs/src/bootc-images.md
index 58a459c75f..be6c52b7c4 100644
--- a/docs/src/bootc-images.md
+++ b/docs/src/bootc-images.md
@@ -7,91 +7,66 @@ activity.
 However, there are a number of basic requirements and integration
 points, some of which have distribution-specific variants.
 
-Further at the current time, the bootc project makes a lot
-of use of ostree, and this can appear in the base image
-requirements.
+## Generic requirements (composefs or ostree backends)
 
-## ostree-in-container
+### `/sysroot`
 
-With [bootc 1.1.3](https://github.com/bootc-dev/bootc/releases/tag/v1.1.3)
-or later, it is no longer required to have a `/ostree` directory
-present in the base image.
+Your container image must have a `/sysroot` directory - this is where the "physical root" will be mounted. The permissions (mode) should generally be the same as `/usr` i.e. `0755` or similar.
 
-To generate container images which do include `/ostree` from scratch,
-the underlying `ostree container` tooling is designed to operate
-on an existing ostree commit, and the `ostree container encapsulate`
-command can turn the commit into an OCI image. If you already
-have a pipeline which prdouces ostree commits as an output
-(e.g. using [osbuild](https://www.osbuild.org/guides/image-builder-on-premises/building-ostree-images.html)
- to produce `ostree` commit artifacts), then this allows a
-seamless transition to a bootc/OCI compatible ecosystem.
+### `LABEL containers.bootc=1` 
 
-## Higher level base image build tooling
+The rationale for this required label is that many higher level tools which expect to operate only on bootc-compatible OCI images will want to be able to present only compatible images. 
 
-A well tested tool to produce compatible base images is 
-[`rpm-ostree compose image`](https://coreos.github.io/rpm-ostree/container/#creating-base-images),
-which is used by the [Fedora base image](https://gitlab.com/fedora/bootc/base-images).
+### Kernel (split)
 
-## Standard image content
+The Linux kernel (and optionally initramfs) is embedded in the container image; the canonical location is `/usr/lib/modules/$kver/vmlinuz`, and the initramfs should be in `initramfs.img` in that directory. You should *not* include any content in `/boot` in your container image. Bootc will take care of copying the kernel/initramfs as needed from the container image to `/boot`.
 
-The bootc project provides a [baseimage](https://github.com/bootc-dev/bootc/tree/main/baseimage) reference
-set of configuration files for base images. In particular at
-the current time the content defined by `base` must be used
-(or recreated). There is also suggested integration there with
-e.g. `dracut` to ensure the initramfs is set up, etc.
+### Kernel (sealed UKI)
 
-## Standard metadata for bootc compatible images
+For the composefs backend, the UKI must be located at `/boot/EFI/Linux/$kver.efi`.
 
-It is strongly recommended to do:
+### /ostree symlink and `bootc container lint`
 
-```dockerfile
-LABEL containers.bootc 1
-```
+This is [a bug](https://github.com/bootc-dev/bootc/issues/2256): currently a `/ostree -> /sysroot/ostree` symlink is required just for `bootc container lint` to pass, even though it's not required for `/sysroot/ostree` to exist.
+
+## composefs backend
 
-This will signal that this image is intended to be usable with `bootc`.
+There are no strict additional basic filesystem/layout requirements for images which plan to deploy with composefs. However, see also [bootloaders](bootloaders.md).
 
-## Deriving from existing base images
+## ostree backend
 
-It's important to emphasize that from one
-of these specially-formatted base images, every
-tool and technique for container building applies!
-In other words it will Just Work to do
+### `prepare-root.conf`
 
-```Dockerfile
-FROM <bootc base image>
-RUN dnf -y install foo && dnf clean all
+The upstream ostree builds today do not default to composefs. You must enable this via a `prepare-root.conf`:
+
+```
+[composefs]
+enabled = true
 ```
 
-You can then use `podman build`, `buildah`, `docker build`, or any other container
-build tool to produce your customized image. The only requirement is that the
-container build tool supports producing OCI container images.
+This is checked by `bootc container lint`.
 
-## Kernel
+### Historical usage of `/ostree`
 
-The Linux kernel (and optionally initramfs) is embedded in the container image; the canonical location
-is `/usr/lib/modules/$kver/vmlinuz`, and the initramfs should be in `initramfs.img`
-in that directory. You should *not* include any content in `/boot` in your container image.
-Bootc will take care of copying the kernel/initramfs as needed from the container image to
-`/boot`.
+Some images include a `/ostree` directory. A requirement for this was dropped in [bootc 1.1.3](https://github.com/bootc-dev/bootc/releases/tag/v1.1.3), and it is recommended that new images do not include it.
 
-Future work for supporting UKIs will follow the recommendations of the uapi-group in [Locations for Distribution-built UKIs Installed by Package Managers](https://uapi-group.org/specifications/specs/unified_kernel_image/#locations-for-distribution-built-ukis-installed-by-package-managers).
+## Suggested image content
 
-The `bootc container lint` command will check this.
+The bootc project provides a [baseimage](https://github.com/bootc-dev/bootc/tree/main/baseimage) reference
+set of configuration files for base images. In particular at
+the current time the content defined by `base` must be used
+(or recreated). There is also suggested integration there with
+e.g. `dracut` to ensure the initramfs is set up, etc.
 
-## The `ostree container commit` command
+The `bootc container lint` command will check this.
 
-You may find some references to this; it is no longer very useful
-and is not recommended.
+## SELinux
 
-## The bootloader setup
+The default mechanism for labeling today is that bootc will load the file contexts from the image (e.g. `/etc/selinux/policy`) and apply labels dynamically. This is the only mechanism that will work today with a generic bootc-unaware build tooling.
 
-At the current time bootc relies on the [bootupd](https://github.com/coreos/bootupd/)
-project which handles bootloader installs and upgrades.  The invocation of
-`bootc install` will always run `bootupd` to perform installations.
-Additionally, `bootc upgrade` will currently not upgrade the bootloader;
-you must invoke `bootupctl update`.
+It is not supported to add `security.selinux` extended attributes into the OCI tar layers, though support for this may be added if requested.
 
-## SELinux
+### More details
 
 Container runtimes such as `podman` and `docker` commonly
 apply a "coarse" SELinux policy to running containers.
@@ -103,12 +78,9 @@ are *dynamically* generated per container invocation,
 and there are no individually distinct e.g. `etc_t` and
 `usr_t` types.
 
-In contrast, with the current OSTree backend for bootc,
-it is possible to include label metadata (and precomputed ostree
-checksums) in special metadata files in `/sysroot/ostree` that correspond
-to components of the base image. This is optional as of bootc v1.1.3.
+### `/ostree`
 
-File content in derived layers will be labeled using the default file
+Only with the ostree backend, there is support for including the ostree commit metadata in the OCI image, which includes all xattrs. File content in derived layers will be labeled using the default file
 contexts (from `/etc/selinux`). For example, you can do this (as of
 bootc 1.1.0):
 
@@ -126,29 +98,3 @@ RUN chcon -t foo_t /usr/bin/foo
 
 Because the container runtime state will deny the attempt to
 "physically" set the `security.selinux` extended attribute.
-
-In the future, it is likely however that we add support
-for handling the `security.selinux` extended attribute in tar
-streams; but this can only currently be done with a custom
-build process.
-
-### Toplevel directories
-
-In particular, a common problem is that inside a container image,
-it's easy to create arbitrary toplevel directories such as
-e.g. `/app` or `/aimodel` etc.  But in some SELinux policies
-such as Fedora derivatives, these will be labeled as `default_t`
-which few domains can access.
-
-References:
-
-- <https://github.com/ostreedev/ostree-rs-ext/issues/510>
-
-## composefs
-
-It is strongly recommended to enable the ostree composefs
-backend (but not strictly required) for bootc.
-
-A reference enablement file to do so is in the base image content referenced above.
-
-More in [ostree-prepare-root](https://ostreedev.github.io/ostree/man/ostree-prepare-root.html).
