Falling back to tmpfs when booted via Ventoy or other loop-mounted ISOs.

wrolpi-bootstrap.sh now classifies the live medium by device-node
pattern.  Real partitions (/dev/sd*, /dev/nvme*, /dev/mmcblk*) continue
to get a persistence partition appended.  Loop/device-mapper sources
(/dev/loop*, /dev/dm-*, /dev/mapper/*) — the marker for Ventoy/YUMI/
Easy2Boot/etc — mount a tmpfs at /media/wrolpi instead, so we never
sfdisk-append a partition onto the user's multiboot stick.

First-boot zenity dialog branches on mode and tells ephemeral users
their data won't persist; README documents the behaviour and the
deferred persistence.dat work.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Roland 2026-05-25 20:26:21 -06:00 • committed by lrnselfreliance
parent 342374b97f
commit 82dd7782d3
2 changed files with 131 additions and 28 deletions

View file

@ -48,6 +48,36 @@ the user's library so a drive moved between hosts keeps its full state:
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
- [x] **Phase 1 — merged live + chroot config**: Single `debian-live-config/`
@ -61,6 +91,10 @@ the user's library so a drive moved between hosts keeps its full state:
(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.)
- [x] **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

View file

@ -1,26 +1,33 @@
#!/usr/bin/env bash
# WROLPi bootstrap — runs at every boot via wrolpi-bootstrap.service.
# Idempotent throughout. Works in all three deployment shapes:
# Idempotent throughout. Works in all four deployment shapes:
#
# 1. Live USB, first boot. No persistence partition exists. This script
# creates one in the free space at the end of the boot drive, formats it
# as ext4 (label `persistence`), writes a persistence.conf so future
# boots pick it up automatically via live-boot, bind-mounts the
# persistence root over /media/wrolpi, creates the Postgres cluster
# under /media/wrolpi/config/postgresql/, runs initialize_api_db.sh,
# and enables the WROLPi runtime services.
# 1. Live USB (direct), first boot. No persistence partition exists.
# This script creates one in the free space at the end of the boot
# drive, formats it as ext4 (label `persistence`), writes a
# persistence.conf so future boots pick it up automatically via
# live-boot, bind-mounts the persistence root over /media/wrolpi,
# creates the Postgres cluster under /media/wrolpi/config/postgresql/,
# runs initialize_api_db.sh, and enables the WROLPi runtime services.
#
# 2. Live USB, subsequent boot. live-boot's initramfs has already applied
# the /media/wrolpi bind mount from persistence.conf. Cluster and DB
# already exist. Most steps no-op; we always regenerate the leaf TLS
# cert and ensure services are enabled.
# 2. Live USB (direct), subsequent boot. live-boot's initramfs has
# already applied the /media/wrolpi bind mount from persistence.conf.
# Cluster and DB already exist. Most steps no-op; we always
# regenerate the leaf TLS cert and ensure services are enabled.
#
# 3. Installed (Calamares). No live medium present; partition-creation
# branch is skipped. /media/wrolpi is mounted via /etc/fstab on an
# external drive, or is a plain directory on the root filesystem if
# the user installed without one. The Postgres bind-mounts happen at
# every boot here because /etc/fstab doesn't own them — see Before=
# in the .service unit.
# 3. Live USB (loop / Ventoy / multiboot). The ISO is loop-mounted by a
# multiboot tool, so we cannot safely write a new partition to the
# underlying disk (it's the user's Ventoy stick, not a blank target).
# /media/wrolpi is backed by tmpfs and everything runs from RAM. All
# user data is lost on reboot. Surfaced to the user via the
# first-boot zenity dialog.
#
# 4. Installed. No live medium present; partition-creation branch is
# skipped. /media/wrolpi is mounted via /etc/fstab on an external
# drive, or is a plain directory on the root filesystem if the user
# installed without one. The Postgres bind-mounts happen at every
# boot here because /etc/fstab doesn't own them — see Before= in the
# .service unit.
set -euo pipefail
@ -49,27 +56,56 @@ note_action() { SUMMARY="${SUMMARY}- $1
progress "Preparing WROLPi..."
# --- Detect Live vs Installed -------------------------------------------
# Live: one of the live-boot mount points is active and points at our USB.
# Installed: none of them exist; this script proceeds straight to the
# Postgres bind-mount section.
# --- Detect deployment mode ---------------------------------------------
# Three mutually-exclusive shapes:
#
# direct Live USB flashed with dd/Etcher: the ISO partition is a
# real partition on a real disk. Create + manage a
# persistence partition on that disk.
#
# loop Live medium is a loop or device-mapper node — typical
# of Ventoy, YUMI, Easy2Boot, GLIM, AIO Boot, etc. The
# underlying block device is the user's data drive; we
# must NOT try to sfdisk-append a partition onto it.
# Run ephemerally: /media/wrolpi backed by tmpfs, lost
# on reboot.
#
# installed No live medium at all. Skip partition logic entirely;
# /media/wrolpi is either on /etc/fstab or a plain dir
# on the root filesystem.
MODE=installed
BOOT_DRIVE=""
LIVE_MEDIUM=""
for mp in /usr/lib/live/mount/medium /run/live/medium /lib/live/mount/medium; do
if part=$(findmnt -nr -o SOURCE "$mp" 2>/dev/null) && [ -n "$part" ]; then
BOOT_DRIVE="/dev/$(lsblk -no PKNAME "$part")"
log "live medium $part on $BOOT_DRIVE"
LIVE_MEDIUM=$part
case "$part" in
/dev/sd*|/dev/nvme*|/dev/mmcblk*)
MODE=direct
BOOT_DRIVE="/dev/$(lsblk -no PKNAME "$part")"
log "live medium $part on $BOOT_DRIVE (mode: direct)"
;;
/dev/loop*|/dev/dm-*|/dev/mapper/*)
MODE=loop
log "live medium $part is a loop/dm device (mode: loop — ephemeral)"
;;
*)
MODE=loop
log "live medium $part has unrecognised shape (mode: loop — safe default)"
;;
esac
break
fi
done
if [ -z "$BOOT_DRIVE" ]; then
if [ "$MODE" = "installed" ]; then
log "no live medium detected — running in Installed mode"
fi
# --- Find or create persistence partition (Live only) -------------------
# --- Find or create persistence partition (direct mode only) ------------
if [ -n "$BOOT_DRIVE" ]; then
if [ "$MODE" = "direct" ]; then
PERSIST_PART=$(blkid -L persistence 2>/dev/null || true)
if [ -z "$PERSIST_PART" ]; then
progress "Creating persistence partition on $BOOT_DRIVE..."
@ -156,6 +192,25 @@ EOF
fi
fi
# --- Ephemeral (loop mode) ----------------------------------------------
# Booted via Ventoy / multiboot tool / loop-mounted ISO. We cannot tell
# which underlying disk is the user's data drive — appending a partition
# would risk corrupting their Ventoy stick or whatever else they had on
# that device. Run from RAM instead. Anything written to /media/wrolpi
# vanishes on reboot, but the rest of WROLPi (Postgres bind-mounts,
# config layout, services) works identically.
if [ "$MODE" = "loop" ]; then
if ! mountpoint -q /media/wrolpi; then
mkdir -p /media/wrolpi
# No explicit size= — defaults to half-RAM, plenty for an
# exploratory session and capped so we can't OOM the box.
mount -t tmpfs -o mode=0755 tmpfs /media/wrolpi
log "ephemeral mode: /media/wrolpi is tmpfs (data lost on reboot)"
fi
note_action "Running ephemerally from RAM (Ventoy / multiboot USB detected). Your data WILL NOT persist across reboots."
fi
# --- /media/wrolpi/config + Postgres data layout ------------------------
# Works regardless of whether /media/wrolpi is a bind (Live), a regular
# mount from /etc/fstab (Installed + external drive), or a plain
@ -253,7 +308,20 @@ systemctl start --no-block wrolpi-api.service wrolpi-app.service wrolpi-kiwix.se
# If we did anything notable, leave a summary for the XFCE autostart to
# show as a zenity dialog once the user lands on the desktop.
if [ -n "$SUMMARY" ]; then
cat > "$SUMMARY_FILE" <<EOF
if [ "$MODE" = "loop" ]; then
cat > "$SUMMARY_FILE" <<EOF
WROLPi is running, but NOT writing to disk.
$SUMMARY
You appear to have booted from Ventoy or a similar multiboot tool.
WROLPi can't safely write a persistence partition in that case, so
everything lives in RAM and will be lost when you reboot or power off.
To get a persistent install, flash the ISO directly to a USB drive
with dd or Etcher and boot from that drive instead.
EOF
else
cat > "$SUMMARY_FILE" <<EOF
WROLPi finished setting itself up:
$SUMMARY
@ -261,6 +329,7 @@ These persist between reboots:
/media/wrolpi — your library (videos, archives, zims, ...)
/media/wrolpi/config — configuration + Postgres data
EOF
fi
chmod 0644 "$SUMMARY_FILE"
fi