stormG & stormFS Builder Suite

Build your own custom Gentoo or LFS+scratchpkg live ISO with a butterknife-style TUI installer

Overview

The stormG & stormFS Builder Suite provides two single-script solutions for building custom live Linux ISOs with a user-friendly, archinstall-style TUI installer. Both scripts are cross-distro – they run on any Linux distribution (Arch, Debian/Ubuntu, Fedora, openSUSE, Gentoo, Void, LFS+scratchpkg, etc.).

Project	Base System	Package Manager	Init System	Desktop Options
stormG	Gentoo Linux	Portage (emerge)	OpenRC	Xfce, KDE Plasma 6, i3, sway, hyprland, awesome, bspwm
stormFS	LFS + scratchpkg	scratch (scratchpkg)	rc (scratchpkg)	Xfce, KDE Plasma 6, i3, sway, hyprland, awesome, bspwm

Features

• Butterknife-style TUI installer – Python + urwid with a simple menu-driven interface
• Full desktop support – Xfce (with custom themes/configs), KDE Plasma 6, and window managers
• Complete driver support – NVIDIA (proprietary), AMDGPU, ATI, Intel, VMware, VirtualBox
• Service management – DBus, ALSA, NTP, Bluetooth enabled on boot
• Custom GRUB themes – gentoo-glass (stormG) and StormFS (stormFS)
• Plymouth boot splash – stormG and stormFS branded themes
• Custom assets – Wallpapers, icons, GTK themes, and whiskermenu icons
• Resume capability – If the build fails, re-run to continue from where it left off
• Cross-distro – Works on any Linux distribution; no host dependencies (besides build tools)

What's Included

stormG (Gentoo)

• Base: stage3-amd64-desktop-openrc (latest)
• Kernel: sys-kernel/gentoo-kernel-bin with dracut
• Bootloader: GRUB with gentoo-glass theme
• Display Manager: LightDM via display-manager OpenRC service
• Desktop: Xfce (with catalyst_stormg configs) or KDE Plasma 6
• Window Managers: i3, sway, hyprland, awesome, bspwm
• Drivers: NVIDIA, AMDGPU, ATI, Intel, VMware, VirtualBox
• Extra Packages: broadcom-sta, ZFS, timeshift, htop, fastfetch, firefox-bin, neovim, mousepad
• Installer: Python TUI with urwid (butterknife-style)

stormFS (LFS + scratchpkg)

• Base: LFS minimal rootfs with scratchpkg
• Package Manager: scratch (scratchpkg) with scratch sysup
• Service Manager: rc from scratchpkg (via /etc/rc.conf)
• Bootloader: GRUB with StormFS custom theme
• Display Manager: LightDM (autologin for liveuser)
• Desktop: Xfce (with custom wallpapers, icons, GTK themes)
• Window Managers: i3, sway, hyprland, awesome, bspwm
• Drivers: NVIDIA, AMDGPU, ATI, Intel, VMware, VirtualBox
• Extra Packages: stormpkg, broadcom-sta, ZFS, timeshift, htop, fastfetch, firefox-bin, neovim, mousepad
• Custom Assets: LFS1.png (wallpaper), LFS3.png (GRUB), LFS-logo-2.png (whiskermenu), custom GTK/icon themes
• Installer: Python TUI with urwid (butterknife-style)

Dependencies

Host System Requirements

Tool	Package (common names)	Purpose
wget	wget	Downloading stage3 and snapshots
tar	tar	Extracting tarballs
mksquashfs	squashfs-tools / squashfs	Creating the squashfs filesystem
xorriso	xorriso / libisoburn	Building the ISO
grub-mkimage	grub / grub2 / grub2-tools	Creating GRUB boot images
grub-mkstandalone	grub / grub2	Creating UEFI GRUB image
mkfs.vfat	dosfstools	Creating FAT filesystem for EFI
mcopy	mtools	Copying files to FAT images
git	git	Cloning configuration repositories
python3	python / python3	Running the installer
pip3	python3-pip / python-pip	Installing Python dependencies
systemd-nspawn (optional)	systemd	Faster chroot (falls back to plain chroot)
chroot	coreutils	Required for chroot environment

For stormFS only: scratch (scratchpkg) – required for building the LFS rootfs. For stormG only: No additional host requirements beyond the tools above.

Install Dependencies by Distribution

RPM-based (Fedora/RHEL/CentOS): sudo dnf install -y wget tar squashfs-tools xorriso grub2 grub2-tools dosfstools mtools git python3 python3-pip

openSUSE (SUSE-based): sudo zypper install -y wget tar squashfs xorriso grub2 dosfstools mtools git python3 python3-pip

Arch Linux (Pacman): sudo pacman -Syu --needed wget tar squashfs-tools xorriso grub dosfstools mtools git python python-pip

Gentoo (Portage): sudo emerge --sync sudo emerge -av wget tar squashfs-tools xorriso grub dosfstools mtools git dev-lang/python dev-python/pip

Void Linux (XBPS): sudo xbps-install -Syu sudo xbps-install -S wget tar squashfs-tools xorriso grub dosfstools mtools git python3 python3-pip

Alpine Linux (APK): sudo apk update sudo apk add wget tar squashfs-tools xorriso grub dosfstools mtools git python3 py3-pip

APT-based (Debian/Ubuntu): sudo apt update sudo apt install -y wget tar squashfs-tools xorriso grub-pc grub-efi-amd64 dosfstools mtools git python3 python3-pip

Quick Start

Step 1: Install Dependencies – Choose your distribution from the list above and install the required tools.

Step 2: Download the Scripts: git clone https://github.com/yourusername/stormg-stormfs-builder.git cd stormg-stormfs-builder Or download individual scripts: wget https://raw.githubusercontent.com/yourusername/stormg-stormfs-builder/main/stormg-builder.sh wget https://raw.githubusercontent.com/yourusername/stormg-stormfs-builder/main/stormfs-builder.sh

Step 3: Make Scripts Executable: chmod +x stormg-builder.sh stormfs-builder.sh

Step 4: Build an ISO: For stormG (Gentoo-based): sudo ./stormg-builder.sh For stormFS (LFS+scratchpkg-based): sudo ./stormfs-builder.sh

Step 5: Boot and Install: dd if=stormg-linux-*.iso of=/dev/sdX bs=4M status=progress Boot from USB and follow the TUI installer

Building the ISO

Build stormG (Gentoo-based): sudo ./stormg-builder.sh Build stormFS (LFS+scratchpkg-based): sudo ./stormfs-builder.sh

Build Process Overview:

1. Detects your host distribution
2. Checks for required tools
3. Downloads and extracts the base system
4. Installs all required packages
5. Applies custom themes and configurations
6. Builds the squashfs
7. Creates the bootable ISO
8. Outputs: stormg-linux-YYYYMMDD.iso or stormfs-linux-YYYYMMDD.iso

Output Location:

• stormg-linux-YYYYMMDD.iso – Gentoo-based live ISO
• stormfs-linux-YYYYMMDD.iso – LFS+scratchpkg-based live ISO

ISO Size: stormG | 1.5 - 2.5 GB | Includes Xfce, drivers, and extra packages stormFS | 1.0 - 2.0 GB | Includes Xfce, custom assets, and stormpkg

Using the Installer

Boot the ISO:

1. Write the ISO to a USB drive: dd if=stormg-linux-*.iso of=/dev/sdX bs=4M status=progress
2. Boot from the USB (BIOS or UEFI)
3. The live environment will start and automatically launch the TUI installer

Installer Menu Flow: Step 1 – Select disk: Choose from available drives Step 2 – Partitioning: Automatic (recommended) or Manual (cfdisk) Step 3 – Filesystem: ext4, btrfs, xfs, or zfs Step 4 – Desktop/WM: Xfce, KDE Plasma 6, i3, sway, hyprland, awesome, bspwm Step 5 – Credentials: Set hostname, root password, optional user account

Installation Process:

1. Partitions the disk
2. Formats the partitions
3. Extracts the rootfs tarball
4. Installs the selected desktop/WM
5. Installs drivers
6. Configures services
7. Sets up GRUB bootloader
8. Reboot when complete

Customizing the Build

stormG Customization: Package list – stormg-builder.sh -> build.sh -> emerge lines – Add/remove packages Xfce configs – https://github.com/bfitzgit23/catalyst_stormg – Clone and modify GRUB theme – sys-boot/gentoo-grub-themes – Change theme package Plymouth theme – /usr/share/plymouth/themes/stormg – Modify script/logo Wallpaper – /usr/share/backgrounds/ – Add your own images

stormFS Customization: Assets – https://github.com/bfitzgit23/StormFS-Linux – Clone and modify GRUB theme – StormFS/grub-themes/StormFS/ – Modify theme.txt and assets Wallpaper – StormFS/backgrounds/ – Add your own images Icons – StormFS/icons/ – Add custom icon theme GTK theme – StormFS/themes/ – Add custom GTK theme Package list – stormfs-builder.sh -> build.sh -> scratch install lines – Add/remove packages stormpkg – /usr/bin/stormpkg on host – Ensure it exists for inclusion

Script Structure

stormg-builder.sh:

• PREP – Clean and prepare workspace
• STAGE3 – Download Gentoo stage3 tarball
• SNAPSHOT – Fetch Portage snapshot
• PORTAGE – Configure Portage
• BUILD SCRIPT – Generate build.sh
• RUN BUILD – Execute chroot build
• CLONE CONFIGS – Get Xfce configs from catalyst_stormg
• COPY GRUB THEME – Copy gentoo-glass theme to ISO
• EMBED INSTALLER – Embed Python TUI installer
• SQUASHFS – Create squashfs
• ISO BUILD – Create bootable ISO

stormfs-builder.sh:

• PREP – Clean and prepare workspace
• FETCH ASSETS – Clone StormFS-Linux repo
• LFS BASE – Create minimal LFS rootfs
• SCRATCHPKG – Install packages via scratchpkg
• BUILD SCRIPT – Generate build.sh
• RUN BUILD – Execute chroot build
• COPY GRUB THEME – Copy StormFS theme to ISO
• EMBED INSTALLER – Embed Python TUI installer
• SQUASHFS – Create squashfs
• ISO BUILD – Create bootable ISO

Troubleshooting

Common Issues: 404 on stage3 download – Update to latest current-stage3-amd64-desktop-openrc.tar.xz URL Missing nproc command – Ensure coreutils is installed on your host pkgadd not found – Ensure scratchpkg is fully installed Chroot mount errors – Scripts handle this automatically grub-bios-setup errors – Scripts use grub-mkimage directly ISO >4GB – Scripts use iso-level 3 for large files Virtual filesystem errors – Scripts mount /proc, /sys, /dev before chrooting Python urwid not found – Run pip3 install urwid in the live environment LightDM not starting – Ensure DISPLAYMANAGER="lightdm" in /etc/conf.d/display-manager Network not working – Ensure NetworkManager service is enabled

Distribution-Specific Issues: Debian/Ubuntu: sudo apt install xorriso; sudo apt install grub-common Fedora/RHEL: sudo dnf install xorriso; sudo dnf install grub2-tools openSUSE: sudo zypper install squashfs; sudo zypper install libisoburn Gentoo: sudo emerge -av sys-apps/coreutils sys-fs/squashfs-tools app-cdr/xorriso sys-boot/grub

Debug Mode: bash -x ./stormg-builder.sh ./stormg-builder.sh 2>&1 | tee build.log

Resume After Failure

Both scripts use a state directory (.state/) to track progress. If a build fails:

1. Fix the issue (e.g., install missing dependencies)
2. Simply re-run the script: sudo ./stormg-builder.sh or sudo ./stormfs-builder.sh

The script will resume from the last completed step, saving hours of re-download and re-build time.

State Files:

• prep – workspace prepared
• stage3 – stage3 downloaded and extracted
• snapshot – Portage snapshot fetched
• portage – Portage configured
• build – Chroot build completed
• xfce_configs – Xfce configs cloned
• grub_theme – GRUB theme copied
• squashfs – Squashfs created
• iso – ISO built

To force a rebuild from scratch: rm -rf .state/; sudo ./stormg-builder.sh

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin feature/my-feature
5. Open a Pull Request

Contribution Guidelines:

• Follow the existing code style
• Test your changes on at least one distribution
• Update the README if adding new features
• Keep scripts POSIX-compliant where possible

License

MIT License

Copyright (c) 2026 stormG & stormFS Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Acknowledgements

• Butterknife – Original inspiration for the TUI installer design
• catalyst_stormg – Xfce configurations and themes
• StormFS-Linux – Custom assets and themes for stormFS
• linuxliveiso – Framework inspiration for ISO building
• Gentoo Linux – The base system for stormG
• LFS + scratchpkg – The base system for stormFS
• Venom Linux – scratchpkg package manager

Support

Bug reports – GitHub Issues Feature requests – GitHub Issues Questions – GitHub Discussions

Comparison Table

Feature | stormG | stormFS Base System | Gentoo Linux | LFS + scratchpkg Package Manager | Portage (emerge) | scratchpkg (scratch) Service Manager | OpenRC | rc (scratchpkg) Build Time | Long (compiles from source) | Medium (binary packages) Customization | Extremely flexible | Flexible GRUB Theme | gentoo-glass | StormFS custom Plymouth Theme | stormG | stormFS Xfce Configs | catalyst_stormg | StormFS-Linux Default DE | Xfce | Xfce KDE Support | Yes | Yes WM Support | Yes | Yes Driver Support | Full | Full Cross-Distro Host | Yes | Yes Resume on Failure | Yes | Yes Custom Assets | Limited | Extensive stormpkg | No | Yes