particle-os/bootc-docs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
bootc-docs/installation.md
robojerk d9faf636ed
Some checks failed
Test bootc Documentation / test-base-image (push) Failing after 29s
Details
Test bootc Documentation / test-documentation (push) Failing after 31s
Details
Implement high-impact improvements based on ChatGPT feedback 
SAFETY IMPROVEMENTS:
- Strengthen safety warnings with 🚨 emoji and mandatory confirmation
- Add BOOTC_CONFIRM_DISK_WIPE=1 requirement for destructive operations
- Add 10-second sleep before exit to prevent accidental execution
- Emphasize experimental nature and data loss risks

COMPATIBILITY MATRIX:
- Create detailed version compatibility table with specific versions
- Add feature compatibility by bootc version
- Include kernel requirements for each feature
- Document experimental flags and their version requirements

KERNEL REQUIREMENTS:
- Add comprehensive kernel feature checklist
- Include verification commands for kernel features
- Specify exact kernel versions for different features
- Add EROFS, composefs, overlayfs, fsverity requirements

LICENSING:
- Add Apache 2.0 LICENSE file with SPDX identifier
- Remove ambiguity about licensing terms

CI/AUTOMATION:
- Add GitHub Actions workflow for automated testing
- Test base image building and validation
- Test nginx layer creation
- Validate documentation structure
- Check for broken links and markdown syntax

This addresses the most critical feedback while maintaining focus
on what actually works (Sid/Forky + modern OSTree).
2025-09-15 14:31:28 -07:00

3.9 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
  • THIS IS EXPERIMENTAL SOFTWARE - Expect failures and data loss
  • Always test on a virtual machine or test hardware first
  • Never run on production systems without proper backups
  • MANDATORY: Use BOOTC_CONFIRM_DISK_WIPE=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.