Butterbian XFCE

Build & contributor reference for the Butterbian-XFCE edition — the graphical, Calamares-installed ISO. For the user-facing overview see Butterbian.

Source: justaguy.dev/drew/Butterbian-XFCE

---

Architecture

This is a live-build project. The ISO is a Debian Trixie live system with XFCE; install-to-disk is handled by Calamares with a partitioning module locked to BTRFS + the Butterbian subvolume layout.

Layers

Layer	Path	What lives here
Distribution	config/bootstrap	Pinned to trixie, archive areas main contrib non-free non-free-firmware
Package list	config/package-lists/live.list.chroot	Everything that ends up in the live env and the installed system. Bootloader packages (grub-efi-amd64, shim-signed) live here so installs work offline.
Calamares config	config/includes.chroot_after_packages/etc/calamares/	Installer modules and branding
Post-install hook	config/includes.chroot_after_packages/usr/lib/jagl/calamares-post-install	Runs inside the installed system via Calamares shellprocess. Configures Timeshift, zram, removes live autologin, removes Calamares itself.
Chroot hooks	config/hooks/normal/	0100-grub-btrfs.hook.chroot builds grub-btrfs from source (it's not in Debian repos) and enables grub-btrfsd.
Apt snapshot hook	config/includes.chroot_after_packages/etc/apt/apt.conf.d/80timeshift-snapshot	Installed into the target system; triggers a Timeshift snapshot before every dpkg operation.

Calamares modules of note

• partition.conf — BTRFS-only, erase mode, GPT, no swap partition, no manual partitioning
• mount.conf — defines the subvolumes: @ → /, @home, @snapshots → /.snapshots, @var_log, @var_cache, @var_tmp
• shellprocess.conf — runs calamares-post-install after install completes
• settings.conf — Calamares module sequence

---

Build commands

Requires a Debian-based host with live-build installed.

sudo apt install live-build

Full clean build (use after config changes)

sudo bash build.sh

That runs lb clean and lb build, then renames the output to butterbian-xfce-<version>-trixie-<YYYYMMDD>.iso.

Faster: chroot-only clean

Preserves the trixie bootstrap cache between iterations:

sudo lb clean && sudo lb build 2>&1 | tee /tmp/lb-build.log

Full purge (use when switching distributions)

sudo lb clean --purge && sudo lb config && sudo lb build 2>&1 | tee /tmp/lb-build.log

Output

butterbian-xfce-<version>-trixie-<YYYYMMDD>.iso in the project root, with matching .sha256 and .torrent artifacts (release process).

---

Key design decisions

• No swap partition — zram-tools provides compressed swap at 50% RAM
• BTRFS subvolumes — @var_log, @var_cache, @var_tmp are separate so they're excluded from Timeshift snapshots automatically
• grub-btrfs built from source — not available in Debian repos; the chroot hook clones and installs it
• Timeshift do_first_run: true — UUID is auto-detected on first boot since it's unknown at build time
• Offline installation — all packages including grub/shim must be in the squashfs; Calamares cannot rely on internet access during install
• Erase-only partitioning — allowManualPartitioning: false, only BTRFS available, ensuring subvolumes are always created correctly

---

Branding

Product name: JustAGuyLinux (JAGL). Branding lives in config/includes.chroot_after_packages/etc/calamares/branding/justaguylinux/. ISO volume label: JAGL Trixie.

---

Files in the repo

• build.sh — top-level wrapper: clean, build, rename output
• config/ — live-build configuration tree (everything above)
• README.md — user-facing project description
• RELEASE.md — release procedure
• VERSION — single-line version string the build script reads

After a build, chroot/, cache/, live-image-amd64.*, and various wget-log* files appear in the root — all build artifacts; safe to delete.

---

Related

• Butterbian — user-facing overview of the distro
• Butterknife — the TUI installer counterpart
• DWM Setup wiki — one of the WM-setups butterknife can install