install/flat: Use composefs pipeline for rootfs

--flat install implementation will go through the composefs
repository. This gives several advantages:

- SELinux labeling is handled by composefs-rs (selabel), which applies
  labels from the image's file_contexts rather than inheriting the
  running container's labels.
- The kernel installation flow is reused from composefs-rs
  (get_boot_resources / UsrLibModulesVmlinuz).
- The composefs repo is preserved at /sysroot/composefs, making it
  easy to convert to immutable/bootc mode later. Users who don't want
  the metadata overhead can rm -rf /sysroot/composefs.
- write_to_path supports reflink copies on btrfs/XFS, sharing blocks
  with the composefs object store.
- --source-imgref now works with --flat (the in_host_mountns guard is
  removed since we pull via the image reference, not via cp /).

Signed-off-by: Eric Curtin <eric.curtin@docker.com>

Author: ericcurtin

ADOPTERS.md

@@ -7,11 +7,11 @@
 
 | Type | Name | Since | Website | Use-Case |
 |:-|:-|:-|:-|:-|
-Vendor | Red Hat | 2024 | https://redhat.com | Image Based Linux 
-Vendor | HeliumOS | 2024 | https://www.heliumos.org/ | An atomic desktop operating system for your devices
-Vendor | AlmaLinux (Atomic SIG) | 2025 | [atomic-desktop](https://github.com/AlmaLinux/atomic-desktop), [atomic-workstation](https://github.com/AlmaLinux/atomic-workstation) | Atomic AlmaLinux desktop respins
-Vendor | Caligra | 2025 | [workbench](https://caligra.com/workbench/) | An OS designed to accelerate knowledge work
-Vendor | CIQ | 2026 | https://ciq.com | Rocky Linux from CIQ (RLC) - Image Based Linux - Standard and Cloud variants
+| Vendor | Red Hat | 2024 | https://redhat.com | Image Based Linux |
+| Vendor | HeliumOS | 2024 | https://www.heliumos.org/ | An atomic desktop operating system for your devices |
+| Vendor | AlmaLinux (Atomic SIG) | 2025 | [atomic-desktop](https://github.com/AlmaLinux/atomic-desktop), [atomic-workstation](https://github.com/AlmaLinux/atomic-workstation) | Atomic AlmaLinux desktop respins |
+| Vendor | Caligra | 2025 | [workbench](https://caligra.com/workbench/) | An OS designed to accelerate knowledge work |
+| Vendor | CIQ | 2026 | https://ciq.com | Rocky Linux from CIQ (RLC) - Image Based Linux - Standard and Cloud variants |
 
 # bootc Adopters (indirect, via ostree)
 
@@ -24,13 +24,13 @@ is to be the successor to ostree, and it is our aim to seamlessly carry forward
 
 | Type | Name | Since | Website | Use-Case |
 |:-|:-|:-|:-|:-|
-| Vendor | Endless | 2014 | [link](https://www.endlessos.org/os) | A Completely Free, User-Friendly Operating System Packed with Educational Tools, Games, and More
-| Vendor | Red Hat | 2015 | [link](https://redhat.com) | Image Based Linux
-| Vendor | Apertis | 2020 | [link](https://apertis.org) | Collaborative OS platform for products
-| Vendor | Fedora Project | 2021 | [link](https://fedoraproject.org/atomic-desktops/) | An atomic desktop operating system aimed at good support for container-focused workflows
+| Vendor | Endless | 2014 | [link](https://www.endlessos.org/os) | A Completely Free, User-Friendly Operating System Packed with Educational Tools, Games, and More |
+| Vendor | Red Hat | 2015 | [link](https://redhat.com) | Image Based Linux |
+| Vendor | Apertis | 2020 | [link](https://apertis.org) | Collaborative OS platform for products |
+| Vendor | Fedora Project | 2021 | [link](https://fedoraproject.org/atomic-desktops/) | An atomic desktop operating system aimed at good support for container-focused workflows |
 | Vendor | Playtron GameOS | 2022 | [link](https://www.playtron.one/) | A video game console OS that has integration with the top PC game stores |
-| Vendor | Universal Blue   | 2022 | [link](https://universal-blue.org/) | The reliability of a Chromebook, but with the flexibility and power of a traditional Linux desktop
-| Vendor | Fyra Labs | 2024 | [link](https://fyralabs.com) | Bootc powers an experimental variant of Ultramarine Linux
+| Vendor | Universal Blue | 2022 | [link](https://universal-blue.org/) | The reliability of a Chromebook, but with the flexibility and power of a traditional Linux desktop |
+| Vendor | Fyra Labs | 2024 | [link](https://fyralabs.com) | Bootc powers an experimental variant of Ultramarine Linux |
 
 ### Adopter Types
 

crates/lib/src/install.rs

@@ -162,6 +162,10 @@ use aleph::InstallAleph;
 use anyhow::{Context, Result, anyhow, ensure};
 use bootc_kernel_cmdline::utf8::{Cmdline, CmdlineOwned};
 use bootc_utils::CommandRunExt;
+use composefs::fs::{read_file, write_to_path};
+use composefs_boot::bootloader::{BootEntry, get_boot_resources};
+use composefs_boot::selabel;
+use composefs_oci::image::create_filesystem as create_composefs_filesystem;
 use camino::Utf8Path;
 use camino::Utf8PathBuf;
 use canon_json::CanonJsonSerialize;
@@ -238,6 +242,9 @@ const DEFAULT_REPO_CONFIG: &[(&str, &str)] = &[
 /// Kernel argument used to specify we want the rootfs mounted read-write by default
 pub(crate) const RW_KARG: &str = "rw";
 
+/// Marker file written to the target root to indicate a flat (non-ostree) install was performed.
+pub(crate) const FLAT_INSTALL_MARKER: &str = "etc/.bootc-flat";
+
 #[derive(clap::Args, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 pub(crate) struct InstallTargetOpts {
     // TODO: A size specifier which allocates free space for the root in *addition* to the base container image size
@@ -488,6 +495,15 @@ pub(crate) struct InstallTargetFilesystemOpts {
     /// is then the responsibility of the invoking code to perform those operations.
     #[clap(long)]
     pub(crate) skip_finalize: bool,
+
+    /// Install in "flat" mode: the container rootfs is written to the target filesystem
+    /// as a regular writable directory tree (no composefs overlay at boot time). This is
+    /// experimental. Post-install, bootc day-2 operations (upgrade, rollback, etc.) are
+    /// unavailable on the installed system. A composefs repository is created at
+    /// `/sysroot/composefs` as an intermediate step; it can be removed post-install or
+    /// retained to enable future conversion to immutable mode.
+    #[clap(long)]
+    pub(crate) flat: bool,
 }
 
 #[derive(Debug, Clone, clap::Parser, PartialEq, Eq)]
@@ -1286,6 +1302,8 @@ pub(crate) struct RootSetup {
     skip_finalize: bool,
     boot: Option<MountSpec>,
     pub(crate) kargs: CmdlineOwned,
+    /// If true, perform a flat installation (no ostree/composefs)
+    pub(crate) flat: bool,
 }
 
 fn require_boot_uuid(spec: &MountSpec) -> Result<&str> {
@@ -1818,16 +1836,17 @@ async fn install_with_sysroot(
 
     if cfg!(target_arch = "s390x") {
         // TODO: Integrate s390x support into install_via_bootupd
-        crate::bootloader::install_via_zipl(&rootfs.device_info, boot_uuid)?;
+        install_bootloader_via_zipl(&rootfs.device_info, boot_uuid)?;
     } else {
         match postfetch.detected_bootloader {
             Bootloader::Grub => {
-                crate::bootloader::install_via_bootupd(
+                let target_root = rootfs
+                    .target_root_path
+                    .as_ref()
+                    .unwrap_or(&rootfs.physical_root_path);
+                install_bootloader_via_bootupd(
                     &rootfs.device_info,
-                    &rootfs
-                        .target_root_path
-                        .clone()
-                        .unwrap_or(rootfs.physical_root_path.clone()),
+                    target_root,
                     &state.config_opts,
                     Some(&deployment_path.as_str()),
                 )?;
@@ -1863,6 +1882,38 @@ async fn install_with_sysroot(
     Ok(())
 }
 
+/// Install the bootloader using bootupd.
+///
+/// This is a helper to reduce duplication between ostree and flat installs.
+///
+/// # Arguments
+/// * `device_info` - Device information for the target
+/// * `target_root` - Path to the target root filesystem
+/// * `config_opts` - Configuration options
+/// * `deployment_path` - Optional deployment path for ostree-based installs
+#[context("Installing bootloader via bootupd")]
+fn install_bootloader_via_bootupd(
+    device_info: &bootc_blockdev::Device,
+    target_root: &Utf8PathBuf,
+    config_opts: &InstallConfigOpts,
+    deployment_path: Option<&str>,
+) -> Result<()> {
+    crate::bootloader::install_via_bootupd(device_info, target_root, config_opts, deployment_path)
+}
+
+/// Install the bootloader using zipl (s390x architecture).
+///
+/// # Arguments
+/// * `device_info` - Device information for the target
+/// * `boot_uuid` - Boot UUID (required for zipl)
+#[context("Installing bootloader via zipl")]
+fn install_bootloader_via_zipl(
+    device_info: &bootc_blockdev::Device,
+    boot_uuid: &str,
+) -> Result<()> {
+    crate::bootloader::install_via_zipl(device_info, boot_uuid)
+}
+
 enum BoundImages {
     Skip,
     Resolved(Vec<ResolvedBoundImage>),
@@ -1899,6 +1950,162 @@ impl BoundImages {
     }
 }
 
+/// Write a BLS entry for a flat (non-ostree) installation.
+#[context("Creating flat BLS entry")]
+fn create_flat_bls_entry(
+    rootfs: &RootSetup,
+    kernel_version: &str,
+    vmlinuz_boot_path: &Utf8PathBuf,
+    initramfs_boot_path: &Utf8PathBuf,
+) -> Result<()> {
+    use crate::parsers::bls_config::{BLSConfig, BLSConfigType};
+
+    let mut cfg = BLSConfig::default();
+    cfg.with_title(format!("Linux {kernel_version}"))
+        .with_version(kernel_version.to_string())
+        .with_cfg(BLSConfigType::NonEFI {
+            linux: vmlinuz_boot_path.clone(),
+            initrd: vec![initramfs_boot_path.clone()],
+            options: Some(rootfs.kargs.clone()),
+        });
+
+    let entry_path = format!("boot/loader/entries/flat-{kernel_version}.conf");
+    rootfs
+        .physical_root
+        .create_dir_all("boot/loader/entries")
+        .context("Creating boot/loader/entries")?;
+
+    let content = format!("{cfg}");
+    rootfs
+        .physical_root
+        .atomic_write(&entry_path, content.as_bytes())
+        .with_context(|| format!("Writing BLS entry {entry_path}"))?;
+
+    tracing::debug!("Wrote BLS entry: {entry_path}");
+    Ok(())
+}
+
+/// Perform a flat (non-ostree) installation.
+///
+/// The approach here is to:
+/// 1. Pull the image into a composefs repository at `composefs/` on the target.
+///    This reuses composefs-rs's SELinux labeling support and kernel installation flow.
+///    The composefs repo is preserved at `/sysroot/composefs`; users who want to convert
+///    to immutable composefs mode later can do so, and anyone who doesn't want the extra
+///    metadata can simply `rm -rf /sysroot/composefs`.
+/// 2. Check out the filesystem from the composefs repo to the target using `write_to_path`,
+///    which supports reflink copies on filesystems that enable it (btrfs, XFS).
+/// 3. Write the kernel and initramfs to `/boot/` from the composefs repo objects.
+/// 4. Create a standard BLS entry pointing at `root=UUID=...` (not a composefs overlay).
+#[context("Performing flat install")]
+async fn flat_install(state: &State, rootfs: &RootSetup) -> Result<()> {
+    println!("Installing in flat mode (experimental)");
+
+    // Step 1: Pull the image into the composefs repository on the target.
+    // allow_missing_fsverity=true because we don't use fsverity at boot time in flat mode.
+    let (image_id, _verity) =
+        initialize_composefs_repository(state, rootfs, true).await?;
+
+    // Step 2: Build the filesystem tree from the pulled image.
+    let repo = crate::bootc_composefs::repo::open_composefs_repo(&rootfs.physical_root)?;
+    let mut fs = create_composefs_filesystem(&repo, &image_id, None)?;
+
+    // Step 3: Apply SELinux labels from the image's file_contexts.
+    // Returns true if a policy was found and labels applied, false if no policy was found.
+    let _ = selabel::selabel(&mut fs, &repo).context("Applying SELinux labels")?;
+
+    // Step 4: Extract kernel/initramfs boot entries from the composefs tree.
+    let boot_entries = get_boot_resources(&fs, &repo)?;
+    let vmlinuz_entry = boot_entries
+        .into_iter()
+        .find_map(|e| match e {
+            BootEntry::UsrLibModulesVmLinuz(v) => Some(v),
+            _ => None,
+        })
+        .ok_or_else(|| anyhow!("No vmlinuz kernel found in flat install image"))?;
+    let kernel_version = vmlinuz_entry.kver.as_ref().to_owned();
+
+    // Step 5: Check out the filesystem to the target directory.
+    // On reflink-capable filesystems (btrfs, XFS) this efficiently shares blocks
+    // with the composefs object store.
+    let target_std = rootfs.physical_root_path.as_std_path().to_owned();
+    tokio::task::block_in_place(|| write_to_path(&repo, &fs.root, &target_std))
+        .context("Checking out container rootfs to target")?;
+
+    // Step 6: Write vmlinuz and initramfs to /boot/ on the target.
+    let vmlinuz_dest = format!("boot/vmlinuz-{kernel_version}");
+    rootfs
+        .physical_root
+        .create_dir_all("boot")
+        .context("Creating boot directory")?;
+    rootfs
+        .physical_root
+        .atomic_write(
+            &vmlinuz_dest,
+            read_file(&vmlinuz_entry.vmlinuz, &repo)
+                .context("Reading vmlinuz from composefs repo")?
+                .as_ref(),
+        )
+        .with_context(|| format!("Writing {vmlinuz_dest}"))?;
+
+    let initramfs_boot_path = Utf8PathBuf::from(format!("/boot/initramfs-{kernel_version}.img"));
+    if let Some(initramfs) = &vmlinuz_entry.initramfs {
+        let initramfs_dest = format!("boot/initramfs-{kernel_version}.img");
+        rootfs
+            .physical_root
+            .atomic_write(
+                &initramfs_dest,
+                read_file(initramfs, &repo)
+                    .context("Reading initramfs from composefs repo")?
+                    .as_ref(),
+            )
+            .with_context(|| format!("Writing {initramfs_dest}"))?;
+    } else {
+        crate::utils::medium_visibility_warning(
+            "No initramfs found in image; boot may require manual initramfs generation",
+        );
+    }
+
+    // Step 7: Create BLS entry.
+    let vmlinuz_boot_path = Utf8PathBuf::from(format!("/boot/vmlinuz-{kernel_version}"));
+    create_flat_bls_entry(rootfs, &kernel_version, &vmlinuz_boot_path, &initramfs_boot_path)?;
+
+    // Step 8: Install bootloader.
+    match state.config_opts.bootloader.as_ref() {
+        Some(crate::spec::Bootloader::None) => {
+            tracing::debug!("Skipping bootloader installation (bootloader=none)");
+        }
+        _ => {
+            if cfg!(target_arch = "s390x") {
+                let boot_uuid = rootfs
+                    .get_boot_uuid()?
+                    .or(rootfs.rootfs_uuid.as_deref())
+                    .ok_or_else(|| anyhow!("No uuid for boot/root"))?;
+                install_bootloader_via_zipl(&rootfs.device_info, boot_uuid)?;
+            } else {
+                let target_root = rootfs
+                    .target_root_path
+                    .as_ref()
+                    .unwrap_or(&rootfs.physical_root_path);
+                install_bootloader_via_bootupd(
+                    &rootfs.device_info,
+                    target_root,
+                    &state.config_opts,
+                    None,
+                )?;
+            }
+        }
+    }
+
+    // Step 9: Write flat install marker.
+    rootfs
+        .physical_root
+        .atomic_write(FLAT_INSTALL_MARKER, b"")
+        .context("Writing flat install marker")?;
+
+    Ok(())
+}
+
 async fn ostree_install(state: &State, rootfs: &RootSetup, cleanup: Cleanup) -> Result<()> {
     // We verify this upfront because it's currently required by bootupd
     let boot_uuid = rootfs
@@ -1971,7 +2178,9 @@ async fn install_to_filesystem_impl(
         }
     }
 
-    if state.composefs_options.composefs_backend {
+    if rootfs.flat {
+        flat_install(state, rootfs).await?;
+    } else if state.composefs_options.composefs_backend {
         // Load a fd for the mounted target physical root
 
         let (id, verity) = initialize_composefs_repository(
@@ -2608,6 +2817,7 @@ pub(crate) async fn install_to_filesystem(
         boot,
         kargs,
         skip_finalize,
+        flat: fsopts.flat,
     };
 
     install_to_filesystem_impl(&state, &mut rootfs, cleanup).await?;
@@ -2658,6 +2868,7 @@ pub(crate) async fn install_to_existing_root(opts: InstallToExistingRootOpts) ->
             replace: opts.replace,
             skip_finalize: true,
             acknowledge_destructive: opts.acknowledge_destructive,
+            flat: false,
         },
         source_opts: opts.source_opts,
         target_opts: opts.target_opts,
@@ -3050,4 +3261,59 @@ UUID=boot-uuid /boot ext4 defaults 0 0
 
         Ok(())
     }
+
+    #[test]
+    fn test_create_flat_bls_entry() -> Result<()> {
+        let td = cap_std_ext::cap_tempfile::TempDir::new(cap_std::ambient_authority())?;
+        td.create_dir_all("boot")?;
+
+        let rootfs = RootSetup {
+            #[cfg(feature = "install-to-disk")]
+            luks_device: None,
+            device_info: bootc_blockdev::Device {
+                name: "vda".to_string(),
+                serial: None,
+                model: None,
+                partlabel: None,
+                parttype: None,
+                partuuid: None,
+                partn: None,
+                children: None,
+                size: 0,
+                maj_min: None,
+                start: None,
+                label: None,
+                fstype: None,
+                uuid: None,
+                path: None,
+                pttype: None,
+            },
+            physical_root_path: Utf8PathBuf::from("/test"),
+            physical_root: td.try_clone()?,
+            target_root_path: None,
+            rootfs_uuid: None,
+            skip_finalize: false,
+            boot: None,
+            kargs: CmdlineOwned::from("root=UUID=abc123 rw"),
+            flat: true,
+        };
+
+        let kernel_version = "6.12.0-100.fc41.x86_64";
+        let vmlinuz = Utf8PathBuf::from(format!("/boot/vmlinuz-{kernel_version}"));
+        let initramfs = Utf8PathBuf::from(format!("/boot/initramfs-{kernel_version}.img"));
+
+        create_flat_bls_entry(&rootfs, kernel_version, &vmlinuz, &initramfs)?;
+
+        // Read back the BLS entry and verify its contents
+        let entry_path = format!("boot/loader/entries/flat-{kernel_version}.conf");
+        let content = String::from_utf8(td.read(&entry_path)?)?;
+
+        assert!(content.contains(&format!("title Linux {kernel_version}")));
+        assert!(content.contains(&format!("version {kernel_version}")));
+        assert!(content.contains(&format!("linux /boot/vmlinuz-{kernel_version}")));
+        assert!(content.contains(&format!("initrd /boot/initramfs-{kernel_version}.img")));
+        assert!(content.contains("options root=UUID=abc123 rw"));
+
+        Ok(())
+    }
 }