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:** ```bash 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):** ```bash #!/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: ```dockerfile # 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.