particle-os/roadmap.md

This is an exciting and ambitious project! Based on your goals and chosen tools, here is a detailed roadmap to guide you through building a Debian Atomic Desktop, mirroring the success of ublue-os while using the strengths of the Debian ecosystem.

The roadmap is broken down into four distinct phases, from the foundational build to a polished, distributable product.

---

Phase 1: Foundation & Core Build (The "Hello, World" Image)

Goal: Create a minimal, bootable Debian OSTree image and automate its build. This is your Minimum Viable Product.

Tools: bootc, just, podman/docker

Tasks:

1. Project Scaffolding:

   • Create a new Git repository for your project (e.g., my-debian-atomic-desktop).
   • Create the foundational files: Containerfile and justfile.

2. Define the Base Image (Containerfile):

   • Start with a minimal Debian image.
   • Example Containerfile snippet:

     FROM debian:trixie
     
     # Install essential packages
     RUN apt-get update && apt-get install -y \
         systemd \
         dbus \
         sudo \
         ...
     

   • Focus on only the bare minimum for now. Don't add a desktop yet. The goal is to get a working, bootable command line.

3. Automate the Build (justfile):

   • Create a simple justfile with a recipe to build the container image.
   • Example justfile snippet:

     build-image:
         podman build -t my-debian-atomic:latest .
     
     # Command to clean up
     clean:
         podman rmi my-debian-atomic:latest
     

4. Test the Image:

   • Build the image with just build-image.
   • Test its functionality by deploying it to a VM using bootc.
   • Example just recipe for testing:

     install-vm:
         bootc install to-disk --device /dev/sda --replace-os --image my-debian-atomic:latest qemu-system-x86_64 -hda /var/lib/libvirt/images/my-debian.qcow2
     

   • Verify that you can boot into a working Debian command-line environment.

Deliverable: A minimal, bootable Debian bootc image and a justfile to build and test it.

---

Phase 2: Calamares Installer Integration

Goal: Create a bootable ISO with a Calamares installer that can deploy your atomic image.

Tools: live-build, calamares

Tasks:

1. Build a Live ISO Environment:

   • Use live-build to create a minimal live environment.
   • Configure live-build to include the calamares package and all its dependencies.
   • The live environment will also need access to your bootc image, either by embedding it in the ISO or pointing to a container registry.

2. Configure Calamares:

   • Create a custom Calamares configuration (a set of .yml files).
   • The Partitioning Module: Configure it to create the necessary partitions (e.g., /boot/efi, /, and a separate /boot for bootc).
   • The post-install Module (Crucial Step): Write a script or configure this module to:
     • Run the command bootc install to-disk --device /dev/sda --replace-os --image ghcr.io/your-project/your-image:latest.
     • Handle the bootloader installation, which bootc can assist with.

3. Integrate the Installer Build with just:

   • Add a new recipe to your justfile to orchestrate the live-build process.
   • Example justfile recipe:

     build-iso:
         ./build_live_iso.sh
         # The script would use live-build to create the .iso
     
     test-iso:
         qemu-system-x86_64 -cdrom my-debian-installer.iso -m 2G
     

Deliverable: A bootable .iso that presents a Calamares installer, which successfully installs your minimal atomic image.

---

Phase 3: Advanced Features (The ublue-os Mimicry)

Goal: Add a full desktop environment and a robust solution for building kernel modules like the NVIDIA driver.

Tools: Multi-stage Containerfile builds, podman/docker

Tasks:

1. Add a Desktop Environment:

   • Update your Containerfile from Phase 1 to include a full desktop environment. For example, for KDE Plasma:

     # Inside the Containerfile
     RUN apt-get install -y sddm task-kde-desktop
     

2. Create the Kernel Module Pipeline:

   • Separate Repository: Create a new repository, for example, my-debian-atomic-kmods.
   • Build Containerfile: In this new repo, create a Containerfile to build the NVIDIA driver from source for a specific Debian kernel version.

     # Inside the kmods Containerfile
     FROM debian:trixie
     RUN apt-get update && apt-get install -y build-essential linux-headers-$(uname -r) ...
     RUN cd /path/to/nvidia-source && make KSRC=/usr/src/linux-headers-$(uname -r)
     # Copy the compiled .ko file to a known location
     

   • Build Automation (justfile): Add a just recipe to build and push this new kmods container image to a registry.

3. Integrate the Pre-built Module:

   • Go back to your main Containerfile from Phase 1.
   • Use a multi-stage build. The first stage pulls from your kmods image. The second stage copies the pre-compiled .ko file into the main image's /lib/modules/ directory.
   • Example multi-stage Containerfile snippet:

     # Stage 1: Build or get the kernel module
     FROM ghcr.io/your-project/my-debian-atomic-kmods:latest AS kmods-builder
     
     # Stage 2: Build the final image
     FROM debian:trixie
     # ... (rest of your desktop setup) ...
     
     # Copy the pre-compiled kernel module
     COPY --from=kmods-builder /path/to/nvidia.ko /lib/modules/$(uname -r)/updates/nvidia.ko
     RUN depmod -a $(uname -r)
     

   • This mimics the ublue-os approach: the complex build is isolated and the final product simply integrates the finished artifacts.

Deliverable: A fully-featured desktop image with an integrated, pre-compiled NVIDIA driver, built using a clean, automated pipeline.

---

Phase 4: Polish & Distribution

Goal: Make the project ready for others to use and contribute to.

Tools: GitHub Actions, Git

Tasks:

1. Public Repositories: Ensure your my-debian-atomic-desktop and my-debian-atomic-kmods repositories are public on a platform like GitHub.

2. Set up CI/CD (GitHub Actions):

   • Create workflows in both repositories to automatically build and push new container images whenever you push code.
   • Trigger an automatic build of the kmods repository whenever a new Debian kernel is released.
   • Trigger an automatic build of the main desktop image after the kmods image has been successfully built and pushed.

3. Write Comprehensive Documentation:

   • Create a README.md that explains the project's goals.
   • Write a guide for users on how to install your desktop using the Calamares ISO.
   • Document the build process for contributors.
   • Explain any custom ujust commands you include.

4. Finalize the User Experience:

   • Add custom desktop branding, wallpapers, and default application choices.
   • Add a ujustfile inside your main Containerfile to provide a user-friendly command line interface for updates and system maintenance.

Deliverable: A stable, automated, and well-documented project with a polished user experience, ready for public consumption.