Building and Testing Sealed Bootable Container Images for Fedora Atomic Desktops

Overview

Fedora Atomic Desktops now offer sealed bootable container images—a new approach to creating a fully verified boot chain from firmware to the operating system's composefs image. These images integrate Secure Boot, Unified Kernel Images (UKI), and fs-verity to ensure integrity at every stage. The primary benefit is enabling passwordless disk unlocking via TPM in a secure, default configuration. This tutorial guides you through testing pre-built images and building your own, covering all essential components: systemd-boot (signed), UKI (signed kernel+initrd+cmdline), and a composefs repository with fs-verity managed by bootc. Note: these are test images, not production-ready; they use test signing keys (not official Fedora keys) and SSH access is enabled by default.

Prerequisites

Hardware and Firmware

• System with UEFI firmware (BIOS/Legacy not supported)
• Secure Boot enabled in firmware settings
• Architecture: x86_64 or aarch64
• At least 8 GB RAM, 20 GB free disk (for building)

Software

• Fedora Linux (or another distribution) with podman or docker installed
• bootc utility (version 0.9.0+)
• skopeo (for container image inspection)
• git (to clone helper scripts)
• USB flash drive (8 GB or larger) for installation media

Step-by-Step Instructions

1. Downloading Pre-built Test Images

Pre-built sealed images are available from the Fedora registry. Choose a desktop variant (e.g., Workstation, KDE, Sway). For this guide, we'll use the Workstation image.

# Pull the container image (example for Workstation on x86_64)
podman pull ghcr.io/travier/fedora-atomic-desktops-sealed:fedora-atomic-desktop-workstation-x86_64

# Alternatively, use skopeo to copy the raw disk image directly
skopeo copy docker://ghcr.io/travier/fedora-atomic-desktops-sealed:fedora-atomic-desktop-workstation-x86_64-disk oci-archive:image.tar

2. Verifying the Image

Check the UKI signature and composefs integrity. The image should include a signed systemd-boot and a UKI signed with test MOK keys.

# Inspect the container image layers
podman inspect ghcr.io/travier/fedora-atomic-desktops-sealed:fedora-atomic-desktop-workstation-x86_64 | jq '.[].RootFS.Layers'

3. Writing the Disk Image to USB

Extract the raw disk image file (usually named disk.img or similar) from the container and write it to a USB drive. Replace /dev/sdX with your actual device.

# Extract the disk image from the OCI archive
mkdir -p raw && cd raw
podman run --rm --pull=never -v $PWD:/output:Z localhost/fedora-atomic-desktops-sealed:latest cp /disk.img /output/
# Write to USB (ensure you use the correct device!)
sudo dd if=disk.img of=/dev/sdX bs=4M status=progress conv=fsync

4. Booting and Testing

Boot from the USB. Since the images use test signing keys, you must enroll the Secure Boot key first time:

1. Enter firmware/BIOS setup and enable Secure Boot (if not already).
2. The system will attempt to boot; you'll see a warning about an untrusted signature.
3. Use mokutil to enroll the embedded Machine Owner Key (MOK):

# After booting into the image (fallback to shim), open a console
sudo mokutil --import /var/lib/bootc/mok/BOOTC-MOK.der

Reboot and confirm enrollment. Now the system will fully verify the boot chain. Test TPM-based disk unlocking:

# Ensure TPM2 is enabled in firmware
sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=0+1+2+3+4+5+6+7 /dev/sda2
# Reboot and see if you are prompted for a password or it unlocks automatically

5. Building Your Own Sealed Image

Use the helper scripts from the fedora-atomic-desktops-sealed repository.

git clone https://github.com/travier/fedora-atomic-desktops-sealed.git
cd fedora-atomic-desktops-sealed

# Build a sealed image for your chosen desktop (e.g., Workstation)
./build-image.sh --variant fedora-atomic-desktop-workstation --arch x86_64

This script generates a container image and a raw disk. You can customize the UKI command line by editing uki-cmdline file before building.

Common Mistakes and Troubleshooting

• Secure Boot enrollment fails: Ensure firmware is in setup mode (not “user” mode). On some systems, you need to clear Secure Boot keys first via firmware menu.
• TPM unlocking not working: Verify TPM2 is enabled in BIOS and that the PCRs used match your boot policy. Use systemd-cryptenroll --tpm2-device=list to check TPM availability.
• Boot loop after writing disk image: You may have written the image to the wrong device. Re-check with lsblk before writing.
• Networking not available during first boot: Some sealed images don't include default network configuration. Use nmcli to bring up an interface manually: sudo nmcli dev wifi connect password .
• SSH access too permissive: Remember the root password is unset; change immediately with sudo passwd.

Summary

Sealed bootable container images for Fedora Atomic Desktops provide a verified chain of trust from firmware to the root filesystem, enabling secure TPM-based disk unlocking. You can test pre-built images by downloading, writing to USB, and enrolling the test Secure Boot keys. For advanced users, the open-source build scripts allow customization. Keep in mind these are testing releases—do not use them in production. Feedback and bug reports are welcome via the project's GitHub repository. This technology is the first step toward consistently secure bootable containers on Fedora.