bootc-docs/installation.md

Installation

⚠️ CRITICAL SAFETY WARNING ⚠️

bootc installation involves DESTRUCTIVE operations that can WIPE your disk and data!

• bootc install to-disk will DESTROY existing partitions and data
• grub-install operations can CORRUPT your bootloader
• Always test on a virtual machine or test hardware first
• Never run on production systems without proper backups
• Use BOOTC_I_KNOW_THIS_WIPES_MY_DISK=1 environment variable to confirm you understand the risks

Base Images

Many users will be more interested in base (container) images for Debian.

Debian

Currently, the Debian bootc project is focused on providing bootc support for Debian-based systems.

For pre-built base images, any Debian derivative can be converted to use bootc. However, since bootc is not yet available as a Debian package, you'll need to compile it from source.

Prerequisites

• Debian 13 (Trixie) or later (recommended)
• Debian 12 (Bookworm) - oldstable, OSTree packages too old
• Debian 14 (Forky) - testing, has newer OSTree libraries
• Systemd as the init system
• Root access for installation
• Development tools and dependencies for compiling bootc

Installation Steps

1. Install build dependencies:

   sudo apt update
   sudo apt install -y build-essential git pkg-config libostree-dev libglib2.0-dev libgpgme-dev libseccomp-dev
   

2. Install runtime dependencies:

   sudo apt install -y ostree podman
   

3. Clone and build bootc:

   git clone https://github.com/containers/bootc.git
   cd bootc
   make
   sudo make install
   

4. Verify installation:

   bootc --version
   

Converting Existing Debian Systems

Converting an existing Debian system to use bootc requires careful planning:

1. Backup your system - This is a major change to how your OS updates work
2. Prepare a bootc-compatible base image - This should be based on your current Debian installation
3. Test the conversion process - Use a virtual machine or test system first
4. Execute the conversion - Follow the bootc conversion guide for Debian

Debian-Specific Considerations

• Source Compilation: Since bootc is not packaged for Debian yet, you'll need to compile from source
• OSTree Version Requirements:
  • Debian 12 (Bookworm): OSTree packages too old, not recommended
  • Debian 13 (Trixie): Has newer OSTree libraries, recommended for bootc
  • Debian 14 (Forky): Has latest OSTree libraries, ideal for bootupd/bootc
• Backporting: Newer OSTree libraries from Forky can be backported to Trixie
• Package Management: bootc works alongside apt for application packages while managing the base OS through container images
• Configuration: System configuration follows Debian conventions with /etc for machine-local settings
• Services: systemd services work normally, with bootc managing the base OS layer
• Updates: OS updates are handled through bootc, while application updates continue to use apt
• Development Status: This is experimental software - use with caution in production environments

Other Distributions

bootc itself is not tied to Debian derivatives; this issue tracks the main blocker for other distributions. However, Debian provides a solid foundation for bootc implementation due to its:

• Mature package management system
• Strong systemd integration
• Extensive hardware support
• Long-term support releases

---

The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage.