From 960eb81880c2e85d3b04c0757f9de98d621bcc0a Mon Sep 17 00:00:00 2001 From: Roland Date: Thu, 28 May 2026 21:33:22 -0600 Subject: [PATCH] Documenting WROLPi Portable USB, splitting install docs into INSTALL.md. - New INSTALL.md consolidates all install paths: WROLPi Portable (Live USB) as the headline option, plus Debian 12, Raspberry Pi, and Docker. - README install sections collapsed into a single Install section that links to INSTALL.md. - UPGRADE.md gains an "Upgrading a WROLPi Portable USB" section covering scripts/wrolpi-usb.sh upgrade, and documents that in-place conversion of an existing data drive is not supported (backup -> flash -> restore). - wrolpi-usb.sh install now prints that supported procedure instead of a "not implemented" stub; debian-live-config/README.md documents the same. Co-Authored-By: Claude Opus 4.8 (1M context) --- INSTALL.md | 81 ++++++++++++++++++++++++++++++++++++ README.md | 35 ++++------------ UPGRADE.md | 34 +++++++++++++++ debian-live-config/README.md | 32 ++++++++++++++ scripts/wrolpi-usb.sh | 51 +++++++++++++++++------ 5 files changed, 192 insertions(+), 41 deletions(-) create mode 100644 INSTALL.md diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..16376386 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,81 @@ +# Installing WROLPi + +There are several ways to run WROLPi. Pick the one that matches your hardware: + +* [WROLPi Portable (Live USB)](#wrolpi-portable-live-usb) — boot a full WROLPi from a USB stick on any x86 PC or laptop, no installation required. +* [Debian 12 Install](#debian-12-install) — install WROLPi onto an x86 PC or laptop. +* [Raspberry Pi Install](#raspberry-pi-install) — install WROLPi onto a Raspberry Pi with an external drive. +* [Docker](docker/README.md) — run the WROLPi containers on an existing Linux host (best for trying it out or development). + +See [UPGRADE.md](UPGRADE.md) for upgrading an existing WROLPi. + +## WROLPi Portable (Live USB) + +WROLPi Portable is a bootable amd64 image that runs a complete WROLPi system +directly off a USB drive on any x86 PC or laptop — nothing is installed to the +computer's internal disk. On the first boot it creates a `persistence` +partition on the USB drive so your library, database, and configuration survive +reboots. + +You will need: + +* A USB drive of at least 16 GB (32 GB+ recommended so there is room for your library). +* An x86 PC or laptop that can boot from USB. + +Steps: + +1. Download the latest `WROLPi-v*-amd64.iso` from [wrolpi.org](https://wrolpi.org). +2. Flash the whole drive with the ISO using Etcher, Rufus, Raspberry Pi Imager, or `dd`: + ``` + sudo dd if=WROLPi-v-amd64.iso of=/dev/sdX bs=4M status=progress conv=fsync + ``` + (Replace `/dev/sdX` with your USB drive. This erases the whole drive.) +3. Boot the PC from the USB drive. At the boot menu, choose **Run WROLPi (live)**. +4. The first boot sets WROLPi up automatically: it creates the persistence + partition, initializes the database, and starts the services. This takes a + minute or two; progress is shown on screen. +5. Once the desktop loads, browse to https://wrolpi.local or the IP address of + your WROLPi. Wi-Fi hotspot and all other features work as usual. + +Notes: + +* **Installing to internal disk.** The same boot menu offers **Install** / + **Graphical Install** entries that run the standard Debian Installer if you + would rather install WROLPi onto the computer's internal disk instead of + running from the USB. +* **Ventoy / multiboot USBs.** Booting the ISO via Ventoy, YUMI, Easy2Boot, or + any other tool that loop-mounts the ISO works, but runs **ephemerally** — the + library lives in RAM and is lost on reboot, because WROLPi cannot safely write + a persistence partition onto your multiboot stick. A first-boot dialog warns + you when this happens. For persistent use, flash the ISO directly to its own + drive as shown above. +* **Upgrading.** See [Upgrading a WROLPi Portable USB](UPGRADE.md#upgrading-a-wrolpi-portable-usb) + to move to a newer ISO without losing your library. + +## Debian 12 Install + +Steps necessary to initialize your WROLPi after installing the Debian image from wrolpi.org + +1. Download and copy a pre-built Debian image from https://wrolpi.org onto a USB thumb-drive (USB 2 recommended). +2. Insert the thumb-drive into the laptop, boot to the thumb-drive. + 1. Select "Start Installer". + 2. Install Debian 12 as you would like. + 1. It is recommended to use the hostname **wrolpi**. + 2. (WROLPi will be installed during the installation without your intervention.) +3. Unplug the thumb-drive after the installation has completed. +4. Login as the user _you_ created during installation. +5. Initialize the WROLPi databases using the repair script: `/opt/wrolpi/repair.sh` +6. Reboot: `reboot` +7. Browse to https://wrolpi.local or the IP address of your WROLPi! + +## Raspberry Pi Install + +Steps necessary to initialize your WROLPi after installing the Raspberry Pi image from wrolpi.org + +1. Download and copy a pre-built image from https://wrolpi.org onto an SD card. +2. Boot the Raspberry Pi, login with username pi and password wrolpi. +3. Modify fstab to mount your external drive to /media/wrolpi (modify this command to match your system). + * `echo '/dev/sda1 /media/wrolpi auto defaults,nofail 0 0' | sudo tee -a /etc/fstab` +4. Initialize the WROLPi databases using the repair script: `sudo /opt/wrolpi/repair.sh` +5. Reboot `sudo reboot` +6. Join the Hotspot or browse to https://wrolpi.local or the IP address of your WROLPi! diff --git a/README.md b/README.md index 9b16faa0..3a191676 100644 --- a/README.md +++ b/README.md @@ -22,9 +22,8 @@ network so that any user with a laptop/tablet/phone can connect and use the libr * [Demo](#demo) * [Download](#download) * [Try WROLPi](#try-wrolpi) +* [Install WROLPi](INSTALL.md) * [Docker Documentation](docker/README.md) -* [Debian 12 Install](#debian-12-install) -* [Raspberry Pi Install](#raspberrypi-install) * [Charter](#charter) * [Upgrading WROLPi](UPGRADE.md) * [Join](#join) @@ -91,34 +90,14 @@ You can try out WROLPi by running the docker containers. More Docker documentation is available in [docker/README.md](docker/README.md) -# Debian 12 Install +# Install WROLPi -Steps necessary to initialize your WROLPi after installing the Debian image from wrolpi.org +Full installation instructions are in [INSTALL.md](INSTALL.md). Pick the option that matches your hardware: -1. Download and copy a pre-built Debian image from https://wrolpi.org onto a USB thumb-drive (USB 2 recommended) -2. Insert the thumb-drive into the laptop, boot to the thumb-drive - 1. Select "Start Installer" - 2. Install Debian 12 as you would like. - 1. It is recommended to use the hostname **wrolpi** - 2. (WROLPi will be installed during the installation without your intervention.) -3. Unplug the thumb-drive after the installation has completed -4. Login as the user _you_ created during installation. -5. Switch to the root user: `su -` -6. Initialize the WROLPi databases using the repair script: `/opt/wrolpi/repair.sh` -7. Reboot: `reboot` -8. Browse to https://wrolpi.local or the IP address of your WROLPi! - -# Raspberry Pi Install - -Steps necessary to initialize your WROLPi after installing the Raspberry Pi image from wrolpi.org - -1. Download and copy a pre-built image from https://wrolpi.org onto an SD card. -2. Boot the Raspberry Pi, login with username pi and password wrolpi. -3. Modify fstab to mount your external drive to /media/wrolpi (modify this command to match your system). - * `echo '/dev/sda1 /media/wrolpi auto defaults,nofail 0 0' | sudo tee -a /etc/fstab` -4. Initialize the WROLPi databases using the repair script: `sudo /opt/wrolpi/repair.sh` -5. Reboot `sudo reboot` -6. Join the Hotspot or browse to https://wrolpi.local or the IP address of your WROLPi! +* **[WROLPi Portable (Live USB)](INSTALL.md#wrolpi-portable-live-usb)** — boot a complete WROLPi from a USB stick on any x86 PC or laptop. Nothing is installed to the computer; the first boot creates a persistence partition on the USB so your library, database, and configuration survive reboots. +* **[Debian 12](INSTALL.md#debian-12-install)** — install WROLPi onto an x86 PC or laptop. +* **[Raspberry Pi](INSTALL.md#raspberry-pi-install)** — install WROLPi onto a Raspberry Pi with an external drive. +* **[Docker](docker/README.md)** — run the WROLPi containers on an existing Linux host. # Charter diff --git a/UPGRADE.md b/UPGRADE.md index a542e94f..0b3449af 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -4,6 +4,7 @@ * [Upgrading Docker containers](#upgrading-docker-containers) * [Upgrading Raspberry Pi or Debian 12 Installation](#upgrading-raspberry-pi-or-debian-12-installation) +* [Upgrading a WROLPi Portable USB](#upgrading-a-wrolpi-portable-usb) ## Upgrading Docker containers @@ -28,3 +29,36 @@ 1. Run the upgrade script * `sudo /bin/bash /opt/wrolpi/upgrade.sh` * (If the upgrade script does not exist, run the installation script: `sudo /bin/bash /opt/wrolpi/install.sh`) + +## Upgrading a WROLPi Portable USB + +A [WROLPi Portable](INSTALL.md#wrolpi-portable-live-usb) USB carries two +partitions: the ISO (boot) partition and a `persistence` partition — created on +the first boot — that holds your library, database, and configuration. To move +to a newer ISO without losing the persistence partition, use the +`scripts/wrolpi-usb.sh` tool from any Linux host (your own computer, or the +WROLPi USB itself booted on another machine). + +1. Download the new `WROLPi-v*-amd64.iso` from [wrolpi.org](https://wrolpi.org). +2. Plug the WROLPi USB into a Linux host and identify its device node (e.g. `/dev/sdb`) with `lsblk`. +3. Run the upgrade: + * `sudo ./scripts/wrolpi-usb.sh upgrade WROLPi-v-amd64.iso /dev/sdX` +4. Eject the USB and boot it to verify. + +The tool backs up the current partition table to `/tmp/` first, 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 is not supported + +There is no in-place conversion of a drive that already holds your data into a +WROLPi Portable USB — flashing the ISO erases the whole drive. To turn a drive +you already use into a WROLPi USB without losing your files: + +1. Back up everything on the drive to another disk. +2. Flash the whole drive with the ISO (`dd`/Etcher/Rufus — 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. diff --git a/debian-live-config/README.md b/debian-live-config/README.md index bbe01346..ed058c77 100644 --- a/debian-live-config/README.md +++ b/debian-live-config/README.md @@ -26,6 +26,38 @@ 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 ``` +## 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 (`dd`/Etcher/Rufus — 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. + ## Layout on disk The drive carries everything WROLPi needs. Postgres data lives alongside diff --git a/scripts/wrolpi-usb.sh b/scripts/wrolpi-usb.sh index 810e4f07..68229396 100755 --- a/scripts/wrolpi-usb.sh +++ b/scripts/wrolpi-usb.sh @@ -8,16 +8,15 @@ # ISO. The persistence partition (your library + database + # configuration) is preserved. # -# sudo ./wrolpi-usb.sh install -# [not yet implemented] -# Convert an existing ext4 drive into a WROLPi USB by shrinking the -# existing partition from the end, adding WROLPi boot partitions in -# the freed space, and relabelling the existing partition as the -# persistence partition. +# sudo ./wrolpi-usb.sh install +# Converting an existing data drive into a WROLPi USB in place is +# NOT supported. Running this prints the supported procedure: +# back up your data, flash the whole drive with the ISO, boot once +# to create the persistence partition, then restore your data. # -# Both commands save the current partition table to +# The upgrade command saves the current partition table to # /tmp/wrolpi-usb--.sfdisk before any destructive -# operation, and refuse to run on non-removable disks. +# operation, and refuses to run on non-removable disks. set -euo pipefail @@ -210,7 +209,34 @@ This operation cannot be undone." } cmd_install() { - die "install is not yet implemented (planned: see scripts/wrolpi-usb.sh comments)" + # In-place conversion of an existing data drive is intentionally not + # supported. A WROLPi USB is a dd-flashed iso-hybrid image with its + # persistence partition appended on first boot; there is no safe, + # filesystem-agnostic way to graft that onto a drive that is already + # full of the user's data without risking it. Point the user at the + # supported backup -> flash -> restore path instead. + cat >&2 <<'EOF' +Converting an existing drive into a WROLPi USB in place is not supported. + +A WROLPi USB is created by flashing the whole drive with the ISO, which +erases everything already on it. To turn a drive you already use into a +WROLPi USB without losing your files: + + 1. Back up everything on the drive to another disk. + 2. Flash the whole drive with the ISO (this erases it): + sudo dd if= of= bs=4M status=progress conv=fsync + (or use Etcher / Rufus / Raspberry Pi Imager) + 3. Boot the drive once. WROLPi creates its persistence partition and + sets itself up on first boot. + 4. Copy your backed-up data into /media/wrolpi/ on the running system, + then let WROLPi refresh/repair so it indexes the restored files. + +Once a drive has been set up this way, future ISO upgrades preserve your +library and are done with: + + sudo ./wrolpi-usb.sh upgrade +EOF + exit 2 } # --------------------------------------------------------------------------- @@ -224,10 +250,9 @@ main() { cmd_upgrade "$@" ;; install) - shift - [ $# -eq 2 ] || { usage; exit 1; } - require_root - cmd_install "$@" + # No args required: install only prints the supported procedure + # and exits. Don't require root or an iso/device. + cmd_install ;; -h|--help|help|"") usage