particle-os/bootc-docs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
bootc-docs/installation.md
robojerk 72155be8de CRITICAL: Correct dangerous claims about bootc production readiness 
EXPERIMENTAL WARNINGS:
- Add prominent warnings that bootc on Debian is HIGHLY EXPERIMENTAL
- Clarify that NO reproducible bootc images exist yet
- Warn that everything is still experimental and not production-ready
- Add DO NOT use in production warnings throughout

DEBIAN VERSION CORRECTIONS:
- Use Debian Sid (unstable) for base image building (like Fedora rawhide)
- Correct dangerous claims about 'tested' configurations
- Mark all configurations as experimental, not tested
- Remove false claims about production readiness

SAFETY IMPROVEMENTS:
- Add experimental warnings to all base image documentation
- Clarify that bootc is not stable on Debian yet
- Emphasize testing-only use on virtual machines
- Remove misleading production recommendations

This corrects dangerous misinformation that could lead to
data loss and system instability in production environments.
2025-09-15 14:24:27 -07:00

3.8 KiB
Raw Blame History

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 Sid (unstable) - Recommended for base image building (like Fedora rawhide)
  • Debian 13 (Trixie) - Stable, but bootc is experimental
  • 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 HIGHLY EXPERIMENTAL software - DO NOT use in production
  • No Reproducible Images: No one has successfully created reproducible bootc images yet
  • Testing Only: Use only for testing on virtual machines or test hardware

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.