Building Locally

You can build an ISO on your own Linux machine with the same commands CI runs. This suits you if you build often, want to change the pipeline itself, or prefer not to use GitHub.

On Windows or macOS you can still validate and compile a spec, because those steps are plain Python. Building the image and the ISO needs Linux. If you don't have Linux, use Building with GitHub Actions.

What you need

• A 64-bit x86 Linux machine with sudo. CI uses Ubuntu 24.04, so that is the tested host; the commands below are for Ubuntu and Debian.
• About 30 GB of free disk at the very least, and more for Fedora. During assembly the image, its unpacked root filesystem and the finished ISO all exist at once.
• 8 GB of RAM or more. The boot test gives the virtual machine 4 GB.
• An internet connection. The build downloads the base image, packages and the Flatpak apps.
• For boot tests, KVM (hardware virtualization) is strongly recommended. Without it QEMU emulates the CPU and a boot takes many times longer.

Running inside WSL, a container or a virtual machine without nested virtualization hasn't been tried.

1. Install the tools

sudo apt-get update
sudo apt-get install -y --no-install-recommends \
  git python3 python3-venv podman \
  squashfs-tools xorriso grub-pc-bin grub-common mtools dosfstools
# For boot tests in QEMU:
sudo apt-get install -y --no-install-recommends qemu-system-x86 qemu-utils ovmf

On other distributions, install the equivalent packages. The assembler looks for grub-mkimage or grub2-mkimage, and for GRUB's BIOS files in /usr/lib/grub/i386-pc or /usr/lib/grub2/i386-pc.

2. Get the code

git clone https://github.com/Eric-Ness/linuxlive.git
cd linuxlive
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-dev.txt
python -m pytest

The tests need no root and no network, and should all pass.

3. Write or pick a spec

To start, use one of the examples, examples/lawndarts-ubuntu.yaml for instance, or write your own as described in Writing a Spec. A spec can live anywhere; image paths are relative to the spec file.

python -m linuxlive validate examples/lawndarts-ubuntu.yaml

4. Compile

python -m linuxlive compile examples/lawndarts-ubuntu.yaml -o build/ctx

This writes a build context to build/ctx: a Containerfile, the files to copy into the system (rootfs/, including your art and the boot splash), the boot menu (iso/), and iso.env with settings for the assembler. The output directory is replaced if it exists. Nothing is downloaded yet, and the output is the same for the same spec every time.

5. Build the image

sudo podman build --pull=newer -t localhost/lawndarts build/ctx

Use sudo: the assembler runs as root and looks for the image in root's podman storage. --pull=newer fetches a newer base image if there is one. This step installs the base system, the desktop and the kernel. It takes from a few minutes to half an hour, depending on your machine, your connection and the base; Fedora takes longest.

6. Assemble the ISO

sudo bash scripts/assemble-iso.sh build/ctx localhost/lawndarts build/lawndarts.iso
sudo chown "$(id -u):$(id -g)" build/lawndarts.iso build/lawndarts.iso.sha256

The assembler exports the image, installs the spec's Flatpak apps from Flathub, prepares the system for a live boot, compresses it to SquashFS, and writes a hybrid ISO that boots on BIOS and UEFI (with Secure Boot) from a DVD or a USB stick. It also writes build/lawndarts.iso.sha256.

You can tune it with environment variables. Put them after sudo, because sudo drops your environment:

sudo LL_SQUASHFS_LEVEL=9 LL_RMI_AFTER=1 bash scripts/assemble-iso.sh build/ctx localhost/lawndarts build/lawndarts.iso

Variable	Default	What it does
LL_SQUASHFS_LEVEL	15	zstd compression level. Lower is faster to build and a little bigger. CI uses 9.
LL_RMI_AFTER	off	1 deletes the podman image once it is exported, to free disk space.
LL_KEEP_WORK	off	1 keeps the work directory (in /var/tmp, or $TMPDIR if set) for debugging.

7. Look inside the ISO

python -m linuxlive inspect-iso build/lawndarts.iso

This prints a JSON report of what makes the ISO bootable: the El Torito boot catalog (a BIOS and a UEFI entry), the MBR and GPT used when it is written to a USB stick (including the EFI system partition), and the size of each key file: the Secure Boot shim (EFI/BOOT/BOOTX64.EFI), GRUB, the kernel, the initramfs and the compressed system. Add --json report.json to also save it to a file, or --no-checksum to skip the SHA-256 of the whole image, which takes a while.

inspect-iso reads the file directly, without mounting it or calling other tools, so it also works on Windows and macOS. Use it to check an ISO you downloaded.

8. Boot it

Boot it in QEMU with the project's test script, or in VirtualBox or on a USB stick: see Testing and Booting.

Building a second time

Build steps are cached by podman, so a rebuild after a small change to the spec is faster. To start clean:

sudo podman rmi localhost/lawndarts
sudo podman system prune --all

Troubleshooting

Problem	Fix
[assemble-iso] error: must run as root	Run the assembler with sudo.
iso.env not found; run 'python -m linuxlive compile' first	The first argument must be the directory compile wrote.
mksquashfs is not installed (or xorriso, mkfs.vfat, mmd, mcopy, podman)	Install the packages from step 1.
GRUB i386-pc files not found (install grub-pc-bin)	Install grub-pc-bin.
The assembler can't find the image	You built it without sudo, so it's in your own podman storage. Build it again with sudo.
"No space left on device"	Free space, use LL_RMI_AFTER=1, and run sudo podman system prune --all. Fedora needs the most room.
Installing Flatpaks fails	The assembler needs to reach dl.flathub.org. Check your connection, proxy or firewall, then run it again.
sudo podman build fails on a package	Run it again later: a mirror may be updating. If it keeps failing, open an issue with the log.