======================================================================== MUPPY 10 SYSTEM HANDBOOK ======================================================================== ------------------------------------------------------------------------ CHAPTER 1: WHAT IS MUPPY 10? ------------------------------------------------------------------------ Muppy 10 is a ultra-lean, custom-built, Debian-based Linux live distribution designed to run entirely in RAM. Weighing in at approximately 470 MB, it provides a lightweight X11 window management environment (powered by IceWM or a custom Vala/C window manager like `mu-wm`) coupled with Picom compositing and customized system HUDs (`tech-hud`). Key Features: - Pure RAM Execution: System files are loaded into RAM during boot for blazing-fast performance and zero disk wear. - Minimal Footprint: Built directly from Debian stable using `mmdebstrap` without unnecessary bloat or standard desktop environment overhead. - Dual-Boot Ready: Can easily run alongside host OS installations like Linux Mint 22.3 without touching existing partitions. - Failsafe Modular Build System: Allows quick live modifications via chroot and fast ISO repacking within seconds. ------------------------------------------------------------------------ CHAPTER 2: EXTENDING & CUSTOMIZING MUPPY (SYNAPTIC / APT & MOUNTING ISOS) ------------------------------------------------------------------------ 2.1 MANAGING PACKAGES WITH APT & SYNAPTIC ----------------------------------------- Muppy 10 comes pre-installed with standard Debian package management tools including `apt` and the graphical `synaptic` package manager. To install new software inside a running Muppy session or inside the chroot: - Using the Terminal: sudo apt update sudo apt install - Using Graphical Synaptic: Launch Synaptic from the menu or terminal (`sudo synaptic`), click "Reload" to update package indexes, search for desired software, mark for installation, and click "Apply". Note: Any packages installed during a standard RAM session will disappear upon reboot unless persistence is configured or changes are committed directly into the build environment (see Chapter 6). 2.2 HOW TO MOUNT AND INSPECT AN ISO FILE ---------------------------------------- If you want to extract files, check contents, or copy the live SquashFS from an existing `muppy10-amd64.iso` file on your host system without booting it, you can mount the ISO file as a loop device: 1. Create a mount directory: sudo mkdir -p /mnt/iso 2. Mount the ISO in read-only mode: sudo mount -o loop /path/to/muppy10-amd64.iso /mnt/iso 3. Inspect or copy files: ls -la /mnt/iso ls -la /mnt/iso/live/ # Contains filesystem.squashfs 4. Unmount when finished: sudo umount /mnt/iso ------------------------------------------------------------------------ CHAPTER 3: RUNNING MUPPY 10 (QEMU & PC RAM BOOT) ------------------------------------------------------------------------ 3.1 STARTING IN A LOCAL QEMU VIRTUAL MACHINE -------------------------------------------- To test your build instantly inside a virtual machine without rebooting your hardware: 1. Install QEMU on your host: sudo apt update sudo apt install -y qemu-system-x86 2. Launch the ISO in QEMU (with 2 GB RAM and KVM hardware acceleration): qemu-system-x86_64 -m 2048 -enable-kvm -cdrom muppy10-amd64.iso 3.2 STARTING ON YOUR PC FROM A LIVE USB (RAM MODE) -------------------------------------------------- To boot Muppy 10 on bare-metal hardware using a bootable USB flash drive: 1. Write the ISO to a USB flash drive (replace `/dev/sdX` with your drive): sudo dd if=muppy10-amd64.iso of=/dev/sdX bs=4M status=progress conv=fsync 2. Insert the USB drive into your target PC and boot into your system BIOS/UEFI. 3. Select the USB drive from the boot menu. 4. Select "Muppy 10 (RAM Mode)" in GRUB. System Behavior in RAM Mode: The entire root filesystem (`filesystem.squashfs`) is uncompressed into system RAM. The USB drive can be safely removed after booting. All temporary files, browser histories, and system tweaks remain strictly in RAM and are completely wiped when power is turned off. ------------------------------------------------------------------------ CHAPTER 4: INSTALLING MUPPY TO YOUR PC (RAM MODE / NON-PERSISTENT) ------------------------------------------------------------------------ If you have a host OS like Linux Mint 22.3 installed on your Mini-PC or SSD, you can install Muppy 10 directly onto a dedicated partition (or external USB) so it boots from local storage into RAM without needing a USB installer stick. HOW IT WORKS: GRUB loads the kernel and initrd directly from your local disk, uncompresses `filesystem.squashfs` into system RAM, and runs Muppy at full RAM speed. Changes made during the session are NOT saved back to the disk. STEP 1: PREPARE THE TARGET PARTITION (USING GPARTED) ---------------------------------------------------- 1. Open GParted (`sudo gparted`). 2. Select your target disk (e.g., `/dev/sda` or external drive `/dev/sdb`). 3. Create/format a partition with the following parameters: - Filesystem: `ext4` - Label: `MUPPY10` - Flags: Set `boot` (or `legacy_boot`) on the partition. STEP 2: COPY MUPPY LIVE FILES TO THE TARGET PARTITION ------------------------------------------------------ 1. Mount your new partition: sudo mkdir -p /mnt/muppy sudo mount /dev/sdb1 /mnt/muppy # Replace /dev/sdb1 with your partition 2. Create the required directory structure: sudo mkdir -p /mnt/muppy/live 3. Copy the live kernel, initrd, and SquashFS files: # You can copy directly from your build directory or a mounted ISO: sudo cp -av /tmp/muppy10-build/iso/live/filesystem.squashfs /mnt/muppy/live/ sudo cp -av /tmp/muppy10-build/iso/vmlinuz /mnt/muppy/ sudo cp -av /tmp/muppy10-build/iso/initrd.img /mnt/muppy/ 4. Unmount the partition: sudo umount /mnt/muppy STEP 3: INTEGRATE WITH LINUX MINT GRUB -------------------------------------- 1. Open `/etc/grub.d/40_custom` in your Linux Mint host text editor: sudo geany /etc/grub.d/40_custom 2. Add the following entry at the bottom of the file: menuentry "Muppy 10 Live (RAM Mode from SSD)" { search --no-floppy --set=root --label MUPPY10 linux /vmlinuz boot=live live-media-path=/live keyboard-layouts=us quiet splash initrd /initrd.img } 3. Update GRUB configuration: sudo update-grub Reboot your PC and select "Muppy 10 Live (RAM Mode from SSD)" from the GRUB menu. ------------------------------------------------------------------------ CHAPTER 5: INSTALLING MUPPY TO YOUR PC (WITH PERSISTENT STORAGE) ------------------------------------------------------------------------ If you want Muppy 10 to act as a fully installed OS that saves your files, installed packages, user configurations, and scripts across reboots, configure Debian `live-boot` persistence. HOW IT WORKS: Muppy still boots the base SquashFS into RAM for performance, but an overlay filesystem continuously writes and reads system modifications to an `ext4` persistence partition on disk. STEP 1: PREPARE PERSISTENCE PARTITION ------------------------------------- 1. Open GParted (`sudo gparted`). 2. Format a partition with `ext4`. 3. CRITICAL: Set the Partition Label to exactly: `persistence` STEP 2: CREATE PERSISTENCE CONFIGURATION FILE --------------------------------------------- 1. Mount the persistence partition: sudo mkdir -p /mnt/persistence sudo mount /dev/sdb2 /mnt/persistence # Replace with your partition 2. Write the overlay rule into `persistence.conf`: echo "/ union" | sudo tee /mnt/persistence/persistence.conf *(Explanation: `/ union` directs the system to merge all changes made across the entire root filesystem `/` directly onto this partition).* 3. Unmount the partition: sudo umount /mnt/persistence STEP 3: ADD PERSISTENT BOOT ENTRY TO GRUB ----------------------------------------- 1. Open `/etc/grub.d/40_custom` on your Linux Mint host: sudo geany /etc/grub.d/40_custom 2. Add a new menu entry containing the `persistence` parameter: menuentry "Muppy 10 (Persistent Mode)" { search --no-floppy --set=root --label MUPPY10 linux /vmlinuz boot=live live-media-path=/live persistence keyboard-layouts=us quiet splash initrd /initrd.img } 3. Update GRUB: sudo update-grub Now, whenever you boot into "Muppy 10 (Persistent Mode)", any file created in `/home/live`, any configuration changed, or any package installed via `apt` will automatically persist across reboots! ------------------------------------------------------------------------ CHAPTER 6: CREATING & REBUILDING YOUR OWN ISO ------------------------------------------------------------------------ 6.1 PREREQUISITES FOR THE HOST SYSTEM ------------------------------------- Run the following command on your Linux Mint/Debian host to install all required build tools: sudo apt update sudo apt install -y mmdebstrap squashfs-tools xorriso grub-pc-bin debian-archive-keyring 6.2 PREPARING CUSTOM BINARIES (OPTIONAL) ---------------------------------------- Place compiled Vala/C binaries (`mu-wm`, `tech-hud`) into `./custom-bin`: mkdir -p ./custom-bin cp /path/to/your/mu-wm ./custom-bin/ cp /path/to/your/tech-hud ./custom-bin/ 6.3 FULL INITIAL BUILD PROCESS ------------------------------ Run `build-muppy10.sh` as root to assemble the chroot and generate the ISO: chmod +x build-muppy10.sh enter-chroot.sh rebuild-iso.sh sudo ./build-muppy10.sh 6.4 FAILSAFE MODIFY & FAST-REBUILD WORKFLOW ------------------------------------------- To edit the OS without re-downloading Debian packages: 1. Enter Chroot: sudo ./enter-chroot.sh (Make your changes, install packages, edit configs, then type `exit`). 2. Rebuild ISO in seconds: sudo ./rebuild-iso.sh 6.5 BACKING UP YOUR BUILD FROM /tmp ----------------------------------- Since `/tmp/muppy10-build` is cleared on host reboot, save your chroot state: sudo cp -a /tmp/muppy10-build ~/muppy10-build-backup To restore after a reboot: sudo mkdir -p /tmp/muppy10-build sudo cp -a ~/muppy10-build-backup/* /tmp/muppy10-build/ ========================================================================