wrolpi/debian-live-config
Roland 1bc337bfb4
Addressing Greptile P2s on the Ventoy ephemeral fallback.
- Treat virtual disks (vd*/xvd*/hd*) as direct, not ephemeral.  A blank
  VM disk imaged with the ISO can safely hold a persistence partition;
  previously these fell through the wildcard to loop mode and never
  accumulated state.
- Move the ephemeral note_action inside the mountpoint guard so a manual
  wrolpi-bootstrap.service restart mid-session doesn't re-fire the "NOT
  writing to disk" first-boot dialog.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-28 21:13:12 -06:00
..
config Addressing Greptile P2s on the Ventoy ephemeral fallback. 2026-05-28 21:13:12 -06:00
files Key changes: 2026-04-04 13:48:19 -06:00
build.sh Reverting to Debian Installer (--debian-installer live) over Calamares. 2026-05-25 20:16:02 -06:00
README.md Falling back to tmpfs when booted via Ventoy or other loop-mounted ISOs. 2026-05-28 21:12:52 -06:00

Debian Live Config

Build a bootable amd64 ISO that boots into a full WROLPi system on any x86 PC. Users can run WROLPi directly off the USB (a persistence partition is created on the first boot so the database and media directory survive reboots) or install to disk via the Calamares launcher on the desktop.

The chroot-phase build is identical for both modes; the resulting squashfs is what runs in live mode AND what Calamares copies onto the target disk.

See https://live-team.pages.debian.net/live-manual/html/live-manual/index.en.html

Build

sudo ./build.sh                # build from 'release' branch
sudo ./build.sh -b master      # build from a specific branch

Requires Debian / Ubuntu with live-build installed. The resulting ISO is written to this directory as WROLPi-v${VERSION}-amd64.iso.

Flash with Etcher, Rufus, Raspberry Pi Imager, or:

sudo dd if=WROLPi-v${VERSION}-amd64.iso of=/dev/sdX bs=4M status=progress conv=fsync

Layout on disk

The drive carries everything WROLPi needs. Postgres data lives alongside the user's library so a drive moved between hosts keeps its full state:

/media/wrolpi/
  videos/                                ← user-facing media
  archives/
  zims/
  map/
  tags/
  config/
    wrolpi.yaml
    controller.yaml
    fstab.yaml
    ssl/
    postgresql/
      data/                              ← bind-mounted to /var/lib/postgresql
      config/                            ← bind-mounted to /etc/postgresql

Booting via Ventoy or other multiboot USBs

Booting WROLPi via Ventoy, YUMI, Easy2Boot, AIO Boot, GLIM, or any other tool that loop-mounts the ISO works, but only in ephemeral mode.

When the live medium appears under /dev/loop*, /dev/dm-*, or /dev/mapper/* (the kernel's tell-tale for a loop/device-mapper-backed file rather than a real partition), wrolpi-bootstrap.sh refuses to create a persistence partition. The underlying disk in that case is the user's Ventoy stick, not a blank target — appending a new ext4 partition to it would risk corrupting the user's other ISOs and data.

Instead the script mounts a tmpfs at /media/wrolpi (sized to half of RAM by default), and the rest of the boot is unchanged. Postgres bind-mounts and DB initialisation all succeed, just into RAM. The user sees a "Running ephemerally…" notice in the first-boot dialog.

Everything written to the WROLPi library — downloads, archives, video metadata, the database — is lost on reboot. This mode is intended for trying WROLPi out without committing a USB stick; for any real use, flash the ISO directly to its own drive with dd or Etcher.

Direct (dd/Etcher) boot is distinguished by the live medium living under /dev/sd*, /dev/nvme*, or /dev/mmcblk*; this is the only shape where wrolpi-bootstrap.sh will touch the partition table.

(Future work: integrate with Ventoy's native persistence.dat flow so the user can opt into a persistent ephemeral-style image without needing a dedicated drive.)

Implementation status

  • Phase 1 — merged live + chroot config: Single debian-live-config/ produces a Debian Live ISO with the full WROLPi stack, XFCE auto-login as wrolpi, persistence partition created on first boot.
  • Phase 2 — Debian Installer: Standard debian-installer bundled via lb config --debian-installer live --debian-installer-gui true. GRUB exposes "Live", "Install", and "Graphical Install" entries. Live boots into WROLPi; Install/Graphical Install copy the running squashfs onto the target disk via Debian's live-installer flow. (We previously tried Calamares-as-the-installer; the XFCE desktop-icon click path proved unreliable in the wrolpi auto-login session and the upstream d-i path is better-tested.)
  • Phase 3 — Ventoy/multiboot safety: wrolpi-bootstrap.sh detects when it's been booted via a loop-mounted ISO (Ventoy and friends) and falls back to a tmpfs-backed /media/wrolpi instead of writing a new partition onto the user's multiboot stick.
  • Release: CI on tag, hosting, wrolpi.org docs.

References