mirror of
https://github.com/lrnselfreliance/wrolpi.git
synced 2026-10-25 18:40:06 -04:00
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) <noreply@anthropic.com>
This commit is contained in:
Roland
parent
1bc337bfb4
commit
960eb81880
5 changed files with 192 additions and 41 deletions
81
INSTALL.md
Normal file
81
INSTALL.md
Normal file
|
|
@ -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<version>-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!
|
||||
35
README.md
35
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
|
||||
|
||||
|
|
|
|||
34
UPGRADE.md
34
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<version>-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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -8,16 +8,15 @@
|
|||
# ISO. The persistence partition (your library + database +
|
||||
# configuration) is preserved.
|
||||
#
|
||||
# sudo ./wrolpi-usb.sh install <iso> <device>
|
||||
# [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-<device>-<timestamp>.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=<iso> of=<device> 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 <iso> <device>
|
||||
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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue