robojerk/particleos-installer
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
particleos-installer/calmares_plan.md

16 KiB
Raw Blame History

Okay, this is an excellent, detailed plan. It clearly outlines the shift to an installer-focused ISO and the integration of bootc via Calamares.

Let's refine this plan with even more nuance, addressing the atomic system requirements and the specific tools involved.

Detailed, Nuanced Plan: ParticleOS Atomic Installer ISO

Overall Goal: Create a minimal, bootable ISO that launches the Calamares installer. Calamares will then orchestrate the deployment of a pre-defined, immutable ParticleOS atomic image onto the target system using bootc.

Core Principles:

  • Minimal Installer: The ISO environment itself will be lean, containing only what's necessary to run Calamares and bootc.
  • Atomic Deployment: The core OS is treated as an atomic unit (an OCI image) deployed by bootc, not built or modified on the fly during installation.
  • Security & Reproducibility: Leverage mmdebstrap and bootc for a secure and reproducible build.

Phase 1: Host-Side Script (build-iso-podman.sh) - Orchestration Layer

Role: This script remains the high-level orchestrator. It sets up the Podman build environment, copies the necessary build scripts and assets into the container, and initiates the containerized build.

Adjustments (Minimal):

  • check_prerequisites:
    • Forgejo Criticality: Reiterate that Forgejo must be accessible and contain bootc and ostree. The current critical checks for GPG key and package presence are correct and should remain. If these checks fail, the build must abort, as bootc is non-negotiable for the atomic system.
    • Calamares Repository Check (Optional but Recommended): If Calamares is sourced from a specific PPA/repository, add a similar check here to ensure its GPG key and packages are reachable. This prevents later failures inside the container.
  • create_dockerfile: No changes needed. The Dockerfile's role is to provide the build tools for the container, not the OS components for the ISO.
  • create_container_build_script: This function will now generate a significantly different build-in-container.sh (detailed in Phase 3).
  • run_container_build: No changes needed. It ensures the isolated container runs with necessary privileges and volume mounts.
  • Cleanup: Remains the same.

Phase 2: Container Base Image (Dockerfile) - Build Tool Environment

Role: This Dockerfile defines the environment inside the Podman container where build-in-container.sh will execute. It needs to provide all the tools required for mmdebstrap, ISO creation, and handling GPG keys.

Adjustments (Minor):

  • RUN apt install -y ...:
    • Ensure curl, wget, ca-certificates, gnupg, gpgv, software-properties-common are installed. These are essential for fetching GPG keys and packages from various repositories during the mmdebstrap phase.
    • Keep mmdebstrap, squashfs-tools, xorriso, grub-pc-bin, grub-efi-amd64-bin, isolinux, live-build. These are core ISO building tools.
    • No other changes are strictly necessary here, as this is the builder's environment, not the target OS.

Phase 3: Container Build Script (build-in-container.sh) - The Core Logic

Role: This script, run inside the Podman container, orchestrates the creation of the minimal Calamares installer chroot, configures it, and builds the final ISO.

Major Overhaul Required.

3.1. Initial Chroot Creation (mmdebstrap)

  • Goal: Create a barebones chroot capable of booting into a graphical environment to run Calamares. This is not a full desktop.
  • mmdebstrap Command Structure: 
    mmdebstrap \
    --architectures=amd64 \
    --variant=minbase \
    --include=systemd,systemd-sysv,dbus,curl,ca-certificates,gnupg,gpgv,locales,resolvconf,iproute2,net-tools,isc-dhcp-client,sudo,useradd,chpasswd,network-manager,plasma-nm,openssh-server,xserver-xorg-core,xinit,desktop-base,plymouth,sddm,calamares,calamares-settings-ubuntu,ostree,bootc,apt-ostree,firefox \
    --mode=unshare \
    --aptopt="Acquire::Check-Valid-Until \"false\"" \
    --setup-hook="mkdir -p \"\$1/etc/apt/keyrings\"" \
    --setup-hook="curl -fsSL https://ppa.launchpadcontent.net/mozillateam/ppa/ubuntu/dists/noble/Release.gpg | gpg --dearmor -o \"\$1${MOZILLA_KEYRING}\"" \
    --setup-hook="curl -fsSL https://git.raines.xyz/api/packages/robojerk/debian/gpg | gpg --dearmor -o \"\$1${FORGEJO_KEYRING}\"" \
    # Add Calamares PPA/Repo key if needed (research required for Noble)
    # --setup-hook="curl -fsSL ${CALAMARES_PPA_RELEASE_GPG} | gpg --dearmor -o \"\$1${CALAMARES_KEYRING}\"" \
    noble \
    "$CHROOT_DIR" \
    "deb [signed-by=${MOZILLA_KEYRING}] https://ppa.launchpadcontent.net/mozillateam/ppa/ubuntu noble main" \
    "deb [signed-by=${FORGEJO_KEYRING}] https://git.raines.xyz/api/packages/robojerk/debian noble main" \
    # "deb [signed-by=${CALAMARES_KEYRING}] ${CALAMARES_PPA_URL} noble main" # Add if Calamares has a PPA
    http://archive.ubuntu.com/ubuntu/ || print_error "mmdebstrap failed to create base system or add GPG keys."
    • Rationale for --include:
      • minbase: Provides a very minimal system.
      • xserver-xorg-core, xinit, desktop-base: Minimal X server and basic desktop files needed for a graphical environment for Calamares. desktop-base provides themes/backgrounds.
      • plymouth: For a nice boot splash.
      • sddm: A display manager to launch Calamares.
      • calamares, calamares-settings-ubuntu: The installer itself and its default configuration.
      • ostree, bootc: Absolutely critical for the atomic deployment.
      • apt-ostree: Likely needed for any apt interactions within the installer environment that might touch ostree concepts (though bootc is the primary tool here).
      • firefox: Useful for accessing documentation or reporting issues from the live installer environment.
      • network-manager, plasma-nm: Essential for network connectivity in the installer, especially if bootc needs to pull an image from a registry.
      • openssh-server: For remote debugging/access to the installer environment.
    • GPG Key Handling: The --setup-hook approach is crucial for placing the GPG keys before mmdebstrap's internal apt runs, preventing signature errors.

3.2. Essential Chroot Configuration (Post-mmdebstrap)

  • Goal: Ensure the chroot environment is fully functional for graphical display, networking, and security.
  • Steps:
    • Bind Mounts: Keep mount --bind /dev, /run, /proc, /sys. (No change)
    • /etc/resolv.conf Copy: Keep cp /etc/resolv.conf "$CHROOT_DIR/etc/resolv.conf". (No change)
    • Device Node Permissions (mknod): Keep the mknod commands for /dev/null, /dev/zero, etc. (No change)
    • APT Sources (Default Ubuntu): Keep the standard Ubuntu sources.list entries. (No change)
    • APT Preferences (Forgejo for ostree/bootc): Keep the 99-forgejo-ostree-bootc.pref file creation. This ensures apt within the installer environment prioritizes your bootc and ostree versions. (No change)
    • Final apt update: chroot "$CHROOT_DIR" apt update. This is to ensure all package lists are up-to-date after all repositories and preferences are set.

3.3. Configure Calamares for Atomic Deployment

  • Goal: Customize Calamares to perform a bootc-driven installation. This is the most complex and critical part.
  • Calamares Configuration Files (/etc/calamares/):
    • Calamares uses a modular YAML-based configuration. You'll need to create or modify several .conf files.
    • Branding: Create /etc/calamares/branding/particleos/ and place branding.desc (for name/logo), slideshow.qml (if you want a custom slideshow), and sidebar.qml.
    • settings.conf: This is the main sequence file.
      • Define the sequence of modules.
      • Disable/hide modules not relevant for an atomic install (e.g., packages if you're not allowing user package selection).
      • Crucially, integrate a custom bootc job.
    • partition.conf:
      • Calamares' default partition module might be sufficient for creating the basic /boot, /boot/efi, and / partitions.
      • Nuance: bootc has specific partitioning requirements (e.g., xfs or ext4 for /, separate /boot and /boot/efi). Ensure Calamares' partition module is configured to create a compatible layout.
      • Alternatively, disable Calamares' partition module and handle partitioning entirely within a custom bootc script if more control is needed.
    • users.conf: Configure user creation. Calamares can handle this, and you'll want to ensure it creates a sudo user.
    • Custom bootc Job (Critical): This is where the magic happens.
      • Create a custom Calamares module (e.g., atomic_install.conf) of type: script.
      • This module will execute a shell script (e.g., /usr/local/bin/particleos-bootc-install.sh) that performs the bootc installation.
      • particleos-bootc-install.sh (inside chroot): 
        #!/bin/bash
# This script is called by Calamares to perform the bootc installation.
# Calamares passes parameters via environment variables or arguments.
# Example: Calamares might set CALAMARES_TARGET_DEVICE=/dev/sda
#
# Forgejo has a oci image repo. See documentation here
# https://forgejo.org/docs/latest/user/packages/container/
#
# Existing images
# https://git.raines.xyz/robojerk/-/packages/container/aurora-bootable/v1.0
# docker pull git.raines.xyz/robojerk/aurora-bootable:v1.0
# Digest: sha256:c3a52d917bf4ac32a5fdcd6de2c1165fbd3ba234fef82a1d35b8b56e2bb1103d
#
# https://git.raines.xyz/robojerk/-/packages/container/aurora-system/v1.0
# docker pull git.raines.xyz/robojerk/aurora-system:v1.0
# Digest: sha256:be75ad8f24e0b25d1d5f1d9fdd2b0bf2a5ed02a2e8646647a8e25ca83c5e6828


TARGET_DEVICE="${CALAMARES_TARGET_DEVICE}" # Or passed as $1
ATOMIC_IMAGE="registry.example.com/particleos:latest" # Your pre-built atomic OS image

if [ -z "$TARGET_DEVICE" ]; then
    echo "Error: Target device not specified for bootc installation by Calamares." >&2
    exit 1
fi

echo "Starting bootc installation to $TARGET_DEVICE using image $ATOMIC_IMAGE"

# Execute bootc install. This command needs to be precise for your atomic image.
# It will:
# 1. Pull the OCI image from the registry.
# 2. Rebase the system onto that image (ostree operation).
# 3. Configure bootloader (GRUB/systemd-boot) for the new atomic system.
bootc install --target-device "$TARGET_DEVICE" "$ATOMIC_IMAGE" || {
    echo "CRITICAL ERROR: bootc installation failed! Check network, image, and target device." >&2
    exit 1
}

echo "bootc installation completed successfully."
exit 0
      • Permissions: Ensure /usr/local/bin/particleos-bootc-install.sh is executable (chmod +x).
  • Calamares Display Manager Integration:
    • Configure sddm to automatically start Calamares. This usually involves creating a custom X session file (.desktop file) that launches Calamares, and then configuring sddm to use that session by default or auto-login a user that launches it.
    • Example: Create /usr/share/xsessions/calamares.desktop and configure sddm.conf to auto-login root or a calamares user and run that session.

3.4. System Configuration (Installer Environment)

  • Goal: Basic system setup for the installer environment itself.
  • Steps:
    • hostname, hosts, localtime, locale-gen, update-locale. (Adjust hostname to particleos-installer for clarity).
    • User Creation: If Calamares handles user creation for the installed system, then the useradd commands for the particle user in the installer ISO might be simplified or removed, focusing only on a temporary live user for the installer session if needed.
    • Service Enabling: systemctl enable sddm NetworkManager ssh.
    • apt-ostree configuration: ref: particleos/installer/1.0.0 (for the installer environment itself, not the target OS).

3.5. ISO Creation

  • Goal: Package the configured installer environment into a bootable ISO.
  • Steps:
    • Kernel/Initrd: Copy the minimal kernel and initrd from the chroot. (No change)
    • SquashFS: Create the filesystem.squashfs from the chroot. This will now contain Calamares, bootc, and minimal system. (No change)
    • GRUB/ISOLINUX Configuration:
      • Adjust grub.cfg and isolinux.cfg to primarily offer an "Install ParticleOS" option.
      • The kernel boot parameters will need to include live-installer/installer/language=en_US (or similar Calamares-specific options) to automatically launch Calamares.
      • Consider a "Boot to Shell" option for debugging.
    • EFI Boot Image: Remains the same.

Phase 4: Atomic OS Image (Separate Build Process)

Role: This is the actual ParticleOS image that bootc will deploy. It's crucial that this image exists and is accessible from the installer environment.

Details:

  • Technology: This image should be a bootc OCI image.
  • Creation: It would be built using a separate Containerfile (or Dockerfile) that looks something like this: 
    # Containerfile for ParticleOS Atomic Image
FROM registry.fedoraproject.org/fedora-bootc:latest # Or a minimal Ubuntu base
# FROM ubuntu:noble-base # If building from scratch with bootc-cli installed

# Install core OS components for your atomic system
# Example:
RUN dnf install -y plasma-desktop firefox # Or apt install on Ubuntu base
# RUN apt install -y kubuntu-desktop firefox # Example for Ubuntu base

# Define your immutable system's configuration
# (e.g., users, services, custom applications)

# Set the default entrypoint for the installed system
CMD ["/usr/lib/systemd/systemd"]
  • Registry: This image must be pushed to a publicly accessible or authenticated container registry (e.g., registry.example.com/particleos:latest). The Calamares installer will pull from this registry.

Implementation Considerations & Challenges

  1. Calamares Configuration Detail: The YAML files for Calamares are extensive. You'll need to study Calamares' documentation (especially for settings.conf, partition.conf, users.conf, and script modules) to tailor it precisely.
  2. bootc Parameters: The bootc install command has many options (--target-device, --target-image, --root-partition, --boot-partition, --boot-efi-partition, --kargs, etc.). The particleos-bootc-install.sh script needs to correctly map Calamares' chosen installation parameters to bootc's arguments.
  3. Network Connectivity in Installer: Ensure the installer environment reliably gets network access (DHCP, DNS) so bootc can pull the atomic image. NetworkManager and plasma-nm are key here.
  4. Error Reporting: Make sure the particleos-bootc-install.sh script provides clear error messages that Calamares can display to the user if the bootc installation fails.
  5. User Experience: Design the Calamares workflow to be intuitive for an atomic OS. For instance, the partitioning step might be simplified, or custom text added to explain the immutable nature.
  6. Testing Iterations: This will require multiple build-test cycles. Use QEMU to quickly test the ISO.

This detailed plan provides a solid roadmap for building your ParticleOS atomic installer ISO. The next step would be to start implementing the changes in build-in-container.sh, focusing on the mmdebstrap includes and the core Calamares/bootc integration.