particleos-installer/calmares_plan.md

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.