diff --git a/docs/index.md b/docs/index.md index f230ca2..c2c6132 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,6 +2,17 @@ Here you will find information about WROLPi, it's modules and how to repair your WROLPi. +## WROLPi + +Information about a WROLPi system. + +* [Getting Started](system/getting-started.md) +* [Getting Help](system/getting-help.md) +* [Logs](system/logs.md) +* [Systems](system/index.md) +* [Recommended Hardware](system/recommended-hardware.md) +* [External USB Drives](system/external-drives.md) + ## Modules Information about the parts of the WROLPi interface. @@ -12,16 +23,6 @@ Information about the parts of the WROLPi interface. * [Map](modules/map/index.md) * [Zim](modules/zim/index.md) -## WROLPi - -Information about a WROLPi system. - -* [Getting Started](system/getting-started.md) -* [Getting Help](system/getting-help.md) -* [Logs](system/logs.md) -* [Systems](system/index.md) -* [Recommended Hardware](system/recommended-hardware.md) - ## Guiding Principals Principals that influence the design decisions of WROLPi. diff --git a/docs/modules/archives/files.md b/docs/modules/archives/files.md index cff6e1e..e01b47f 100644 --- a/docs/modules/archives/files.md +++ b/docs/modules/archives/files.md @@ -27,11 +27,11 @@ Archive files are named using three parts: If archiving `https://wrolpi.org/getting-started`, the resulting files might be named as follows: ``` -wrolpi.org/2023-01-01-12-00-00_Getting Started.html -wrolpi.org/2023-01-01-12-00-00_Getting Started.readability.html -wrolpi.org/2023-01-01-12-00-00_Getting Started.readability.txt -wrolpi.org/2023-01-01-12-00-00_Getting Started.readability.json -wrolpi.org/2023-01-01-12-00-00_Getting Started.png +/media/wrolpi/archive/wrolpi.org/2023-01-01-12-00-00_Getting Started.html +/media/wrolpi/archive/wrolpi.org/2023-01-01-12-00-00_Getting Started.readability.html +/media/wrolpi/archive/wrolpi.org/2023-01-01-12-00-00_Getting Started.readability.txt +/media/wrolpi/archive/wrolpi.org/2023-01-01-12-00-00_Getting Started.readability.json +/media/wrolpi/archive/wrolpi.org/2023-01-01-12-00-00_Getting Started.png ``` WROLPi will attempt to extract the Readability and create a screenshot from the Singlefile. If this is not possible, diff --git a/docs/modules/map/index.md b/docs/modules/map/index.md index 461dca2..cbddb15 100644 --- a/docs/modules/map/index.md +++ b/docs/modules/map/index.md @@ -31,22 +31,30 @@ save them to the `map` directory. After they have been downloaded, you will need You can manually import a PBF file using the **import_map.sh** script: -`/opt/wrolpi/scripts/import_map.sh /media/wrolpi/map/austria-231121.osm.pbf` +```shell +/opt/wrolpi/scripts/import_map.sh /media/wrolpi/map/austria-231121.osm.pbf +``` Multiple maps can be imported like so: -`/opt/wrolpi/scripts/import_map.sh /media/wrolpi/map/one.osm.pbf /media/wrolpi/map/two.osm.pbf /media/wrolpi/map/three.osm.pbf` +```shell +/opt/wrolpi/scripts/import_map.sh /media/wrolpi/map/one.osm.pbf /media/wrolpi/map/two.osm.pbf /media/wrolpi/map/three.osm.pbf +``` ## Reset Map If your map is not working, maps cannot be imported, or some other reason, you can reset the map database using the reset script: -`/opt/wrolpi/scripts/reset_map.sh` +```shell +/opt/wrolpi/scripts/reset_map.sh +``` Next, run the repair script: -`/opt/wrolpi/repair.sh` +```shell +/opt/wrolpi/repair.sh +``` -Browse to your map, you should see the default map. If you do not, you may need to clear your browse's cache. Next, +Browse to your map, you should see the default map. If you do not, you may need to clear your browse's cache. Finally, import your desired maps. \ No newline at end of file diff --git a/docs/modules/videos/files.md b/docs/modules/videos/files.md index e69de29..82522bc 100644 --- a/docs/modules/videos/files.md +++ b/docs/modules/videos/files.md @@ -0,0 +1,37 @@ +# Video Files + +WROLPi creates several files when downloading a video: + +1. A video file. +2. Caption files. The suffix may be prefixed with the language like so: `.en.vtt` or `.es.vtt` +3. An "info" json file. This file contains large amounts of information about the video: Channel name, Source ID, + comments, Like count, etc. +4. A poster file (thumbnail). + +These files all share the same filename but have different suffixes. + +| File Suffix | Purpose | +|-------------|------------------------------| +| .mp4 | The video. | +| .vtt | The captions. | +| .info.json | Information about the video. | +| .jpg | The poster (thumbnail). | + +Video files are named using three parts: + +1. The Channel Name. +2. The Published Date (upload date). +3. The Source ID (a unique string of characters linking to the video, i.e `0xfMLNVFq2Y`) +4. The title of the video. + +The above order is important, it allows the videos to be viewed chronologically in the file browser. The Source ID +is important because it prevents a conflict if a Channel uploads a video with the same name on the same day. + +Example file names for a video: + +``` +/media/videos/wrolpi/WROLPi_20230909_0xfMLNVFq2Y_WROLPi v0.11 beta demo.mp4 +/media/videos/wrolpi/WROLPi_20230909_0xfMLNVFq2Y_WROLPi v0.11 beta demo.en.vtt +/media/videos/wrolpi/WROLPi_20230909_0xfMLNVFq2Y_WROLPi v0.11 beta demo.info.json +/media/videos/wrolpi/WROLPi_20230909_0xfMLNVFq2Y_WROLPi v0.11 beta demo.jpg +``` \ No newline at end of file diff --git a/docs/modules/videos/index.md b/docs/modules/videos/index.md index e935005..c41e3c4 100644 --- a/docs/modules/videos/index.md +++ b/docs/modules/videos/index.md @@ -8,6 +8,8 @@ Videos Module (`/videos`) allows browsing all video files. In the context of WROLPi, a Video refers to a set of [similarly named files](files.md) created during download. A single video file is also supported. +![video-page.png](video-page.png) + ## Video Format As of the writing of this article, WROLPi favors MP4 files due to their small size and universal support. @@ -67,4 +69,19 @@ When the indexes for a Video are generated for searching, they are searched in t 1. Title 2. Description -3. Subtitles \ No newline at end of file +3. Subtitles + +## Videos without WROLPi + +WROLPi comes with VLC pre-installed, this application allows you to watch video files, even if the React App is not +working. VLC also displays captions when the caption file is named like the video file (see +[Video Files](../videos/files.md)). + +### Raspberry Pi + +VLC can be launched by navigating: `Applicaions Menu > Sound & Video > VLC Media Player` + +![wrolpi-launch-vlc.png](wrolpi-launch-vlc.png) + +Any video file can be opened by navigating `Media > Open File`. VLC will automatically display captions files that +WROLPi has downloaded. \ No newline at end of file diff --git a/docs/modules/videos/video-page.png b/docs/modules/videos/video-page.png new file mode 100644 index 0000000..c3e8443 Binary files /dev/null and b/docs/modules/videos/video-page.png differ diff --git a/docs/modules/videos/wrolpi-launch-vlc.png b/docs/modules/videos/wrolpi-launch-vlc.png new file mode 100644 index 0000000..3b08158 Binary files /dev/null and b/docs/modules/videos/wrolpi-launch-vlc.png differ diff --git a/docs/modules/zim/index.md b/docs/modules/zim/index.md index 50cc1b0..322ab30 100644 --- a/docs/modules/zim/index.md +++ b/docs/modules/zim/index.md @@ -28,4 +28,18 @@ WROLPi will search any Zim file found in the `zims` directory, but not every pro subscription list. If you would like to download a specific Zim file, use the **Files Downloader** and save the file to the `zims` directory. (You may need to restart your WROLPi for the new Zim file to be found.) -![Downloading a Zim file using the Files Downloader](zim-file-downloader.png) \ No newline at end of file +![Downloading a Zim file using the Files Downloader](zim-file-downloader.png) + +## Kiwix without WROLPi + +WROLPi comes with Kiwix pre-installed, this application allows you to use your zim files even if the React App is not +working. + +### Raspberry Pi + +Kiwix can be started by navigating: `Applications Menu > Education > Kiwix` + +![kiwix-rpi-application-start.png](kiwix-rpi-application-start.png) + +Any zim file can be opened using the "Open" button on the top right of the Kiwix application. Zim files are usually +stored in `/media/wrolpi/zims`. \ No newline at end of file diff --git a/docs/modules/zim/kiwix-rpi-application-start.png b/docs/modules/zim/kiwix-rpi-application-start.png new file mode 100644 index 0000000..e581391 Binary files /dev/null and b/docs/modules/zim/kiwix-rpi-application-start.png differ diff --git a/docs/other/ebooks.md b/docs/other/ebooks.md index ab3d76c..09b071c 100644 --- a/docs/other/ebooks.md +++ b/docs/other/ebooks.md @@ -3,7 +3,13 @@ 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. -Epub files are desired as ebooks, though some support for Mobi files is provided. +Epub files are desired as ebooks, though some support for Mobi files is provided. Reasons why WROLPi supports 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. +* Because an Epub contains HTML files, it makes it easy to display them in a web browser. ## Searching diff --git a/docs/system/external-drives.md b/docs/system/external-drives.md new file mode 100644 index 0000000..cf8ceaf --- /dev/null +++ b/docs/system/external-drives.md @@ -0,0 +1,45 @@ +# External USB Drive Configuration + +WROLPi expects a single USB drive to be mounted at `/media/wrolpi`. However, multiple drives are supported. WROLPi +uses special directories to know where to place downloaded files. The config special directories cannot be changed +and WROLPi will always look for it at `/media/wrolpi/config` + +The default special directories are the following (the inputs are disabled because the "Edit Directories" toggle +is not checked): + +![Special Directories Settings](special-directories-settings.png) + +## 2+ drives + +As of the writing of this article, WROLPi partially supports multiple drives. The _primary_ drive must be mounted to +`/media/wrolpi`, the configs will be written to this drive. The other drive must be mounted within `/media/wrolpi`. + +If you wanted your _secondary_ drive named "secondary", you could mount it at `/media/wrolpi/secondary`. Linux will +ensure the files are placed in the correct drives. + +### Migrating from one to two drives + +Assuming that you have a WROLPi with a single external hard drive, and would like to add a second drive, follow these +steps. + +1. Mount the _secondary_ drive to some path in `/media/wrolpi`. We will assume you use `/media/wrolpi/secondary` for + this example. Follow this pattern for all new drives. + 1. `mkdir /media/wrolpi/secondary` + 2. `mount /dev/sdb1 /media/wrolpi/secondary` +2. Decide where WROLPi will download files. + 1. WROLPi will download videos to `/media/wrolpi/videos` by default. If you want WROLPi to save new videos to + the secondary drive, edit the "Videos Directory" in `Admin > Settings > Special Directories` to something like + `secondary/videos`. + 2. Do this for all special directories. + 3. You can keep all special directories in the _primary_ drive, WROLPi will still search the _secondary_ drive for + any new files. +3. Make the drive mounts permanent by modifying `/etc/fstab`: + + ``` + /dev/sda1 /media/wrolpi auto defaults,nofail 0 0 # primary + /dev/sdb /media/wrolpi/secondary auto defaults,nofail 0 0 # secondary + ``` + +4. Verify that the mounts are correct by rebooting. + - `sudo reboot` +5. [Refresh your files](../modules/files/index.md#refreshing) \ No newline at end of file diff --git a/docs/system/getting-started.md b/docs/system/getting-started.md index 50756e2..39799ae 100644 --- a/docs/system/getting-started.md +++ b/docs/system/getting-started.md @@ -4,13 +4,15 @@ To finish your WROLPi installation follow these steps: -1. Modify fstab to mount your external drive. In the example below, `/dev/sda1` will be mounted to `/media/wrolpi` +1. Modify fstab to mount your external drive(s). In the example below, `/dev/sda1` will be mounted to `/media/wrolpi` 1. `echo '/dev/sda1 /media/wrolpi auto defaults,nofail 0 0' | sudo tee -a /etc/fstab` 2. Finish the installation with the repair script: `sudo bash /opt/wrolpi/repair.sh` 3. Reboot: `sudo reboot` 4. After reboot, browse to `http://wrolpi.local` or `http://127.0.0.1` on the WROLPi itself. 5. [Refresh your files](../modules/files/index.md#refreshing) +[Support for multiple drives](external-drives.md) + # Creating a new WROLPi ## Raspberry Pi diff --git a/docs/system/logs.md b/docs/system/logs.md index aff1a51..391c3fd 100644 --- a/docs/system/logs.md +++ b/docs/system/logs.md @@ -5,15 +5,21 @@ gathered by `systemd`. Logs are viewed using `journalctl`. You can watch all the logs on your WROLPi: -`journalctl -f` +```shell +journalctl -f +``` More detailed logs can be viewed: -`journalctl -f -p debug` +```shell +journalctl -f -p debug +``` To view logs only from the most recent boot: -`journalctl -f -b` +```shell +journalctl -f -b +``` The above commands use `-f` (follow) which will display logs as soon as they are created. You can view older logs by removing `-f` from the command, but you will need to use your keyboard to navigate the logs. Use `up`, `down`, @@ -24,22 +30,30 @@ the bottom of the logs. To watch the API logs: -`journalctl -f -u wrolpi-api` +```shell +journalctl -f -u wrolpi-api +``` ## React App To watch the React App logs: -`journalctl -f -u wrolpi-app` +```shell +journalctl -f -u wrolpi-app +``` ## Map To watch the Map logs: -`journalctl -f -u renderd` +```shell +journalctl -f -u renderd +``` ## Zim To watch the React App logs: -`journalctl -f -u wrolpi-kiwix` +```shell +journalctl -f -u wrolpi-kiwix +``` diff --git a/docs/system/primary-secondary-tertiary.md b/docs/system/primary-secondary-tertiary.md index b31726c..64ce4d4 100644 --- a/docs/system/primary-secondary-tertiary.md +++ b/docs/system/primary-secondary-tertiary.md @@ -3,10 +3,11 @@ WROLPi attempts to integrate all services in an easy to learn interface. But, if the React app is unavailable, secondary and tertiary options to use your WROLPi may be available. -| Module | Primary | Secondary | Tertiary | -|----------|-----------|---------------------------------------------------------|-----------------------------------------------------| -| Videos | React App | Open video files with VLC. | Open subtitle files with a text editor. | -| Archives | React App | Open Archive files directly with Chromium | Readability files can be opened with a text editor. | -| Map | React App | Map is directly accessible on port `:8084` | None | -| Zim | React App | Kiwix server is directly accessible on port `:8085` | Kiwix application | -| Help | React App | Markdown files are available in `/opt/wrolpi-help/docs` | None | +| Module | Primary | Secondary | Tertiary | +|----------|-------------------------------------------|--------------------------------------------------------------------------------|-------------------------------------------------------------------| +| Videos | [React App](../modules/videos/index.md) | [Open video files with VLC.](../modules/videos/index.md#videos-without-wrolpi) | Open subtitle files with a text editor. | +| Archives | [React App](../modules/archives/index.md) | Open Archive files directly with Chromium | Readability files can be opened with a text editor. | +| Map | [React App](../modules/map/index.md) | Map is directly accessible on port `:8084` | None | +| Zim | [React App](../modules/zim/index.md) | Kiwix server is directly accessible on port `:8085` | [Kiwix application](../modules/zim/index.md#kiwix-without-wrolpi) | +| Help | [React App](../..) | Markdown files are available in `/opt/wrolpi-help/docs` | None | + diff --git a/docs/system/special-directories-settings.png b/docs/system/special-directories-settings.png new file mode 100644 index 0000000..2d01ac0 Binary files /dev/null and b/docs/system/special-directories-settings.png differ diff --git a/docs/system/systemd.md b/docs/system/systemd.md index 5a87544..7cb1b9c 100644 --- a/docs/system/systemd.md +++ b/docs/system/systemd.md @@ -1,10 +1,12 @@ # Service Control +WROLPi services are controlled by `systemd`. + You can view and control the WROLPi services using these commands: -| Service | Status | Logs | Restart | Stop | Start | -|-----------|---------------------------------|---------------------------|----------------------------------|-------------------------------|--------------------------------| -| API | `systemctl status wrolpi-api` | `journalctl wrolpi-api` | `systemctl restart wrolpi-api` | `systemctl stop wrolpi-api` | `systemctl start wrolpi-api` | -| React App | `systemctl status wrolpi-app` | `journalctl wrolpi-app` | `systemctl restart wrolpi-app` | `systemctl stop wrolpi-app` | `systemctl start wrolpi-app` | -| Map | `systemctl status renderd` | `journalctl renderd` | `systemctl restart renderd` | `systemctl stop renderd` | `systemctl start renderd` | -| Zim | `systemctl status wrolpi-kiwix` | `journalctl wrolpi-kiwix` | `systemctl restart wrolpi-kiwix` | `systemctl stop wrolpi-kiwix` | `systemctl start wrolpi-kiwix` | +| Service | Status | Logs | Restart | Stop | Start | +|-----------|---------------------------------|------------------------------|----------------------------------|-------------------------------|--------------------------------| +| API | `systemctl status wrolpi-api` | `journalctl -u wrolpi-api` | `systemctl restart wrolpi-api` | `systemctl stop wrolpi-api` | `systemctl start wrolpi-api` | +| React App | `systemctl status wrolpi-app` | `journalctl -u wrolpi-app` | `systemctl restart wrolpi-app` | `systemctl stop wrolpi-app` | `systemctl start wrolpi-app` | +| Map | `systemctl status renderd` | `journalctl -u renderd` | `systemctl restart renderd` | `systemctl stop renderd` | `systemctl start renderd` | +| Zim | `systemctl status wrolpi-kiwix` | `journalctl -u wrolpi-kiwix` | `systemctl restart wrolpi-kiwix` | `systemctl stop wrolpi-kiwix` | `systemctl start wrolpi-kiwix` |