======================================================================== MUPPY 10 BUILD INSTRUCTIONS ======================================================================== OVERVIEW & ARCHITECTURE: ------------------------ This build system creates a minimal, fast Debian-based live ISO ("Muppy 10") in RAM mode. The build environment lives in `/tmp/muppy10-build`. - `/tmp/muppy10-build/chroot`: The uncompressed root filesystem of your live OS. - `/tmp/muppy10-build/iso`: The staging directory for GRUB and SquashFS. *NOTE ON /tmp STORAGE:* Because `/tmp` is cleared upon system reboot, ensure you back up your chroot directory or script modifications before shutting down your host system! ======================================================================== 1. INSTALL HOST PREREQUISITES ======================================================================== Run the following command on your Linux Mint/Debian host to install all required build tools and GPG keyrings: sudo apt update sudo apt install -y mmdebstrap squashfs-tools xorriso grub-pc-bin debian-archive-keyring ======================================================================== 2. PREPARE CUSTOM BINARIES (OPTIONAL) ======================================================================== If you have custom compiled Vala/C binaries (such as mu-wm or tech-hud), place them into a directory named 'custom-bin' in the project root: mkdir -p ./custom-bin cp /path/to/your/mu-wm ./custom-bin/ cp /path/to/your/tech-hud ./custom-bin/ If no 'custom-bin' folder exists, the build script will automatically fall back to IceWM as the default window manager. ======================================================================== 3. FULL INITIAL BUILD ======================================================================== Make the main build script executable and run it with root privileges. This will download Debian stable packages, assemble the chroot, and build the initial ISO (~470 MB): chmod +x build-muppy10.sh enter-chroot.sh rebuild-iso.sh sudo ./build-muppy10.sh ======================================================================== 4. FAILSAFE WORKFLOW: MODIFYING & REBUILDING WITHOUT REDOWNLOADING ======================================================================== To modify the OS without downloading all packages again: STEP A: Enter the Chroot Environment ------------------------------------ Run `enter-chroot.sh` to open an interactive shell inside your live system. Virtual pseudo-filesystems (/proc, /sys, /dev) will be safely mounted. sudo ./enter-chroot.sh Inside the chroot, you can: - Install packages: `apt update && apt install ` - Edit user configs: Modify `/home/live/.xinitrc` or `/home/live/.config/` - Add binaries directly: Copy files into `/usr/local/bin/` Type `exit` when done. The script will automatically unmount pseudo-filesystems. STEP B: Fast Rebuild of the ISO ------------------------------- Re-generate the SquashFS compression and the GRUB bootable ISO in seconds: sudo ./rebuild-iso.sh ======================================================================== 5. BACKUP YOUR CHROOT (PREVENT DATA LOSS) ======================================================================== Since `/tmp` is wiped on host reboot, create a local backup of your modified chroot directory if you plan to work on it across multiple sessions: sudo cp -a /tmp/muppy10-build ~/muppy10-build-backup To restore a backup into `/tmp` after a host reboot: sudo mkdir -p /tmp/muppy10-build sudo cp -a ~/muppy10-build-backup/* /tmp/muppy10-build/ ======================================================================== 6. TEST THE RESULTING ISO IN QEMU ======================================================================== To quickly test your new ISO in a local QEMU virtual machine: sudo apt install -y qemu-system-x86 qemu-system-x86_64 -m 2048 -enable-kvm -cdrom muppy10-amd64.iso ======================================================================== 7. FREQUENTLY ASKED QUESTIONS (FAQ) ======================================================================== Q: If the system boots to RAM, will it save and where? ------------------------------------------------------------------------ By default, Muppy 10 runs as a pure live RAM system (volatile mode). Any changes made while running the live session are kept exclusively in RAM and are **lost upon reboot**. To enable persistence, you would need to configure `live-boot` persistence parameters in `grub.cfg` and create a dedicated persistence partition or loop file (`persistence`). Q: Can or must the system be installed and how? ------------------------------------------------------------------------ The system **does not have to be installed**—it is designed to run completely standalone from USB/RAM. However, it *can* be installed to a local hard drive if desired. Because this is a minimal custom build, there is no heavy GUI installer pre-configured. Manual installation can be done from within the live environment by partitioning a target drive, copying the root filesystem via `rsync`, and installing GRUB (`grub-install`). Q: How much smaller could we be without Xorg / Picom? ------------------------------------------------------------------------ Dropping `xserver-xorg-core`, video drivers, utilities, and `picom` would reduce the ISO and RAM footprint by roughly **30 to 50 MB**, and save a modest amount of RAM overhead. However, doing so means losing traditional X11 window management. You would have to render your UI (like your Tech-HUD or custom Vala applications) directly via Linux Framebuffer (`/dev/fb0`), DRM/KMS, or a lightweight Wayland compositor instead.