mirror of
https://github.com/lrnselfreliance/wrolpi.git
synced 2026-10-26 19:01:39 -04:00
2f5d88ad4e
live-config's openssh-server component rewrites sshd_config to "PasswordAuthentication no" on every live boot, so the live session only accepted SSH keys. An sshd_config.d drop-in sets it back to yes; sshd uses the first value it reads and sshd_config includes the drop-ins first, so the drop-in wins. The login is user / live (live-config's default), now noted in INSTALL.md. check-iso.sh fails the build if the drop-in is missing. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
149 lines
6.4 KiB
Markdown
149 lines
6.4 KiB
Markdown
# 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`, `libarchive-tools` (bsdtar),
|
|
`genisoimage` (isoinfo) and `squashfs-tools` installed. The resulting ISO is
|
|
written to this directory as
|
|
`WROLPi-v${VERSION}-amd64.iso`, and `check-iso.sh` then checks it for
|
|
problems that would only appear after the Debian installer runs.
|
|
|
|
Flash with Raspberry Pi Imager, Rufus, or:
|
|
|
|
```
|
|
sudo dd if=WROLPi-v${VERSION}-amd64.iso of=/dev/sdX bs=4M status=progress conv=fsync
|
|
```
|
|
|
|
## Upgrading an existing WROLPi USB
|
|
|
|
A WROLPi USB carries two partitions: the ISO (boot) partition and a
|
|
`persistence` partition created on first boot that holds your library,
|
|
database, and configuration. To move to a newer ISO without losing the
|
|
persistence partition, use `scripts/wrolpi-usb.sh` from any Linux host:
|
|
|
|
```
|
|
sudo ./scripts/wrolpi-usb.sh upgrade WROLPi-v${VERSION}-amd64.iso /dev/sdX
|
|
```
|
|
|
|
It backs up the partition table, overwrites only the ISO partition, and
|
|
re-adds the persistence partition entry at its original location. The
|
|
ISO partition reserves 8 GiB of headroom so a larger future ISO still
|
|
fits ahead of the persistence partition.
|
|
|
|
## Converting an existing data drive (not supported)
|
|
|
|
There is no in-place conversion of a drive that already holds your data
|
|
into a WROLPi USB — flashing the ISO erases the whole drive, and there
|
|
is no safe, filesystem-agnostic way to graft WROLPi onto a full drive.
|
|
`scripts/wrolpi-usb.sh install` only prints this procedure:
|
|
|
|
1. Back up everything on the drive to another disk.
|
|
2. Flash the whole drive with the ISO (Raspberry Pi Imager/Rufus/`dd` — this erases it).
|
|
3. Boot once so WROLPi creates its persistence partition and sets itself up.
|
|
4. Copy your data into `/media/wrolpi/`, then let WROLPi refresh/repair to
|
|
index the restored files.
|
|
|
|
Afterwards, future ISO upgrades preserve your library via the
|
|
`upgrade` command above.
|
|
|
|
## Users
|
|
|
|
- `wrolpi` is a system account (no password, no login sudo) that owns
|
|
`/media/wrolpi` and runs the WROLPi services, as on every other WROLPi.
|
|
- The live session logs in automatically as `user` (live-config), password
|
|
`live`. SSH accepts that password (`sshd_config.d/50-wrolpi-password.conf`
|
|
overrides live-config, which turns password SSH off).
|
|
- An installed system has the user the Debian installer asked for, with sudo,
|
|
and no automatic login.
|
|
|
|
## Layout on disk
|
|
|
|
The drive carries everything WROLPi needs. The SQLite database 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/
|
|
wrolpi.db ← SQLite database (created by the
|
|
API on first start; -wal/-shm
|
|
sidecars appear while running)
|
|
```
|
|
|
|
## 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. The config
|
|
layout and SQLite database are created as usual, 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 Raspberry Pi Imager or `dd`.
|
|
|
|
Direct (Raspberry Pi Imager/dd) 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/`
|
|
produces a Debian Live ISO with the full WROLPi stack, XFCE auto-login
|
|
as `user`, persistence partition created on first boot.
|
|
- [x] **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.)
|
|
- [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
|
|
|
|
- Debian Live Manual: https://live-team.pages.debian.net/live-manual/html/live-manual/index.en.html
|
|
- Persistence: https://live-team.pages.debian.net/live-manual/html/live-manual/customizing-run-time-behaviours.en.html
|