rt/wrolpi-help
1
0
Fork 0
mirror of https://github.com/wrolpi/wrolpi-help.git synced 2026-10-26 10:51:37 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
wrolpi-help/docs/system/getting-started.md
Roland 217ff68098
Creating Tags, Configs, FileGroups, Downloads, and Upgrade docs. 
Also: adding WROLPi Portable (Live USB) to Getting Started, syncing the
Home TOC with all existing pages, pointing eBooks/PDFs at the Docs
module, recommending Raspberry Pi Imager instead of Etcher, and fixing
typos.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-03 18:34:34 -06:00

4.9 KiB
Raw Permalink Blame History

Getting Started

First Boot

When a WROLPi boots for the first time, it generates a temporary HTTPS certificate and starts the Controller fallback UI. Your browser will be redirected to the Controller where you can complete the onboarding process.

Onboarding

  1. Open a browser to your WROLPi's address (e.g. https://wrolpi.local or https://127.0.0.1 on the WROLPi itself).
  2. Accept the self-signed certificate warning in your browser. This is expected on a fresh install.
  3. The Controller will display the Welcome to WROLPi screen with your available drives.

onboarding-drive-selection.png

  1. Select the drive you want to use as your WROLPi media drive.
  2. If the drive contains an existing WROLPi configuration, you will be asked to confirm. Click Set Up This Drive to proceed, or Choose Different Drive to go back.

onboarding-confirm-drive.png

  1. WROLPi will mount the drive and start the repair script automatically. You will see a Repair WROLPi Running banner at the top of the page.

onboarding-repair-running.png

This will take about 15 minutes on a Raspberry Pi 4.

  1. Once repair completes, all services will start and you will be redirected to the main UI.

After onboarding, you should install the HTTPS certificate on your devices to avoid the browser warning on future visits.

Creating a new WROLPi

The following sections are the steps necessary to create a new WROLPi, either as a backup, or to restore your WROLPi on new hardware.

WROLPi Portable (Live USB)

WROLPi Portable is a bootable image that runs a complete WROLPi 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.
  2. Flash the whole drive with the ISO using Raspberry Pi Imager, Rufus, 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.

Warning! Booting the ISO from a multiboot tool (Ventoy, YUMI, Easy2Boot, etc.) runs ephemerally — your library lives in RAM and is lost on reboot, because WROLPi cannot safely write a persistence partition onto a multiboot stick. A dialog warns you on the first boot when this happens. For persistent use, flash the ISO directly to its own drive as shown above.

The same boot menu also offers Install / Graphical Install entries that run the standard Debian Installer if you would rather install WROLPi onto the computer's internal disk. See the Debian section below.

Raspberry Pi

Image an SD Card on Linux

  1. Plug in your SD card, find its device path with: sudo blkid
  2. Extract and copy the WROLPi image to your drive (/dev/sdb in this example):
    • xzcat WROLPi-v<version>-aarch64-desktop.img.xz | sudo dd of=/dev/sdb status=progress

Image an SD Card on Windows

  1. Copy the WROLPi image to your micro SD card using Raspberry Pi Imager

First Boot

  1. Unplug your Raspberry Pi
  2. Insert the micro SD card into your Raspberry Pi
  3. Connect any peripherals to your Raspberry Pi.
  4. Boot your Raspberry Pi.
  5. Choose your Country/Language/Timezone.
  6. Choose your own username and password (do not use the wrolpi user).
  7. Skip "Wi-Fi Selection", it is not required.
  8. Choose your favorite browser.
  9. Skip "Raspberry Pi Connect".
  10. Skip "Update Software".
  11. Restart.
  12. Login using the user you created above.
  13. A browser will open automatically. Follow the Onboarding steps above to select your drive and complete the installation.

Debian

  1. Copy the Debian WROLPi ISO to a thumb-drive.
  2. Insert the thumb-drive into the laptop, boot to the thumb-drive.
    1. Select Start Installer
    2. Install Debian 12.
  3. Unplug the thumb-drive after the installation has completed
  4. Login as the user you created during installation.
  5. Reboot: sudo reboot
  6. A browser will open automatically. Follow the Onboarding steps above to select your drive and complete the installation.