This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

butterknife

Build & contributor reference for butterknife — the archinstall-style TUI installer for Debian 13. For the user-facing overview of how it fits into the Butterbian family, see Butterbian.

Source: justaguy.dev/drew/butterknife

---

Architecture

Python + urwid TUI, no pip dependencies (urwid ships in Debian as python3-urwid). The installer doesn't depend on live-build or Calamares — build-iso.sh calls debootstrap + mksquashfs + grub-mkrescue directly.

Project structure

butterknife/
├── build-rootfs.sh       Build a Debian rootfs tarball (offline install support)
├── build-iso.sh          Build a bootable installer ISO
├── butterknife           The installer entry point
├── lib/                  Python modules (TUI screens, installer logic)
├── overlay/              Files copied into the installed system
│   └── usr/lib/jagl/
│       └── wm-chooser    Post-install window manager selector
├── HOWTO.md              Long-form walkthrough of the build pipeline
└── VERSION               Version string the build scripts read

Python modules (lib/)

File	Purpose
config.py	Config dataclass holding all user selections (disk, filesystem, encrypt/luks_pass, locale, timezone, keymap, hostname, user, sshd). ready() gates the install button.
app.py	urwid App class: palette, main Frame, menu↔subscreen navigation, keybindings
screens.py	One function per screen: network, filesystem, keyboard, timezone, locale, disk, hostname, user, sshd, summary, chroot_recovery, drop_to_shell. Wi-Fi scan/connect uses nmcli.
installer.py	The actual install: partition_disk (GPT, UEFI/BIOS), LUKS setup, format, mount, install_base (tarball extract or debootstrap), configure_system (fstab, locale, users, zram, wm-chooser sudoers), _configure_btrfs_snapshots (timeshift + grub-btrfs + apt pre-invoke hook), install_bootloader, cleanup
widgets.py / utils.py	urwid helpers and shell/network utilities

Entry point (butterknife)

Checks root, detects boot mode (UEFI/BIOS) and install method (tarball vs debootstrap), waits briefly for network, launches the TUI, and hands off to the installer when the user confirms.

---

Build pipeline

There are two scripts. Run them on a Debian-based development machine.

Prerequisites

sudo apt install debootstrap xorriso grub-efi-amd64-bin grub-pc-bin mtools squashfs-tools zstd

build-rootfs.sh — the offline rootfs tarball

Bundles a complete Debian system into rootfs.tar.zst. Optional but strongly recommended — without it, the ISO has to debootstrap from the internet at install time (10–20 min vs. <1 min from the tarball).

sudo bash build-rootfs.sh

Steps the script runs:

1. debootstrap — pulls a minimal Debian Trixie root into /tmp/work
2. chroot in — bind-mounts /dev, /dev/pts, /proc, /sys first
3. apt install — kernel, bootloader, NetworkManager, firmware, CLI tools, with DEBIAN_FRONTEND=noninteractive
4. clean — apt-get clean to drop cached .debs
5. tar — compresses the whole tree to rootfs.tar.zst with zstd

Note: zstd must be present in both the rootfs (so update-initramfs uses zstd compression) and the live ISO env (so tar --zstd can extract during install). Without zstd in the live env, extraction silently produces an empty root.

build-iso.sh — the bootable installer

Builds the live environment and packs it into a hybrid (USB + DVD) ISO. If rootfs.tar.zst is present, it gets bundled inside.

sudo bash build-iso.sh

Output: butterknife-<version>-trixie-<YYYYMMDD>.iso in the project root, with matching .sha256 and .torrent.

The ISO auto-launches butterknife on tty1 — boot, run.

---

Feature status

Implemented:

• BTRFS with subvolume layout (@, @home, @snapshots, @var_log, @var_cache, @var_tmp)
• Timeshift + grub-btrfs with apt pre-invoke snapshot hook
• zram swap (50% RAM, no swap partition)
• LUKS encryption (ext4 / xfs only — not BTRFS)
• SSHD opt-in
• Chroot recovery (mount + chroot into an existing install from the live env)
• WM chooser — post-install first-login selection from JustAGuyLinux setup repos
• ext4 / BTRFS / xfs filesystem choice

---

Key design decisions

• No live-build — debootstrap directly, both for the live env and the installed system
• No Calamares — all installation logic is in butterknife itself
• Offline capable — if rootfs.tar.zst is bundled in the ISO, no internet required for the base install
• Erase-only partitioning — full disk, GPT. No dual-boot, no manual partitioning.
• No pip dependencies — python3-urwid is the only non-stdlib Python package, and it's in Debian

---

Related projects

• Butterbian — user-facing overview
• Butterbian-XFCE — full-desktop counterpart with Calamares
• WM setup repos on Butterforge: awesomewm-setup, bspwm-setup, dwm-setup (wiki), i3-setup, openbox-setup, qtile-setup, sway-setup, swayfx-setup. butterknife's WM picker installs whichever you choose.
• butterknife-bash — the original bash installer, kept as reference; not invoked