particle-os/bootc-docs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
bootc-docs/installation.md
robojerk d2238df478 Critical safety and compatibility fixes based on ChatGPT feedback 
SAFETY FIXES:
- Add prominent safety warnings for destructive operations
- Add BOOTC_I_KNOW_THIS_WIPES_MY_DISK environment variable checks
- Add safety warnings to manual installation scripts

BUILD FIXES:
- Fix Containerfile systemd calls to use symlinks instead of systemctl
- Replace brittle image validation with podman image mount
- Add fallback for rootless/mount issues

COMPATIBILITY FIXES:
- Align Debian version references (12 Bookworm vs 14 Forky)
- Add comprehensive COMPATIBILITY.md with version matrix
- Add kernel requirements for composefs (5.15+ basic, 6.5+ recommended)
- Document experimental flags and version requirements

TECHNICAL IMPROVEMENTS:
- Use DEBIAN_FRONTEND=noninteractive in build scripts
- Improve image inspection robustness
- Add explicit version testing matrix
- Document known issues and workarounds

This addresses the most critical issues identified in the ChatGPT review:
1. Safety warnings for destructive operations
2. Build-time systemd handling fixes
3. Robust image validation methods
4. Version compatibility documentation
2025-09-15 14:19:12 -07:00

3.1 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 12 (Bookworm) or later (tested with Bookworm)
  • 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
  • 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.