Getting Started

WROLPi Portable (Live USB)Easiest

WROLPi Portable 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 survives reboots.

You will need: a USB drive of at least 16GB (32GB+ recommended), and an x86 PC or laptop that can boot from USB.

1. Download the PC / Laptop ISO.
2. Flash the whole USB 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 — this takes a minute or two, and progress is shown on screen.
5. Once the desktop loads, follow First Boot below.

Raspberry Pi

You will need: a Raspberry Pi 4 or 5 (4GB+ RAM) with a quality cooler, a micro SD card (64GB minimum, 128GB+ recommended), and an external drive for your library.

1. Download the Raspberry Pi image.
2. Copy the image to your micro SD card using Raspberry Pi Imager. On Linux you can also use dd:

   xzcat WROLPi-v<version>-aarch64-desktop.img.xz | sudo dd of=/dev/sdX status=progress

   (Replace /dev/sdX with your SD card — find it with sudo blkid.)
3. Insert the micro SD card, connect your external drive and peripherals, and boot the Raspberry Pi.
4. Complete the Raspberry Pi OS first-boot wizard:
   1. Choose your Country/Language/Timezone.
   2. Choose your own username and password (do not use the wrolpi user).
   3. Skip "Wi-Fi Selection", it is not required.
   4. Choose your favorite browser.
   5. Skip "Raspberry Pi Connect" and "Update Software".
   6. Restart, then login with the user you created.
5. A browser opens automatically — follow First Boot below.

Debian

You will need: any x86_64 computer — an old laptop is a great choice because it has a built-in battery, keyboard, and screen. WROLPi is installed automatically as part of the Debian 12 installation.

1. Download the PC / Laptop ISO and copy it to a USB thumb-drive (same flashing tools as above).
2. Boot the computer from the thumb-drive and select Start Installer (or Graphical Install).
   1. Install Debian 12 as you like — the hostname wrolpi is recommended.
   2. WROLPi is installed during the installation without your intervention.
3. Unplug the thumb-drive after the installation completes, and reboot.
4. Login as the user you created during installation.
5. A browser opens automatically — follow First Boot below.

Docker

Best for trying WROLPi out, or for development, on an existing Linux machine. Not recommended as a permanent off-grid installation.

1. Install docker-ce and docker-compose.

2. git clone https://github.com/lrnselfreliance/wrolpi.git
   cd wrolpi
   git submodule update --init

3. Follow the Docker instructions on GitHub to build and start the containers.

First Boot

Every new WROLPi finishes setup the same way, using a wizard in your browser. Open https://wrolpi.local (or the IP address of your WROLPi) from the WROLPi itself or any device on the same network.

1. Accept the self-signed certificate warning in your browser — this is expected on a fresh install.
2. The Welcome to WROLPi screen lists your drives. Select the drive you want to use for your library — WROLPi mounts it and finishes the installation automatically. (This takes about 15 minutes on a Raspberry Pi 4; WROLPi Portable configures its own drive, so this step is skipped.)
3. When setup completes, you are redirected to the WROLPi app.

After setup

1. Install the WROLPi certificate on your devices (Settings → Download Root CA Certificate) so browsers stop warning about HTTPS.
2. Click Files → Refresh to index your library — a new WROLPi looks empty until the first refresh completes.
3. Download your first video, or archive your first web page!