Daniel J. Summers
0c87392910
- Change to SQLite document store - Complete documentation on usage of Feed Reader Central - Update INSTALLING.md for new installation procedures Reviewed-on: #23
74 lines
5.1 KiB
PHP
74 lines
5.1 KiB
PHP
<?php declare(strict_types=1);
|
|
|
|
include '../../start.php';
|
|
|
|
FeedReaderCentral\Security::verifyUser(redirectIfAnonymous: false);
|
|
|
|
page_head('Feeds | Documentation'); ?>
|
|
<h1>Feeds</h1>
|
|
<p class=back-link><?=hx_get('./', '⟨⟨ Documentation Home')?>
|
|
<article class=docs>
|
|
<h2>Adding a Feed</h2>
|
|
<p>On the top menu bar, click the <strong>Feeds</strong> link, then click the <strong>Add Feed</strong> button. In
|
|
the field that is displayed, enter the
|
|
<abbr title="Uniform Resource Locator (aka “link”)">URL</abbr> for the feed. Then click the
|
|
<strong>Save</strong> button; if all goes well, the application will subscribe to the feed and pull in all its
|
|
current items.
|
|
<p>If you do not have the feed’s direct link, you can enter the URL for the site that hosts the feed. In most
|
|
cases, the application should be able to find it and subscribe to it.
|
|
<h2>Editing a Feed’s URL</h2>
|
|
<p>If the feed to which you are subscribed has moved, you can edit the URL of the feed. In this case, the
|
|
application will confirm that the new feed exists and will synchronize with its items. Depending on how the feed
|
|
was moved, this may result in items reappearing as new; however, bookmarked items will not be removed, and older
|
|
items will not be removed until they would otherwise have been pruned.
|
|
<h2>Deleting a Feed</h2>
|
|
<p>On the <strong>Feeds</strong> page, below each feed’s title, there is a <strong>Delete</strong> link at the
|
|
end of the line. Once that is clicked, you will be prompted to confirm that you really mean to delete this feed;
|
|
if you confirm the deletion, the feed and all its items (including bookmarked items) will be deleted.
|
|
<h2>Refreshing Feeds</h2>
|
|
<p>Feeds are pulled when their subscriptions are added; however, a one-time pull of feeds does not keep us up to
|
|
date on future posts. From within the application, feeds can be updated manually; there is also a way to set up
|
|
a job to regularly refresh feeds.
|
|
<h3>Manual Refresh</h3>
|
|
<p>Next to the “Your Unread Items” heading on the main page, there is a link labeled
|
|
<strong>Refresh All Feeds</strong>. Clicking this link will reload the main page once the feeds have been
|
|
refreshed. Depending on the number and size of feeds, this may take a bit of time; each feed is refreshed
|
|
individually.
|
|
<h3>Automatic Refresh Job <em>(Linux / Mac)</em></h3>
|
|
<p>The <code>refresh</code> utility script will perform this refresh from the CLI. As it runs, it will list the
|
|
feeds as it processes them, and if it encounters any errors, that is noted as well. This process can be
|
|
automated via <code>cron</code> on Linux or Mac systems. This is most easily implemented by writing a small
|
|
shell script to provide some environment settings, then telling <code>cron</code> to run that script.
|
|
<pre class=item_content>
|
|
#!/bin/bash
|
|
exec 1> >(logger -t feed-reader-central) 2>&1
|
|
cd /path/to/frc
|
|
php-cli util/refresh.php all</pre>
|
|
<p>Save this (<code>frc-refresh.sh</code> might be a good name) and be sure it is executable
|
|
(<code>chmod +x ./frc-refresh.sh</code>). Before we put it in crontab, though, let’s understand what each
|
|
line does:
|
|
<ul>
|
|
<li>Line 1 tells the operating system to use the <code>bash</code> shell.
|
|
<li>Line 2 directs all output to the system log (<code>/var/log/syslog</code>), labeling each entry with
|
|
<code>feed-reader-central</code>. This lets you review the output for its runs in a log that is already
|
|
maintained and rotated by the operating system.
|
|
<li>Line 3 changes the current directory to the one where Feed Reader Central is installed; modify it for where
|
|
you have installed it. Since we are setting up for a <a href=./the-cli>CLI execution</a>, this should place
|
|
us one directory up from <code>/public</code>.
|
|
<li>Line 4 executes the refresh script.
|
|
</ul>
|
|
<p>Finally, we are ready to add this to our crontab. Enter <code>crontab -e</code> to edit the file, then add a row
|
|
at the bottom that looks like this:
|
|
<pre class=item_content>
|
|
0 */6 * * * /path/to/job/frc-refresh.sh</pre>
|
|
<p>The items before the path specify when it should run. This example will run at the top of the hour every six
|
|
hours. Crontab schedules can be tricky to create; a full treatment is outside the scope of this documentation.
|
|
However, <a href=https://crontab.guru/#0_*/6_*_*_* target=_blank rel=noopener title="Crontab.guru">this site</a>
|
|
lets you put values in each position and it translates that to words; this lets you see if what you put is what
|
|
you meant.
|
|
<p>This should not require many resources; the majority of its time will be spent waiting for the websites to return
|
|
their feeds so it can process them. However, if you want it to yield to everything else happening on the server,
|
|
add <code>nice -n 1</code> (with a trailing space) before the path to the script.
|
|
</article><?php
|
|
page_foot();
|