From 217ff68098662426e56c500d7bbd06d544de8fb9 Mon Sep 17 00:00:00 2001 From: Roland Date: Fri, 3 Jul 2026 18:34:34 -0600 Subject: [PATCH] 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 --- docs/index.md | 22 ++++++ docs/modules/downloads/index.md | 109 +++++++++++++++++++++++++++++ docs/modules/files/index.md | 4 +- docs/other/ebooks.md | 16 +++-- docs/other/pdfs.md | 8 +-- docs/system/backup.md | 4 +- docs/system/configs.md | 90 ++++++++++++++++++++++++ docs/system/filegroups.md | 91 ++++++++++++++++++++++++ docs/system/getting-started.md | 51 ++++++++++---- docs/system/special-directories.md | 4 +- docs/system/tags.md | 109 +++++++++++++++++++++++++++++ docs/system/upgrade.md | 83 ++++++++++++++++++++++ 12 files changed, 564 insertions(+), 27 deletions(-) create mode 100644 docs/modules/downloads/index.md create mode 100644 docs/system/configs.md create mode 100644 docs/system/filegroups.md create mode 100644 docs/system/tags.md create mode 100644 docs/system/upgrade.md diff --git a/docs/index.md b/docs/index.md index 9c0918b..06b9857 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,11 +8,20 @@ Information about a WROLPi system. * [Getting Started](system/getting-started.md) * [Getting Help](system/getting-help.md) +* [Upgrading WROLPi](system/upgrade.md) * [Controller](controller/index.md) +* [How WROLPi Stores Files](system/filegroups.md) +* [How Configs Work](system/configs.md) +* [Tags](system/tags.md) * [Collections](system/collections/index.md) * [Reorganize Collections](system/collections/reorganization.md) +* [Backup](system/backup.md) * [Logs](system/logs.md) * [Systems](system/index.md) +* [Services (systemd)](system/systemd.md) +* [Databases](system/databases.md) +* [Special Directories](system/special-directories.md) +* [Environment Variables](system/variables.md) * [Recommended Hardware](system/recommended-hardware.md) * [External USB Drives](system/external-drives.md) * [HTTPS Certificates](system/certificates.md) @@ -22,9 +31,13 @@ Information about a WROLPi system. Information about the parts of the WROLPi interface. * [Files](modules/files/index.md) +* [Downloads](modules/downloads/index.md) * [Videos](modules/videos/index.md) + * [Video Files](modules/videos/files.md) * [Encrypted Cookies](modules/videos/cookies.md) * [Archives](modules/archives/index.md) + * [Archive Files](modules/archives/files.md) + * [SingleFile Extension](modules/archives/singlefile-extension.md) * [Docs](modules/docs/index.md) * [Map](modules/map/index.md) * [Zim](modules/zim/index.md) @@ -33,6 +46,15 @@ Information about the parts of the WROLPi interface. * [Ration](modules/inventory/ration.md) * [Export](modules/inventory/export.md) +## Other File Types + +How WROLPi handles other common file types. + +* [eBooks](other/ebooks.md) +* [PDFs](other/pdfs.md) +* [Texts](other/texts.md) +* [Zips](other/zips.md) + ## Guiding Principals Principals that influence the design decisions of WROLPi. diff --git a/docs/modules/downloads/index.md b/docs/modules/downloads/index.md new file mode 100644 index 0000000..603342f --- /dev/null +++ b/docs/modules/downloads/index.md @@ -0,0 +1,109 @@ +# Downloads + +All downloading in WROLPi goes through a single download manager. Whether it is a video, a web page archive, a Zim +file, or map data — everything is queued as a Download, runs in the background, and is visible on the **Downloads** +page. + +## Starting a Download + +The Download menu offers a form for each kind of download: + +* **Videos** — download one or more videos (one URL per line) using yt-dlp. Options include Tags, a destination + directory, audio-only (with audio format), preferred resolutions, and video format. See + [Videos](../videos/index.md). +* **Channel/Playlist** — subscribe to a channel or playlist. Options include the download frequency, title + include/exclude words, download order (newest/oldest), a video count limit, minimum/maximum duration, and a + Channel Tag. See [Videos](../videos/index.md). +* **Archives** — create a [SingleFile archive](../archives/index.md) of each URL, with readability text and a + screenshot. Options include Tags, compression, and skipping URLs you have already archived. +* **RSS Feed** — watch an RSS feed and automatically download new entries with either the Video or Archive + downloader. Options include the frequency and title/URL filters. +* **Files** — download any file from a URL into a directory of your choosing. +* **Scrape** — crawl a web page (up to a chosen depth and page limit) collecting every linked file that matches your + list of file suffixes (for example `.pdf,.mp4`), then download those files to a destination. + + **Warning!** Scraping can be exponential — each level of depth can multiply the number of pages visited. + +[Zim subscriptions](../zim/index.md) and [Map subscriptions](../map/index.md) also create recurring downloads; they +are managed from their own pages but appear in the Downloads page like everything else. + +## Once vs Recurring + +A Download either runs **once**, or **recurs** on a frequency (hourly up to every 180 days, depending on the type). + +* A **Once** download of a Channel/Playlist downloads all of its *current* videos, but will not notice videos added + later. +* A **recurring** download keeps its schedule slot — a weekly download runs at the same time each week. If your + WROLPi was powered off past the scheduled time, the most-overdue download runs as soon as possible and the rest + are spread out to avoid a thundering herd. +* Completed once-downloads are automatically cleaned up after 30 days. + +## The Downloads Page + +The Downloads page has two tables: **Downloads** (once) and **Recurring Downloads**. + +Each download has a status: + +| Status | Meaning | +|---|---| +| New | Waiting to be downloaded. | +| Pending | Downloading right now. | +| Complete | Finished successfully. | +| Deferred | Failed, but will be retried automatically (with an increasing back-off). | +| Failed | Failed and will not be retried. | + +Things you can do from the tables: + +* **Stop** a new/pending download, **Restart** a failed/deferred one, or **Delete** it. +* **Edit** a download (its frequency, filters, destination, etc.). +* Click the red error icon to see the full error message of a failed download. +* Watch live progress (speed and time remaining) of a pending download. +* Bulk **Clear** completed downloads, or **Retry** / **Delete** the selected ones. + +**Deleting a download adds its URL to a skip list** so it will not be re-downloaded by an RSS feed or Channel +subscription. You can still download it again by submitting the URL manually. + +## When Downloads Run + +The download manager checks for work every few seconds, but downloads only run when **all** of these are true: + +1. Downloading is enabled (the toggle at the top of the Downloads page). +2. The WROLPi has internet access. +3. WROL Mode is off. +4. A drive is mounted for every download destination (so downloads cannot fill your SD card) — this can be changed + with the *require media mounted* setting. +5. Your [encrypted cookies](../videos/cookies.md) are unlocked, if you have configured cookies. +6. The current time is inside your configured download window (if you set one). + +To be polite to the websites you download from, WROLPi runs at most one download per domain at a time (a few domains +in parallel), and waits between downloads to the same domain. + +## Download Settings + +The Settings page has a **Download** section: + +* **Download on Startup** — enable downloading automatically when WROLPi boots. +* **Wait Between Downloads** — the politeness delay between downloads to the same domain. +* **Download Timeout** — kill any download running longer than this. +* **Daily Download Limits** — cap the number of downloads per domain, and in total, per day. +* **Download Window** — only download between certain hours (overnight windows are supported). +* **Pause downloads when no drive is mounted** and **while cookies are locked** — the safety gates described above. + +## Where Downloaded Files Go + +Destinations are controlled by templates in the [WROLPi config](../../system/configs.md): + +* Videos: `videos///` — the Channel is created automatically if needed. Videos without a + channel go to `videos/NO CHANNEL/`. +* Archives: `archive//` — the Domain is created automatically. +* Zims: `zims/`, Maps: `map/`. +* Files and Scrape downloads go to the destination directory you choose. + +## Failures + +* Most errors are **deferred** and retried automatically with an increasing delay. Each downloader gives up for good + after enough attempts (videos try the hardest). +* If a website blocks WROLPi as a bot (common with YouTube when cookies are missing or stale), all pending downloads + from that domain are failed at once — see [Encrypted Cookies](../videos/cookies.md) for the fix. +* All of your downloads are stored in the `download_manager.yaml` [config](../../system/configs.md), so your + subscriptions survive a database rebuild. diff --git a/docs/modules/files/index.md b/docs/modules/files/index.md index 89ccf73..9aa5053 100644 --- a/docs/modules/files/index.md +++ b/docs/modules/files/index.md @@ -44,6 +44,8 @@ The tool buttons are as displayed: ## Tags +See [Tags](../../system/tags.md) for everything about tagging. + WROLPi creates and manages a `tags` directory, this directory contains links to files you have tagged. This is the [secondary](../../system/primary-secondary-tertiary.md) method to access your tags. **You should never manually add files to this directory, they will be deleted.** @@ -54,7 +56,7 @@ separated by commas (alphabetically). For example, if you tagged a video at then a link to the video will be created in `tags/Computers, WROL/WROLPi_20230909_0xfMLNVFq2Y_WROLPi v0.11 beta demo.mp4` -All files in the **FileGroup** will be linked in the same directory. +All files in the [FileGroup](../../system/filegroups.md) will be linked in the same directory. ## File Preview diff --git a/docs/other/ebooks.md b/docs/other/ebooks.md index 9c09141..5911884 100644 --- a/docs/other/ebooks.md +++ b/docs/other/ebooks.md @@ -1,20 +1,24 @@ # eBooks -eBooks are a secondary file type in WROLPi, which means that they do not yet have a dedicated module, and some features -may not yet be available. +eBooks are managed by the [Docs module](../modules/docs/index.md), where they can be browsed, filtered by author and +subject, searched, and read directly in the browser with the built-in EPUB reader. -Epub files are desired as ebooks, though some support for Mobi files is provided. Reasons why WROLPi supports Epub: +Epub files are desired as ebooks, though some support for Mobi files is provided. Reasons why WROLPi prefers Epub: * Epub files are simple. An Epub file is a zip file containing HTML files. * Third-party support for reading Epubs is much more feature-rich. * Images are files in the Epub zip. -* Device supports for Epubs is nearly ubiquitous. +* Device support for Epubs is nearly ubiquitous. * Because an Epub contains HTML files, it makes it easy to display them in a web browser. +Cover images are detected automatically — including Calibre-style directories with a `cover.jpg` — see +[Cover Images](../modules/docs/index.md#cover-images). + ## Searching -When indexes for an EPUB are generated, they are searched in the following order of precedence: +When indexes for an eBook are generated, they are searched in the following order of precedence: 1. Title 2. Author -3. eBook contents +3. File name +4. eBook contents diff --git a/docs/other/pdfs.md b/docs/other/pdfs.md index 947c987..8b6a2ea 100644 --- a/docs/other/pdfs.md +++ b/docs/other/pdfs.md @@ -1,13 +1,13 @@ # PDF -PDFs are a secondary file type in WROLPi, which means that they do not yet have a dedicated module, and some features -may not yet be available. +PDFs are managed by the [Docs module](../modules/docs/index.md), where they can be browsed, filtered by author and +subject, searched, and read directly in the browser with the embedded PDF viewer. ## Searching -When indexes for an PDFs are generated, they are searched in the following order of precedence: +When indexes for a PDF are generated, they are searched in the following order of precedence: 1. Title 2. Author 3. File path name -4. Text \ No newline at end of file +4. Text diff --git a/docs/system/backup.md b/docs/system/backup.md index 55a37e8..6da6ea1 100644 --- a/docs/system/backup.md +++ b/docs/system/backup.md @@ -11,7 +11,7 @@ Follow these steps to automate backup of your WROLPi. - `sudo -u wrolpi passwd` 2. SSH/login into the backup WROLPi 1. Switch to the "wrolpi" user: - - `sudo su - wropi` + - `sudo su - wrolpi` 2. Generate SSH keys for the wrolpi user: - `ssh-keygen` 3. Copy ssh keys to the primary WROLPi (using the password from step 1) @@ -21,7 +21,7 @@ Follow these steps to automate backup of your WROLPi. 5. Copy all files from the primary to the backup - `rsync -avrle ssh wrolpi@PRIMARY_IP_ADDRESS:/media/wrolpi/* /media/wrolpi` -Files are now synchronized, now you need to automate it. Copy/paste the following into the shell of the backup WROLPI, +Files are now synchronized, now you need to automate it. Copy/paste the following into the shell of the backup WROLPi, it will create a bash script that will copy files from the primary to the backup WROLPi. ```shell diff --git a/docs/system/configs.md b/docs/system/configs.md new file mode 100644 index 0000000..876c531 --- /dev/null +++ b/docs/system/configs.md @@ -0,0 +1,90 @@ +# How Configs Work + +WROLPi stores your settings and everything you have curated (Tags, Channels, Playlists, Downloads, Inventories, etc.) +in plain YAML config files. **The config files are the source of truth** — the database is only an index that can be +rebuilt at any time from your files and configs. + +This design means your WROLPi can be rebuilt, upgraded, or even moved to entirely new hardware without losing what +you have curated: your configs travel with your media drive. + +## Where Configs Live + +All configs are stored in the `config` directory of your media directory: `/media/wrolpi/config/` +(see [Special Directories](special-directories.md)). + +| File | What it stores | +|---|---| +| `wrolpi.yaml` | Global settings: WROL Mode, hotspot, download limits and window, destinations, timezone, etc. | +| `tags.yaml` | Your [Tags](tags.md), and every tagged file and Zim entry. | +| `channels.yaml` | Your video Channels and their download schedules. | +| `domains.yaml` | Your Archive Domains. | +| `playlists.yaml` | Your Playlists, including the order of their items. | +| `download_manager.yaml` | All of your Downloads, and the skip list of deleted URLs. | +| `videos_downloader.yaml` | Video downloader (yt-dlp) settings: resolutions, file name format, etc. | +| `archives_downloader.yaml` | Archive downloader settings. | +| `download_cache.yaml` | Cached video durations (safe to ignore). | +| `map_pins.yaml` | Your [Map](../modules/map/index.md) pins. | +| `inventory/*.yaml` | One file per [Inventory](../modules/inventory/index.md), plus the food catalog. | +| `cookies.txt.enc` | Your [encrypted cookies](../modules/videos/cookies.md). | +| `controller.yaml` | [Controller](../controller/index.md) settings: drives, Samba shares, hotspot. | +| `fstab.yaml` | The WROLPi-managed mount table for your drives. | +| `backup/` | Automatic dated backups of your configs (see below). | +| `ssl/` | Your generated [HTTPS certificates](certificates.md). | + +## The Source-of-Truth Model + +1. **On startup**, WROLPi imports the config files into the database, making the database match the configs. This + works in both directions: Tags are re-created, Channels are re-created, tagged files are re-tagged, and so on — + but anything **removed** from a config is also **deleted** from the database (see + [What imports can delete](#what-imports-can-delete) below). +2. **When you change something in the interface**, the change is written to the database *and* automatically saved + back to the matching config file. Saves are debounced — if many changes happen quickly, only the final state is + written. +3. **Before every save**, the previous file is copied into `config/backup/` with a dated name (for example + `tags-20260703.yaml`), so you can recover from mistakes. + +Because of this, the database can always be rebuilt: a file refresh re-indexes your media files, and a config import +restores everything you curated. + +> The **Settings page has a Configs table** that shows every config file, whether it imported successfully, and lets +> you import or save each one manually. + +## Editing Configs by Hand + +You can edit any config file with a text editor — this is a supported way to make changes (for example, adding many +Channels at once). Keep in mind: + +* WROLPi does **not** watch the files for changes. A hand-edit takes effect on the next startup, or when you click + **Import** for that config in the Settings page's Configs table. +* The file must remain valid YAML. If a config fails to import, WROLPi keeps running, shows an error Event, and + **refuses to overwrite that file** until it imports successfully — this protects your hand-edits from being lost. +* Each config contains a `version` counter. WROLPi refuses to overwrite a config file that is newer than the version + it has in memory. + +### What imports can delete + +Imports are designed to be safe, but you should know the rules: + +* A **missing or empty** config file never deletes anything from the database. +* Removing a Channel or Playlist from a non-empty `channels.yaml` / `playlists.yaml` **will delete it** (and a + Channel's videos) on the next import — this is how you can remove Collections by editing configs. +* Removing a Tag from `tags.yaml` only deletes it if it is no longer used by anything. + +## Backup and Restore + +* Automatic dated backups of every config are kept in `config/backup/`. +* The Configs table in Settings supports **backup import** for the curated configs (Tags, Channels, Domains, + Downloads, Playlists, and Inventories) with two modes: **merge** (add to what you have) or **overwrite** (replace + with the backup). +* Backing up `/media/wrolpi/config/` along with your media files captures everything needed to rebuild your WROLPi. + See [Backup](backup.md). + +## What is *not* in Configs + +A few things live only in the database and are lost if the database is rebuilt: + +* Video watch history / view positions. +* The file index itself (this is simply rebuilt by a file refresh). + +Everything you deliberately curated — Tags, Channels, Playlists, Downloads, Inventories, pins, settings — is in the +configs and survives. diff --git a/docs/system/filegroups.md b/docs/system/filegroups.md new file mode 100644 index 0000000..b65a35a --- /dev/null +++ b/docs/system/filegroups.md @@ -0,0 +1,91 @@ +# How WROLPi Stores Files + +Everything in your WROLPi library is a plain file in the [media directory](special-directories.md) — videos, web +page archives, ebooks, Zims, maps. The database is only an index of those files: it can be deleted and rebuilt at +any time from the files on disk and your [configs](configs.md). There is no hidden storage format; you can browse +your entire library with any file manager, on any computer. + +## FileGroups + +WROLPi groups related files together into a **FileGroup**: files in the *same directory* that share the same name +(stem) are treated as one item in your library. + +For example, these four files are one FileGroup, displayed as a single video: + +``` +videos/WROLPi/WROLPi_20230909_0xfMLNVFq2Y_WROLPi demo.mp4 <- the video (primary file) +videos/WROLPi/WROLPi_20230909_0xfMLNVFq2Y_WROLPi demo.info.json <- metadata +videos/WROLPi/WROLPi_20230909_0xfMLNVFq2Y_WROLPi demo.en.vtt <- captions +videos/WROLPi/WROLPi_20230909_0xfMLNVFq2Y_WROLPi demo.jpg <- poster +``` + +WROLPi understands multi-part suffixes like `.info.json`, `.readability.html`, `.readability.txt`, and +per-language caption suffixes like `.en.vtt` — they all group with their base file. + +Typical FileGroups: + +| Kind | Files | +|---|---| +| [Video](../modules/videos/files.md) | `.mp4` + `.info.json` + captions (`.vtt`/`.srt`) + poster image | +| [Archive](../modules/archives/files.md) | SingleFile `.html` + `.readability.html`/`.txt`/`.json` + screenshot | +| eBook | `.epub` or `.mobi` + a cover image | +| Document | a single `.pdf`, `.docx`, comic book, etc. | + +### The primary file + +Each FileGroup has a **primary file** which decides how the group appears and behaves in the interface. When a group +contains several file types, WROLPi picks the most important one: an archive page, video, or audio file beats an +ebook, an ebook beats a PDF, and images are only primary when nothing else is present. A Video, Archive, or eBook +record is then attached to the FileGroup based on the primary file's type. + +Files that share a stem but live in **different directories are not grouped** — a FileGroup never spans directories. + +## The File Refresh + +The refresh is how WROLPi discovers your files. It scans the media directory, groups files into FileGroups, indexes +their contents for search, and creates the Video/Archive/eBook records. + +> To refresh all your files, click the **Files** link in the top navigation bar, then click **Refresh** at the +> bottom of the files table. You can also select specific files or directories and refresh only those. + +Things to know about the refresh: + +* A brand-new WROLPi has an empty library until the first full refresh completes — the Dashboard will remind you. +* Videos and other downloads refresh their own directories automatically when they complete. +* The refresh refuses to run if the media directory looks empty — this protects your database when a drive failed to + mount. +* A full refresh of a large library can take a long time; progress is displayed while it runs. + +## Indexing and Search + +During the refresh, WROLPi extracts searchable text from your files. What is extracted depends on the file type: + +* **Videos**: the title, description, and the full caption/subtitle text. +* **Archives**: the page title and the readability article text. +* **eBooks / PDFs / documents**: the title, author, and the document text. +* **Everything else**: at minimum, the words of the file name. + +Search offers two modes: the default **fast search** matches titles and other important fields, while **deep +search** also matches the full body text (captions, article contents, document text). + +## The Database Can Be Rebuilt + +Because the database is derived, deleting it is not a disaster: + +* FileGroups, Videos, Archives, and eBooks are rebuilt by a file refresh. +* Everything you curated — [Tags](tags.md), Channels, Playlists, Downloads, settings — is restored from your + [configs](configs.md). +* Only minor runtime data is lost, such as video watch history. + +## Rules to Know + +* All files must live inside the media directory (`/media/wrolpi/`). WROLPi cannot see files outside it. +* **Use the [Files module's tools](../modules/files/index.md) to move, rename, or delete files.** The tools keep the + database and your Tags in sync. If you move or rename a tagged file outside of WROLPi, the Tag can be lost because + Tags are keyed by the file's path. +* You can add files yourself (over the network, or by plugging the drive into another computer): put them anywhere + in the media directory, keep sidecar files (posters, captions, metadata) next to their base file with the same + stem, then run a refresh. +* Directories can be **ignored** from the Files module if you do not want their contents indexed or searchable. +* Never store your own files in the `tags` or `config` directories — see + [Special Directories](special-directories.md). diff --git a/docs/system/getting-started.md b/docs/system/getting-started.md index ed67ea2..6956a8e 100644 --- a/docs/system/getting-started.md +++ b/docs/system/getting-started.md @@ -32,24 +32,54 @@ fallback UI. Your browser will be redirected to the Controller where you can com After onboarding, you should install the [HTTPS certificate](certificates.md) on your devices to avoid the browser warning on future visits. -# Creating a new WROLPi +## Creating a new WROLPi -## Raspberry Pi +The following sections are the steps necessary to create a new WROLPi, either as a backup, or to restore your WROLPi +on new hardware. -The following instructions are the steps necessary to create a new WROLPi, either as a backup, or to restore your WROLPi -on a new Raspberry Pi. +### WROLPi Portable (Live USB) -### Image an SD Card on Linux +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](https://wrolpi.org). +2. Flash the whole drive with the ISO using [Raspberry Pi Imager](https://www.raspberrypi.com/software/), Rufus, 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. + +**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](#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-v0.19-aarch64-desktop.img.xz | sudo dd of=/dev/sdb status=progress` + * `xzcat WROLPi-v-aarch64-desktop.img.xz | sudo dd of=/dev/sdb status=progress` -### Image an SD Card on Windows +#### Image an SD Card on Windows 1. Copy the WROLPi image to your micro SD card using [Raspberry Pi Imager](https://www.raspberrypi.com/software/) -### First Boot +#### First Boot 1. Unplug your Raspberry Pi 2. Insert the micro SD card into your Raspberry Pi @@ -66,10 +96,7 @@ on a new Raspberry Pi. 13. A browser will open automatically. Follow the [Onboarding](#onboarding) steps above to select your drive and complete the installation. -## Debian - -The following instructions are the steps necessary to create a new WROLPi, either as a backup, or to restore your WROLPi -on a new Debian computer. +### Debian 1. Copy the Debian WROLPi ISO to a thumb-drive. 2. Insert the thumb-drive into the laptop, boot to the thumb-drive. diff --git a/docs/system/special-directories.md b/docs/system/special-directories.md index d62cbe7..0c0a425 100644 --- a/docs/system/special-directories.md +++ b/docs/system/special-directories.md @@ -23,14 +23,14 @@ The normal media directory is `/media/wrolpi` `/media/wrolpi/config/` This directory contains the configuration files of the WROLPi. These files are considered the "source of truth" and -their contents will alter the behavior of the WROLPi. +their contents will alter the behavior of the WROLPi. See [How Configs Work](configs.md). ## Tags Directory `/media/wrolpi/tags` This directory contains links to tagged files. It is automatically managed by WROLPi as you add or remove tags from -files. +files. See [Tags](tags.md). **Warning!** Do not store files in this directory, they will be automatically deleted. diff --git a/docs/system/tags.md b/docs/system/tags.md new file mode 100644 index 0000000..dd71824 --- /dev/null +++ b/docs/system/tags.md @@ -0,0 +1,109 @@ +# Tags + +A Tag is a named, colored label that you can attach to nearly anything in your WROLPi. Tags are the primary way to +organize your library across all modules. One item can have many Tags, and one Tag can be applied to many items. + +You can tag: + +* **Files** — any file WROLPi tracks: videos, archives, ebooks, PDFs, images, and so on. +* **Zim entries** — individual pages inside a Zim file (for example, a particular Wikipedia article). +* **Collections** — a Channel, Domain, or Playlist can have a single Tag (see + [Collections](collections/index.md)). + +## Creating and Editing Tags + +Tags are managed from the **Dashboard**. The Dashboard shows all of your Tags; click **Edit** to open the Tag editor. + +The Tag editor shows every Tag with counts of how many Files, Zims, Channels, and Domains use it. From here you can: + +1. **Create** a new Tag by entering a name and choosing a color (or click **Random** for a distinct color). A preview + shows what the Tag will look like. +2. **Edit** an existing Tag's name or color. +3. **Delete** a Tag using the trash button. + +You can also create Tags on the fly wherever the Tag selector appears (file previews, video player, etc.). + +### Tag name rules + +* Tag names must be unique, and cannot be empty. +* Tag names cannot contain a comma, or file-unsafe characters like `<`, `>`, `:`, `|`, `"`, `?`, `*`, `%`, or `!`. + This is because Tag names are used as directory names. +* A Tag **cannot be deleted while it is in use**. Remove it from all files, Zim entries, and Collections first. +* Renaming a Tag is safe: WROLPi automatically updates any Downloads that reference the Tag, and moves any Channel + directories named after the Tag (see [Tagged directories](#tagged-directories) below). + +## Tagging Files + +Wherever you view a file you can tag it: + +> Open any file's preview (or the video player) and use the Tag selector to add or remove Tags. + +Other ways to tag files: + +* **Bulk tagging**: select many files in the Files browser, then use the bulk tag tool to add or remove Tags on all + of them in one operation. A progress bar is shown for large batches. +* **Upload**: files can be tagged as they are uploaded. + +When deleting files that have Tags, WROLPi will ask for an extra confirmation. + +## Tagging Zim Entries + +While reading a Zim page (a Wikipedia article, for example) you can tag that specific page using the Tag selector. + +If you later replace a Zim file with a newer version (for example, this year's Wikipedia), WROLPi will automatically +migrate your tagged entries to the new Zim file. + +## Tagging Collections + +A Channel, Domain, or Playlist can be given **one** Tag. When tagging a Collection you can also choose to move its +files into a directory named after the Tag. + +### Tagged directories + +Tags control where some downloads are stored on disk: + +* A tagged Channel's videos are stored in `videos///` by default. +* A tagged Playlist's files are stored in `playlists///`. + +When you tag (or rename the Tag of) a Channel or Playlist, WROLPi will offer to move the files to the matching +directory, and warns you if the destination conflicts with an existing Collection. + +## Searching with Tags + +* **Click any Tag label** anywhere in the interface to search for everything with that Tag. +* The search pages (global Search, Files, Archives) have a Tag filter. Selecting multiple Tags finds items that have + **all** of the selected Tags. +* The **Any** button finds items that have at least one Tag (any Tag at all). +* The Tag selector suggests your **Recent Tags** and **Frequent Tags** (Tags often used together) to speed up + tagging. + +## The Tags Directory + +WROLPi maintains a `tags` directory in your media directory (`/media/wrolpi/tags/`). It contains links to every +tagged file, organized into directories named after the Tags. This is the +[secondary](primary-secondary-tertiary.md) way to access your tagged files — it works even if the WROLPi app is +down, and the links survive if you browse the drive on another computer. + +If a file has multiple Tags, its links are placed in a directory named with all of its Tags, sorted alphabetically +and separated by commas. For example, a video tagged with "WROL" and "Computers" is linked at +`tags/Computers, WROL/