mirror of
https://github.com/wrolpi/wrolpi-help.git
synced 2026-10-25 18:40:11 -04:00
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>
This commit is contained in:
Roland
parent
002e747fba
commit
217ff68098
12 changed files with 564 additions and 27 deletions
|
|
@ -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.
|
||||
|
|
|
|||
109
docs/modules/downloads/index.md
Normal file
109
docs/modules/downloads/index.md
Normal file
|
|
@ -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/<channel tag>/<channel name>/` — the Channel is created automatically if needed. Videos without a
|
||||
channel go to `videos/NO CHANNEL/`.
|
||||
* Archives: `archive/<domain>/` — 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.
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
4. Text
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
90
docs/system/configs.md
Normal file
90
docs/system/configs.md
Normal file
|
|
@ -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.
|
||||
91
docs/system/filegroups.md
Normal file
91
docs/system/filegroups.md
Normal file
|
|
@ -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).
|
||||
|
|
@ -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<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](#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<version>-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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
109
docs/system/tags.md
Normal file
109
docs/system/tags.md
Normal file
|
|
@ -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/<tag>/<channel name>/` by default.
|
||||
* A tagged Playlist's files are stored in `playlists/<tag>/<playlist name>/`.
|
||||
|
||||
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/<video files>`. All files of the [FileGroup](filegroups.md) (the video, its poster, captions,
|
||||
etc.) are linked together.
|
||||
|
||||
**Warning!** Do not store your own files in the `tags` directory — it is managed automatically by WROLPi and extra
|
||||
files will be deleted.
|
||||
|
||||
> The Tags Directory can be turned off in the WROLPi Settings (`tags_directory`) if you do not want it.
|
||||
|
||||
## Where Tags are Stored
|
||||
|
||||
Tags are stored in the `tags.yaml` [config file](configs.md) in your config directory. It records every Tag (with
|
||||
its color), every tagged file, and every tagged Zim entry. Like all WROLPi configs, this file is the source of
|
||||
truth:
|
||||
|
||||
* Your Tags survive a database rebuild — on startup (or config import) WROLPi re-creates Tags and re-applies them to
|
||||
your files.
|
||||
* You can hand-edit `tags.yaml` (for example, to add a Tag) and WROLPi will apply the change on the next startup or
|
||||
import.
|
||||
* A Tag removed from the config will only be deleted if it is no longer used by anything.
|
||||
|
||||
Because `tags.yaml` travels with your media drive, your Tags come along when you move the drive to a new WROLPi.
|
||||
83
docs/system/upgrade.md
Normal file
83
docs/system/upgrade.md
Normal file
|
|
@ -0,0 +1,83 @@
|
|||
# Upgrading WROLPi
|
||||
|
||||
WROLPi can upgrade itself from the internet. Your library, configs, and database are not touched by an upgrade —
|
||||
only the WROLPi software in `/opt/wrolpi` is replaced.
|
||||
|
||||
Your WROLPi's current version is shown at the bottom of every page, and in the **Settings** page under **Upgrade**.
|
||||
|
||||
## Checking for Updates
|
||||
|
||||
> Open **Settings**, find the **Upgrade** section, and click **Check for Upgrades**.
|
||||
|
||||
When an upgrade is available, a green up-arrow appears in the navigation bar linking to the Upgrade section.
|
||||
|
||||
## Upgrading a Raspberry Pi or Debian WROLPi
|
||||
|
||||
Both Raspberry Pi and Debian WROLPi's upgrade the same way.
|
||||
|
||||
### From the browser (recommended)
|
||||
|
||||
1. Open **Settings** and find the **Upgrade** section.
|
||||
2. Click **Check for Upgrades**, then **Upgrade Now**.
|
||||
3. Your browser is redirected to the [Controller](../controller/index.md), which stays online during the upgrade so
|
||||
you can watch the progress and service logs.
|
||||
4. When the upgrade completes and all services are running again, you are redirected back to the main interface.
|
||||
|
||||
### From the command line
|
||||
|
||||
```shell
|
||||
sudo /bin/bash /opt/wrolpi/upgrade.sh
|
||||
```
|
||||
|
||||
If the upgrade script is missing (very old WROLPi), run the installer instead — it also acts as an upgrade:
|
||||
|
||||
```shell
|
||||
sudo /bin/bash /opt/wrolpi/install.sh
|
||||
```
|
||||
|
||||
### What an upgrade does
|
||||
|
||||
1. The Controller is upgraded first, so you can monitor the rest of the upgrade even while other services are down.
|
||||
2. The API and App services are stopped. **The interface will be unavailable for several minutes.**
|
||||
3. The latest WROLPi code is downloaded. Every release is **GPG-signed** — the upgrade refuses to install code that
|
||||
is not signed by the WROLPi maintainer.
|
||||
4. Dependencies are upgraded and database migrations are applied.
|
||||
5. The upgrade finishes by running the [repair script](getting-help.md), then all services are restarted.
|
||||
|
||||
**Warning!** The upgrade requires the internet, and discards any manual changes you have made to files in
|
||||
`/opt/wrolpi`. Your media files and [configs](configs.md) are never touched.
|
||||
|
||||
## Upgrading a WROLPi Portable USB
|
||||
|
||||
A WROLPi Portable USB is upgraded by re-flashing only the boot portion of the USB drive — your `persistence`
|
||||
partition (library, database, and configuration) is preserved.
|
||||
|
||||
From any Linux computer:
|
||||
|
||||
1. Download the new `WROLPi-v*-amd64.iso` from [wrolpi.org](https://wrolpi.org).
|
||||
2. Plug in your WROLPi Portable USB and identify its device with `lsblk`.
|
||||
3. Run the upgrade tool from the WROLPi repository:
|
||||
* `sudo ./scripts/wrolpi-usb.sh upgrade WROLPi-v<version>-amd64.iso /dev/sdX`
|
||||
4. Eject the drive and boot it to verify the upgrade.
|
||||
|
||||
## Upgrading Docker
|
||||
|
||||
In-app upgrades are not available in Docker environments; upgrade the containers manually:
|
||||
|
||||
1. `docker-compose stop`
|
||||
2. `git pull origin master --ff`
|
||||
3. `docker-compose build --parallel`
|
||||
4. `docker-compose up -d db`
|
||||
5. `docker-compose run --rm api db upgrade`
|
||||
6. `docker-compose up -d`
|
||||
|
||||
## If Something Goes Wrong
|
||||
|
||||
* The upgrade log is written to `/opt/wrolpi/upgrade.log`, and can be followed live with:
|
||||
* `journalctl -fu wrolpi-upgrade.service`
|
||||
* The [repair script](getting-help.md) is offline-safe and fixes most problems:
|
||||
* `sudo /opt/wrolpi/repair.sh`
|
||||
* Check the health of your WROLPi with:
|
||||
* `/opt/wrolpi/help.sh`
|
||||
|
||||
See [Getting Help](getting-help.md) for more.
|
||||
Loading…
Add table
Add a link
Reference in a new issue